English

Using OAuth

The OAuth 2.0 Authorization Framework enables user to authorize your application to get user's information or access API methods otherwise not accessible by default client credentials.

OAuth 2 rely on separate standards for the access tokens. In Wallet API MAC access authentication is used - the same protocol that is available for client authentication.

Currently two grant types are available:

authorization code grant - used on web systems, recommended method

resource owner password credentials grant - used on mobile and desktop programs, only allowed for specific clients

Using authorization code grant

To use OAuth authorization code grant, client should follow these steps:
  1. Redirect user to authentication endpoint with client_id parameter and redirection URI;
  2. After user authenticates in the Paysera system, she is redirected to provided redirection URI together with parameter code;
  3. Client makes API request to the token endpoint providing the code parameter. Response contains access_token and mac_key parameters;
  4. Client makes API requests, using access_token and mac_key instead of default credentials for MAC authentication scheme.

Confirming transaction and redirecting to authentication

In case you want User to confirm transaction and immediately grant permissions to requested scopes, please use following endpoint.

Firstly User will be asked to confirm given transaction, if confirmation succeeds, User will be redirected to OAuth authentication endpoint.

https://www.paysera.com/frontend/transaction/confirm-with-oauth/:transaction_key

URI parameters:

Query parameters:

Same Query parameters are supported as in authentication endpoint.

Redirecting user to authentication endpoint

User must be redirected to the following URI, providing required parameters in query:

https://www.paysera.com/frontend/oauth

To control the default web page language, redirection can be made to the following URI:

https://www.paysera.com/frontend/locale/oauth

Where locale is one of the following:

en - for English language

lt - for Lithuanian language

ru - for Russian language

Together with URI some query parameters must be provided.

Parameter
Type
Remarks
Description
response_type
string
required
Currently only code is supported
client_id
string
required
client_id parameter, provided with credentials for client
redirect_uri
string
required if not provided in project configuration
URI to redirect the user after authorization. If not set, the one provided in the system will be used
scope
string
optional
Needed scopes if default one is not enough. You can separate scopes with spaces
state
string
recommended
Paysera system will include this parameter when redirecting the user back to your site. This parameter should be used to prevent cross-site request forgery
Example redirection URI: 
https://www.paysera.com/frontend/oauth?response_type=code&client_id=wkVd93h2uS&redirect_uri=http%3A%2F%2Flocalhost%2Fabc&state=iQZMRnQCtm

Redirection back to client's site

After user authorizes project, she will be redirected to the provided redirection_uri. code and state (if it was provided) parameters will be sent together with the URI. For example: 
HTTP/1.1 302 Found
Location: http://localhost/abc?code=SplxlOBeZQQYbYS6WxSbIA&state=iQZMRnQCtm
In the case of canceling authorization request or some other error, user will be redirected to the redirection_uri with these query parameters:
  • error - type of an error. One of: invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable
  • state - the same as was passed during redirect to authorization endpoint
For example: 
HTTP/1.1 302 Found
Location: http://localhost/abc?error=access_denied&state=iQZMRnQCtm

Requesting access token

Token endpoint: 
https://wallet.paysera.com/oauth/v1/token
After confirming the state parameter, you can request access token by providing code parameter. POST request must be made to the token endpoint by adding the following parameters using the application/x-www-form-urlencoded format in the HTTP request body:
  • grant_type - always authorization_code;
  • code - the code that you have got when user was redirected back to your site;
  • redirect_uri - exactly the same as was included in the authorization redirect.
API request must be authenticated using one of available methods, like in any other API request. For example: 
POST /oauth/v1/token HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/x-www-form-urlencoded;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="ElTV7TYXQrZrBe0tL6PtqvH6EI15iBSd/JvAkpMoH64=", ext="body_hash=IftzxAtYliLQx46c2JAPidlHKqck0OXD7KmsHNnSptU%3D"
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=http%3A%2F%2Flocalhost%2Fabc
Response contains new credentials to use for API calls, related to the current user and her wallet:
  • access_token - value to use instead of client_id in API calls;
  • token_type - always mac;
  • expires_in - access token expiration timeout in seconds;
  • mac_key - value to use instead of default mac_key in API calls;
  • mac_algorithm - algorithm to use when calculating mac. Always hmac-sha-256;
  • refresh_token - value to use for renewing expired token. This item is optional and can be missing.
For example: 
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
    "access_token": "SlAV32hkKG",
    "token_type": "mac",
    "expires_in": 3600,
    "mac_key": "adijq39jdlaska9asud",
    "mac_algorithm": "hmac-sha-256",
    "refresh_token": "0UnzbsnOLSkC7ftN"
}
Info When redirected to authentication endpoint, user selects account to relate to the project. Therefore authorization code grant access token is related to some specific wallet.

Passing confirmed user information to ease registration

Info This feature is not available by default and is enabled only for some clients

If your project has special privilege, you can provide already confirmed user information to ease registration process - user will not have to confirm his/her email or/and phone once again.

Request

POST https://wallet.paysera.com/rest/v1/contact-token

Request body structure

Request body must be encoded in JSON - same as in most other API requests. Confirmed contact will be valid for 15 minutes after creation.
Parameter
Type
Remarks
Description
email
string
required if no phone provided
Confirmed email address
phone
string
required if no email provided
Confirmed phone number

Response data structure

Parameter
Type
Remarks
Description
email
string
always
Confirmed email address
phone
string
always
Confirmed phone number
status
string
always
Confirmed contact status
token
string
always
Confirmed contact token
expires_at
integer
always
Confirmed contact expiration timestamp
Statuses

accessToken - optional; access token identifier, used as MAC id parameter. Can be omitted if request is made with the access token itself.

Example request

DELETE /oauth/v1/token?access_token=SlAV32hkKG HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="qtfqgX6EaE0nSHP9fN9ItmTNWqmr1Jkal7IOJbglOOE="