ePayServices OpenApi (v1)

Introduction

Welcome to the ePayServices Open API!

Here you will find all the information to get started with our API.

We offer both a REST JSON API and fallback html interface for screen scraping. This API and html interface can be used to access the accounts of customers and to create internal P2p transfers.

Download OpenAPI specification.

Authentication

All endpoints require authentication via Bearer token in Authorization header.

To become authenticated you will need to sign up as a developer and to generate a new OAuth2 application from the developer's panel.

Afterwards, you'll be able to get an ACCESS TOKEN by following Open ID Connect authentication flow.

You'll find the necessary endpoints information at the OpenID Connect Discovery endpoint

oauth2

Visit the developer's panel to get client_id and client_secret.

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://online.epayservices.com/open_api/oauth/authorize
Token URL: https://online.epayservices.com/open_api/oauth/token
Scopes:
  • openid -

    Authenticate your account

  • accounts -

    Read wallets' information, their balances and operation histories.

  • payments -

    Send an instant internal transfers

Authorization

OAuth2 endpoints support 2 kinds of grants: client credentials and authorization code.

Client credentials grant is used for /account_requests and /payment_requests endpoints. It doesn't require any consent from PSU.

Authorization code grant is used for all the rest of the endpoints. It's required for TPP to get an explicit consent from the PSU.

QWAC Certificate

Both REST JSON API and screen scraping interfaces requires the use of the QWAC client certificates to identify the TPP and have a mutual TLS connection.

During development TPP could issue a temporary QWAC certificate to be used with the ePayServices Sandbox endpoints.

In production TPP is required to have a valid QWAC certificate issued by any Qualified Trust Service Provider.

Sandbox

To generate the development QWAC certificate, TPP should register in the ePayServices Sandbox and create an application.

Afterwards TPP will be able to generate the certificate on the application page.

To test OAuth2 authentication, TPP could use predefined user credentials: user / 123123123.

Account and transaction API

Step 1: Request Account Information

  • This flow begins with a PSU consenting to allow an AISP to access account information data.

Step 2: Setup Account Request

  • The AISP requests access token from ASPSP using Client Credentials grant.

  • The AISP makes a POST request to /account-requests endpoint and gets a new account-request resource (incl. its identifer consent_id). This informs the ASPSP that one of its PSUs is granting access to account and transaction information to an AISP.

Step 3: Authorise Consent

  • The AISP redirects the PSU to the ASPSP. The redirect includes the consent_id generated in the previous step. This allows the ASPSP to correlate the account-request that was setup.

  • The ASPSP authenticates the PSU using Strong Customer Authentication (SCA). The ASPSP updates the state of the account-request resource internally to indicate that the account request has been authorized.

  • During authorization the PSU selects accounts that are authorized for the AISP request (in the ASPSP's banking interface).

  • The PSU is redirected back to the AISP. The TPP takes the code token from the redirect and exchanges it for access token that is linked by ASPSP to the accepted PSU's consent.

Step 4: Request Data

  • This is carried out by making a GET request the relevant resource.

Sequence diagram

Accounts sequence diagram

Payment API

Step 1: Request Internal Transfer (p2p)

  • This flow begins with a PSU consenting to a payment being made. The request is sent through a PISP.

Step 2: Setup Payment Request

  • The PISP requests access token from ASPSP using Client Credentials grant.

  • The PISP makes a POST request to /payment-requests/p2ps endpoint and gets a new payment-request resource (incl. its identifer consent_id). This informs the ASPSP that one of its PSUs intends to make a payment.

  • The PISP must include all payment data in the POST request. It'll be verified by the PSU and compared against the data submitted to /payments/p2ps endpoint after the authorization.

Step 3: Authorise Consent

  • The PISP redirects the PSU to the ASPSP. The redirect includes the consent_id generated in the previous step. This allows the ASPSP to correlate the payment that was setup.

  • The ASPSP authenticates the PSU using Strong Customer Authentication (SCA). The ASPSP updates the state of the payment-request resource internally to indicate that the payment request has been authorized.

  • During authorization the PSU verifies the payment details and accepts or denies the payment (in the ASPSP's banking interface).

  • The PSU is redirected back to the PISP. The TPP takes the code token from the redirect and exchanges it for access token that is linked by ASPSP to the accepted PSU's consent.

Step 4: Request Data

  • Once the PISP gets the access token, the PISP submits the same payment data to /payments/p2ps endpoint. ASPSP validates the payment data and verifies that it matches the consent data. If the data matches and is valid, ASPSP creates p2p payment and returns the p2p resource to the PISP.

Sequence diagram

Payments sequence diagram

Account history

Retrieve a list of operations

Retrieve a list of operations for given account

Authorizations:
path Parameters
account_id
required
integer
Example: 1

Responses

Request samples

curl https://online.epayservices.com/open_api/account_history?account_id=1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response samples

Content type
application/json
[
  • {
    }
]

Account requests

Create account request

Generate account request to retrieve wallet's information.

Authorizations:

Responses

Request samples

curl -X POST https://online.epayservices.com/open_api/account_requests \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response samples

Content type
application/json
{
  • "id": 2,
  • "type": "accounts",
  • "status": "new",
  • "data": { },
  • "expires_at": "2019-03-28 15:00:51 +0300",
  • "created_at": "2019-03-28 14:40:51 +0300"
}

Retrieve a single account request

Retrieve a single new account request.

Authorizations:
path Parameters
id
required
integer
Example: 1

Responses

Request samples

curl https://online.epayservices.com/open_api/account_requests/1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response samples

Content type
application/json
{
  • "id": 2,
  • "type": "accounts",
  • "status": "new",
  • "data": { },
  • "expires_at": "2019-03-28 15:00:51 +0300",
  • "created_at": "2019-03-28 14:40:51 +0300"
}

Delete existing new account request

Delete existing new account request.

Authorized account requests can't be deleted.

Authorizations:
path Parameters
id
required
integer
Example: 1

Responses

Request samples

curl -X DELETE https://online.epayservices.com/open_api/account_requests/1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response samples

Content type
application/json
{
  • "error": "invalid_token",
  • "error_description": "The access token is invalid",
  • "state": "unauthorized"
}

Accounts

Retrieve a list of accounts

Retrieve a list of all active user's accounts.

Authorizations:

Responses

Request samples

curl https://online.epayservices.com/open_api/accounts \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a single account

Retrieve a single account by its unique ID

Authorizations:
path Parameters
id
required
integer
Example: 1

Responses

Request samples

curl https://online.epayservices.com/open_api/accounts/1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response samples

Content type
application/json
{
  • "id": 2,
  • "type": "REGULAR",
  • "balance": "1000.5",
  • "name": "Euro Wallet #2",
  • "number": "1001773430400555",
  • "currency": "USD",
  • "currency_label": "WMZ",
  • "payment_provider_code": "MTACCEU",
  • "favorite": true,
  • "epscard": {
    }
}

Internal P2p transfers

Create payment request to perform internal p2p transfer

Generate payment request to send money to other ePayService account.

Authorizations:
Request Body schema: application/json
sender_account_number
required
string

Wallet number of the sender.

It must have the same currency as receiver_account_number

receiver_account_number
required
string

Wallet number of the receiver.

It must have the same currency as sender_account_number

amount
required
string

Amount to transfer.

Length: between 5 and 32 characters.

comment
required
string [ 5 .. 32 ] characters

Purpose of payment

Responses

Request samples

Content type
application/json
{
  • "sender_account_number": "1001773430400144",
  • "receiver_account_number": "1001773430400555",
  • "amount": "100.10",
  • "comment": "Loan return"
}

Response samples

Content type
application/json
{
  • "id": 2,
  • "type": "accounts",
  • "status": "new",
  • "data": { },
  • "expires_at": "2019-03-28 15:00:51 +0300",
  • "created_at": "2019-03-28 14:40:51 +0300"
}

Retrieve a single P2p payment request

Retrieve a single new payment request for internal P2p transfer by its unique ID.

Authorizations:
path Parameters
id
required
integer
Example: 1

Responses

Request samples

curl https://online.epayservices.com/open_api/payment_requests/p2ps/1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response samples

Content type
application/json
{
  • "id": 2,
  • "type": "accounts",
  • "status": "new",
  • "data": { },
  • "expires_at": "2019-03-28 15:00:51 +0300",
  • "created_at": "2019-03-28 14:40:51 +0300"
}

Delete existing new payment request

Delete existing new payment request.

Authorized or paid payment requests can't be deleted.

Authorizations:
path Parameters
id
required
integer
Example: 1

Responses

Request samples

curl -X DELETE https://online.epayservices.com/open_api/payment_requests/p2ps/1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response samples

Content type
application/json
{
  • "error": "invalid_token",
  • "error_description": "The access token is invalid",
  • "state": "unauthorized"
}

Create internal p2p transfer

Perform authorized internal p2p transfer to other ePayService account.

Authorizations:
Request Body schema: application/json
sender_account_number
required
string

Wallet number of the sender.

It must have the same currency as receiver_account_number

receiver_account_number
required
string

Wallet number of the receiver.

It must have the same currency as sender_account_number

amount
required
string

Amount to transfer.

Length: between 5 and 32 characters.

comment
required
string [ 5 .. 32 ] characters

Purpose of payment

Responses

Request samples

Content type
application/json
{
  • "sender_account_number": "1001773430400144",
  • "receiver_account_number": "1001773430400555",
  • "amount": "100.10",
  • "comment": "Loan return"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "status": "wait",
  • "sender_account_number": "1001773430400555",
  • "receiver_account_number": "2001224100100230",
  • "amount": "300.00",
  • "tax": "1.5",
  • "currency": "EUR",
  • "comment": "Loan return",
  • "created_at": "2019-03-28 15:40:51 +0300",
  • "finished_at": "2019-04-01 12:40:00 +0300"
}

Retrieve a single P2p transfer

Retrieve a single instant internal P2p transfer by its unique ID

Authorizations:
path Parameters
id
required
integer
Example: 1

Responses

Request samples

curl https://online.epayservices.com/open_api/payments/p2ps/1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response samples

Content type
application/json
{
  • "id": 1,
  • "status": "wait",
  • "sender_account_number": "1001773430400555",
  • "receiver_account_number": "2001224100100230",
  • "amount": "300.00",
  • "tax": "1.5",
  • "currency": "EUR",
  • "comment": "Loan return",
  • "created_at": "2019-03-28 15:40:51 +0300",
  • "finished_at": "2019-04-01 12:40:00 +0300"
}