API Introduction

Authentication Models

Depending on how transaction processing responsibilities are divided, two distinct scenarios are covered.

It is preferable that the Issuer can provide their IP address, which we will add to our whitelist. The Issuer can use the Bearer Token mode.

Issuer Does NOT Manage Card/Account Balance

In this setup, Eastpay issuing system is fully responsible for transaction processing, including authorization logic and balance checking. The Issuer does not control card/account balance directly.

Issuer Manages Card/Account Balance

In this case, the Issuer system holds and manages the actual balance. Our system acts as a transaction gateway and forwards each authorization request to the Issuer in real time.

Authentication Setup:

• Our system acts as the API client, initiating secure requests to the Issuer.

• OAuth 2.0 compliant authentication defined in Section Authentication Method is preferable.

Authentication Method

Authentication is based on OAuth 2.0 using the private_key_jwt method and client_credential as grant type (no user invloved).

This ensures strong client authentication, token lifecycle management, and cryptographic protection of API payloads.

The following components are involved:

• Authorization Server -- issues and validates access tokens.

• Client -- the external system integrating with this API.

• Resource Server -- validates tokens and processes API requests.

Key Exchange

Before API integration, the client must obtain the required public keys from the server and provide its own keys.

• Server-provided keys

  • EC Public Key -- used to verify access token signatures.

  • RSA Public Key -- used to encrypt request payloads.

• Client-provided keys

  • EC Public Key -- used to verify client_assertion signatures.

  • RSA Public Key -- used to encrypt response payloads.

If certificate-based distribution is required, the client must provide valid X.509 certificates. Certificates should be issued by a trusted CA.

Client Authentication

The client must authenticate to the Authorization Server using the following parameters:

• clientAuthenticationMethod: private_key_jwt

• authorizationGrantType: client_credentials

• scope: as assigned by the server (principle of least privilege)

• authenticationSigningAlgorithm: ES256

Token Usage

• The access token is signed by the server with ES256 (JWS). The access token is short-lived for 60 minutes. Once it is expired, the client could request the access token again via Client Authentication.

• The client assertion must be signed by the client with ES256 (JWS).

Payload Encryption

All API payloads must be encrypted as follows:

• Requests (Client → Server)

  • Encrypted with the server's RSA Public Key.

  • Algorithm: RSA_OAEP_256 (key management) + A128GCM (content encryption).

• Responses (Server → Client)

  • Encrypted with the client's RSA Public Key.

  • Algorithm: RSA_OAEP_256 + A128GCM.

API Request

Each API request must include the access token (signed JWT) as a Bearer Token in the header.

Enoding

Our system expects data to be sent encoded in UTF-8.

Using this Content-Type header can help: application/json; charset=UTF-8

Network Connectivity Options

For enhanced security and stability, we can establish VPN tunnels or dedicated MPLS/private leased lines between our system and the Issuer.

• The specific connection method will be chosen following mutual security assessments conducted by both parties' security/compliance teams.

HTTP Header

Request HTTP Header

Request	Field Name	Description	Format	Remark
authorization type	Authorization	Bearer access-token, the access- token is assigned by coshine	String, Maximum 64 characters	For example:  Bearer EAmHx5ClXw7nB7ai/r2 Nm9vDiPOXBdL/0P4C ZiOHNeY=
timestamp	Timestamp	Timestamp of the message send	String, Maximum 15 characters	For example: "10567867" UNIX Timestamp

Response HTTP

Request	Field Name	Description	Format	Remark
timestamp	Timestamp	Timestamp of the message send	String, Maximum 15 characters	For example: "10567867" UNIX Timestamp

HTTP Status Codes

For each request you send to our API the HTTP status code of the response will already tell you the basic result.

Status Code	Description
200	Successful request
307	Temporary redirect
400	Bad request. This might either point to e.g. invalid parameters or values sent. It's also returned if the payment failed e.g. because the acquirer declined.
401	Invalid authorization header provided
403	Invalid access token provided
404	Requested resource or endpoint is not found. I.e. endpoint/url doesn't exist. This can also be caused by typos like POST /v3/payments instead of payments or wrong IDs like GET /v3/payments/{id} where no payment with {id} exists.