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
new
New created confirmed contact with validity of 15 minutes
Redirecting to authorization endpoint
After creating contact token, redirect user to the corresponding endpoint which requires user contact confirmation with contact_token in query string: 
https://www.paysera.com/frontend/en/wallet/confirm/pDAlAZ3z?contact_token=SnaKM0o40CIMZTr8WWE9yahyybn7Sqhk
Info You can also provide other endpoints which require users phone or email confirmation
Parameters
contact_token
token parameter from contact token creation method response
No other query parameters are needed - all needed information was passed when creating the confirmed contact token.
Example request
POST /rest/v1/contact-token HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="YkGFImxADv/etXHZfqaly1n4gsuUS9YVebZ6Z73eKWE=", ext="body_hash=4H7ZXzCAgSYtpX3Pvsqi5%2F3cPVze2cOj3h1ALDBtXAs%3D"
{
    "email": "email@example.com",
    "phone": "+123456789"
}
Example response
HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "email": "email@example.com",
    "phone": "+123456789",
    "status": "new",
    "token": "SnaKM0o40CIMZTr8WWE9yahyybn7Sqhk",
    "expires_at": "1435226105"
}

Using resource owner password credentials grant

Info This feature is not enabled by default and is unavailable for web-based clients at all

Resource owner password credentials grant is allowed only for specific projects and is not recommended to use. User must give her username and password which can be exchanged for an access token.

Requesting access token

Token endpoint: 
https://wallet.paysera.com/oauth/v1/token
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 password;
  • username - username of the user;
  • password - password of the user;
  • scope - optional, space separated list of scopes. You must request only those scopes that are required for your application to run.
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="5ojXh9Bdk6lvycu0oFLaLu7R6zDOoS0RdYzzbCJLIgg=", ext="body_hash=idZpyAYcVaQLJFMoGIv612GXxLXwGDcoHQmKUG9r%2Fe8%3D"
grant_type=password&username=user1&password=secret&scope=balance
Response contains new credentials to use for API calls, related to the current user:
  • access_token - value to use instead of client_id in API calls;
  • token_type - always mac;
  • expires_in - access token expiry 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"
}

Errors

user_error_limit_exceeded (status code 400, if this user is blocked due to too many password errors), invalid_grant (status code 400, if password is incorrect), rate_limit_exceeded (status code 400, if current client made too many invalid requests with user credentials in some period of time).

Using refresh token

When access token expires, client can exchange refresh_token value to a new access token. refresh_token is provided together with access token response. It is valid only for exchanging to a new access token, client cannot make other requests to API using it. It is valid for a longer period of time than the access token itself.

After getting access token via other methods, save refresh_token value with other credentials. If invalid_grant error has been get when making standard API calls, renew an access token using this method.

Requesting access token

Token endpoint: 
https://wallet.paysera.com/oauth/v1/token
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 refresh_token;
  • refresh_token - value of refresh token, which was provided when issuing an access token;
  • scope - optional, space separated list of scopes. If not provided, scope is not changed. If provided, it must be equal or a subset of the original scope, unless code parameter is provided.
  • code - optional, used for extending current scope. This is the code, sent to the user (usually by SMS) and related to the concrete scopes that are additionally requested. invalid_code error code is returned if code is not valid or expired
Request must be authenticated. 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="vvBzS4/26BhTpYvC3iSnr3sCSSfvKb+/W23qcpVwtpg=", ext="body_hash=CMOMCMxmRfRhw3n4WsVaqlOcV1zvy571AJOyx96I7VY%3D"
grant_type=refresh_token&refresh_token=0UnzbsnOLSkC7ftN
Response contains new credentials to use for API calls, related to the current user:
  • access_token - value to use instead of client_id in API calls;
  • token_type - always mac;
  • expires_in - access token expiry 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"
}

Revoking access token

Request

DELETE https://wallet.paysera.com/oauth/v1/token?access_token=:accessToken

Parameters

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="