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.
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
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:
|
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.
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.
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
.
Step 1: Request Account Information
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
Step 1: Request Internal Transfer (p2p)
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
/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.Retrieve a list of operations for given account
account_id required | integer Example: 1 |
curl https://online.epayservices.com/open_api/account_history?account_id=1 \ -H "Authorization: Bearer <ACCESS_TOKEN>"
[- {
- "id": 3,
- "account_id": 2,
- "type_act": "out",
- "description": "To Ivan Ivanov (card: 4242**4242)",
- "comment": "Loan return",
- "status": "paid",
- "amount": "100.55",
- "tax": "0.5",
- "currency": "EUR",
- "created_at": "2019-03-28 14:40:51 +0300",
- "transaction_type": "Cash Remittance",
- "available_balance": "900.45"
}
]
Generate account request to retrieve wallet's information.
curl -X POST https://online.epayservices.com/open_api/account_requests \ -H "Authorization: Bearer <ACCESS_TOKEN>"
{- "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 new account request.
id required | integer Example: 1 |
curl https://online.epayservices.com/open_api/account_requests/1 \ -H "Authorization: Bearer <ACCESS_TOKEN>"
{- "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.
Authorized account requests can't be deleted.
id required | integer Example: 1 |
curl -X DELETE https://online.epayservices.com/open_api/account_requests/1 \ -H "Authorization: Bearer <ACCESS_TOKEN>"
{- "error": "invalid_token",
- "error_description": "The access token is invalid",
- "state": "unauthorized"
}
Retrieve a list of all active user's accounts.
curl https://online.epayservices.com/open_api/accounts \ -H "Authorization: Bearer <ACCESS_TOKEN>"
[- {
- "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": {
- "id": 1,
- "status": "active",
- "currency": "EUR",
- "exp_y": "22",
- "exp_m": "03",
- "masked_number": "4242********4242",
- "is_virtual": true,
- "is_reloadable": false,
- "limits_group": "string"
}
}
]
Retrieve a single account by its unique ID
id required | integer Example: 1 |
curl https://online.epayservices.com/open_api/accounts/1 \ -H "Authorization: Bearer <ACCESS_TOKEN>"
{- "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": {
- "id": 1,
- "status": "active",
- "currency": "EUR",
- "exp_y": "22",
- "exp_m": "03",
- "masked_number": "4242********4242",
- "is_virtual": true,
- "is_reloadable": false,
- "limits_group": "string"
}
}
Generate payment request to send money to other ePayService account.
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 |
{- "sender_account_number": "1001773430400144",
- "receiver_account_number": "1001773430400555",
- "amount": "100.10",
- "comment": "Loan return"
}
{- "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 new payment request for internal P2p transfer by its unique ID.
id required | integer Example: 1 |
curl https://online.epayservices.com/open_api/payment_requests/p2ps/1 \ -H "Authorization: Bearer <ACCESS_TOKEN>"
{- "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.
Authorized or paid payment requests can't be deleted.
id required | integer Example: 1 |
curl -X DELETE https://online.epayservices.com/open_api/payment_requests/p2ps/1 \ -H "Authorization: Bearer <ACCESS_TOKEN>"
{- "error": "invalid_token",
- "error_description": "The access token is invalid",
- "state": "unauthorized"
}
Perform authorized internal p2p transfer to other ePayService account.
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 |
{- "sender_account_number": "1001773430400144",
- "receiver_account_number": "1001773430400555",
- "amount": "100.10",
- "comment": "Loan return"
}
{- "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 instant internal P2p transfer by its unique ID
id required | integer Example: 1 |
curl https://online.epayservices.com/open_api/payments/p2ps/1 \ -H "Authorization: Bearer <ACCESS_TOKEN>"
{- "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"
}