logo
Documentation Powered by ReDoc

ePayServices OpenApi (v1)

Download OpenAPI specification:Download

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

  • psp_ai -

    Read account information such as transactions, balances.

  • psp_pi -

    Send instant internal transfers

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.

Strong Customer Authentication

Every P2P payment requires a prior SCA consent from the PSU.

To get the consent, TPP should redirect the PSU to /open_api/sca/new page with its client_id and the payment's amount, current and beneficiary (receiver_account_number in case of p2p) GET parameters.

After the PSU authorization, TPP will receive the redirect to sca_redirect_uri url with the consent status. (either ok or denied).

If the returned status is ok, then TPP could send the actual p2p payment with the same amount, currency and beneficiary as the consent's.

Account history

Retrieve a list of operations

Retrieve a list of operations for given account

Authorizations:
oauth2
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
[
  • {
    }
]

Accounts

Retrieve a list of accounts

Retrieve a list of all active user's accounts.

Authorizations:
oauth2

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:
oauth2
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 internal p2p transfer

Send money to other ePayService account.

Scope: p2p_out.

Authorizations:
oauth2
Request Body schema: application/json
sender_account_id
required
integer

Unique ID of the sender's account.

receiver_account_number
required
string

Account number of the receiving user.

It must have the same currency as the sender's account

amount
required
string

Amount to transfer.

Length: between 5 and 32 characters.

comment
required
string [ 5 .. 32 ] characters

Purpose of payment

protection_code
string

Optional password protection for the transfer

protection_days
integer

Number of days until p2p is automatically cancelled

Responses

201

Transfer created

401

Invalid token

403

Invalid TPP certificate

422

Validation error

post /open_api/out/p2ps

Sandbox Server

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

Live Server

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

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "sender_account_id": 101,
  • "receiver_account_number": "1001773430400555",
  • "amount": "100.10",
  • "comment": "Loan return",
  • "protection_code": "SECRET",
  • "protection_days": 14
}

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",
  • "protected": true,
  • "protection_time": "2019-04-10 13:00:00 +0300"
}

Retrieve a single P2p transfer

Retrieve a single instant internal P2p transfer by its unique ID

Scope: p2p_out.

Authorizations:
oauth2
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/out/p2ps/{id}

Sandbox Server

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

Live Server

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

Request samples

Copy
curl https://online.epayservices.com/open_api/out/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",
  • "protected": true,
  • "protection_time": "2019-04-10 13:00:00 +0300"
}

Calculate a fee

Calculate a transaction fee for a single P2p transfer.

Scope: p2p_out.

Authorizations:
oauth2
query Parameters
account_id
required
integer
Example: account_id=1

Sender account unique ID

amount
string
Example: amount=50.0

Transfered amount

receiver_account_number
string
Example: receiver_account_number=2001224100100230

Pass receiver account number to apply special optional fee rates

Responses

200

Fee calculated

401

Invalid token

403

Invalid TPP certificate

get /open_api/out/p2ps/fee

Sandbox Server

https://psd2.staging.epayservices.com/open_api/out/p2ps/fee

Live Server

https://psd2.epayservices.com/open_api/out/p2ps/fee

Request samples

Copy
curl https://online.epayservices.com/open_api/out/p2ps/fee?amount=50.0&account_id=1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount":
    {
    },
  • "fee":
    {
    },
  • "total":
    {
    }
}