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

200

List of operations

401

Invalid token

403

Invalid TPP certificate

404

Account not found

get /open_api/account_history?account_id={account_id}

Sandbox Server

https://psd2.staging.epayservices.com/open_api/account_history?account_id={account_id}

Live Server

https://psd2.epayservices.com/open_api/account_history?account_id={account_id}

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Account requests

Create account request

Generate account request to retrieve wallet's information.

Authorizations:

Responses

201

Account request created

401

Invalid token

403

Invalid TPP certificate

post /open_api/account_requests

Sandbox Server

https://psd2.staging.epayservices.com/open_api/account_requests

Live Server

https://psd2.epayservices.com/open_api/account_requests

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

Account request is found

401

Invalid token

403

Invalid TPP certificate

404

Account request isn't found

get /open_api/account_requests/{id}

Sandbox Server

https://psd2.staging.epayservices.com/open_api/account_requests/{id}

Live Server

https://psd2.epayservices.com/open_api/account_requests/{id}

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

204

Account request deleted

401

Invalid token

403

Invalid TPP certificate

404

Account request isn't found

delete /open_api/account_requests/{id}

Sandbox Server

https://psd2.staging.epayservices.com/open_api/account_requests/{id}

Live Server

https://psd2.epayservices.com/open_api/account_requests/{id}

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

List of accounts

401

Invalid token

403

Invalid TPP certificate

get /open_api/accounts

Sandbox Server

https://psd2.staging.epayservices.com/open_api/accounts

Live Server

https://psd2.epayservices.com/open_api/accounts

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Retrieve a single account

Retrieve a single account by its unique ID

Authorizations:
path Parameters
id
required
integer
Example: 1

Responses

200

Account found

401

Invalid token

403

Invalid TPP certificate

404

Account not found

get /open_api/accounts/{id}

Sandbox Server

https://psd2.staging.epayservices.com/open_api/accounts/{id}

Live Server

https://psd2.epayservices.com/open_api/accounts/{id}

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

201

Payment request created

400

Missing p2p params

401

Invalid token

403

Invalid TPP certificate

post /open_api/payment_requests/p2ps

Sandbox Server

https://psd2.staging.epayservices.com/open_api/payment_requests/p2ps

Live Server

https://psd2.epayservices.com/open_api/payment_requests/p2ps

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

Payment request found

401

Invalid token

403

Invalid TPP certificate

404

Payment request isn't found

get /open_api/payment_requests/p2ps/{id}

Sandbox Server

https://psd2.staging.epayservices.com/open_api/payment_requests/p2ps/{id}

Live Server

https://psd2.epayservices.com/open_api/payment_requests/p2ps/{id}

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

204

Payment request deleted

401

Invalid token

403

Invalid TPP certificate

404

Payment request isn't found

delete /open_api/payment_requests/p2ps/{id}

Sandbox Server

https://psd2.staging.epayservices.com/open_api/payment_requests/p2ps/{id}

Live Server

https://psd2.epayservices.com/open_api/payment_requests/p2ps/{id}

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

201

Transfer created

400

Validation error

401

Invalid token

403

Invalid TPP certificate

post /open_api/payments/p2ps

Sandbox Server

https://psd2.staging.epayservices.com/open_api/payments/p2ps

Live Server

https://psd2.epayservices.com/open_api/payments/p2ps

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

Transfer found

401

Invalid token

403

Invalid TPP certificate

404

Transfer not found

get /open_api/payments/p2ps/{id}

Sandbox Server

https://psd2.staging.epayservices.com/open_api/payments/p2ps/{id}

Live Server

https://psd2.epayservices.com/open_api/payments/p2ps/{id}

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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"
}