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 Server, accepting secure requests from 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 involved).

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 issuer (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.

Encoding

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

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

HTTP Header

Request HTTP Header:

Request	Field Name	Description	Format	Length	Remark
authorization Type	authorization	Bearer <access-token>, the access-token is assigned by Coshine	String	Maximum 64 characters	Example: Bearer EAmHx5ClXw7nB7ai/ r2Nm9vDiPOXBdL/0P4CZiOHNeY=
Timestamp	timestamp	Timestamp of the message send	String	Maximum 15 characters	Example: "10567867" UNIX Timestamp

Response HTTP :

Response	Field Name	Description	Format	Length	Remark
Timestamp	timestamp	Timestamp of the message send	String	Maximum 15 characters	Example: 10567867 UNIX Timestamp

HTTP Status Code

For each request sent to our API, the HTTP status code of the response will indicate the basic result.

Status Code	Status Message	Description
200	Success	Message call is successful
307	Temporary Redirect	Temporary redirect
400	Bad Request	Message verification failed. This might either point to e.g. invalid parameters or values sent.
401	Unauthorized	invalid authorization header provided
403	Invalid access token	invalid access token provided
404	Not Found	requested resource or endpoint is not found. I.e. endpoint/url doesn't exist.

API List

No.	Module	API Name	API Description	Prepaid	Debit	Remark
1	Application	CardApplication	Support both Physical / virtual card application (delivery address is mandatory for Physical card)	M	M
2	Customer	CustomerCardInfoInquiry	Return the card information (including card status) with inquiry of the customer id	M	M
3		CustomerAccountInfoInquiry	Return the account information (including account status) with inquiry of the customer id	O	NA
4		CustomerInfoUpdate	For customer Information maintenance, including mobile number, email address, address (delivery address for physical card)…	O	O
5	Account	AccountLinkage	Associate a card with an account	O	O
6		AccountStatusUpdate	Change Account Status including block, close etc.	O	NA
7	Card	CardInfoInquiry	Return card information, card plastic status and status date, renew/reissuing information and other card-related information	O	O
8		CardActivation	Activate a card	O	O
9
10		CardReplacement	Support Card Replacement with Same Card number or Specific card number or Random card number; Also can be used to convert virtual card to physical card	O	O
11		CardCancellation	Card Cancellation with reason codes or memo	O	O
12		CardStatusUpdate	Change Card Status including lost, stolen, block etc.	C	C
13		CardLimitSetting	Set transaction limit + Domestic/Oversea & e-commerce/POS Transaction Indicator	O	O	Card level limit control
14		CardCVV2Inquiry	Retrieve Card number, expiry date, CVV2 by card token	O	NA	Only for virtual card
15		CardCVV2Verify	Verify CVV2 by card token	O	NA	Only for virtual card
16		GenerateDCVV	Generate a new CVV2	O	O
17		CardExpiryDateUpdate	Update Card Expiry Date		NA
18		CardSecureRegist	3D-Secure Service for cardholder. if registered, the cardholder will get OTP by mail /SMS when e-commerce transaction need authentication	O	O	If use Coshine’s ACS Services
19		BlacklistUpdate	Insert or delete blacklist or whitelist card	NA	NA	Old Version. Not used now.
20		PINReset	Reset Card PIN	O	M	If card support online PIN
21		PINChange	Change Card PIN	O	M
22		PINVerify	Verify Card PIN	O	O
23	Transaction	BalanceInquiry	Balance Inquiry	O	NA	Wallet / Banking system will provide their own API if account is controlled by their system
24		LoadFund	Load fund / Payment to card account	O	NA
25		Withdraw	Withdraw in ATM	C	NA	If prepaid card support ATM transaction
26		TransferFund	Transfer between two card	O	NA
27		Purchase	Purchase /Sale transaction	C	NA
28		Refund	Refund or Void transaction	C	NA
29		Reversal	Reversal for LoadFund , Withdraw, TransferFund and Purchase	M	NA
30		BlockFund	For Preauthorization or other purpose to block the amount	C	NA	If prepaid card support pre-auth / block fund
31		UnblockFund	Release/ Partial release preauthorization	C	NA
32		ServiceCharge	Service Fee charge	O	NA
33		Verification	Card/Account Verification	O	NA
34		DebitAdjustment	Debit Adjustment (Miscellaneous adjustment with memo)	O	NA
35		CreditAdjustment	Credit Adjustment (Miscellaneous adjustment with memo)	O	NA
36		TransactionHistory	Inquiry Transaction History by token number	M	NA
37		AuthorizationHistory	Inquiry Authorization History by token number	O	NA
38	Token	TokenInquiry	Inquiry token information by card number.
39		TokenRequest	After Generated UnionPay Virtual PAN based on issuer’s mobile APP Account, initialize Token for the Virtual PAN.
40		TokenStateUpdate	When the Cardholder or the mobile application suspends, resumes, or deletes the card, the mobile application shall send the Token State Update request to change the state of the Token.
41		TokenStateNotification	When the UMPS suspends, resumes, or deletes the card, the UMPS will send the Token State Notification request to notify the mobile application.
42		TokenMetadataUpdate	The Token metadata, e.g., Token expiry date, needs to be updated from the mobile application’s side if the PAN expiry date has already been renewed.
43		ReplenishTokenLUK	Mobile application will call SDK API “tokenValidForProcessing” to check if there are available LUKs in SDK before payment for a given Token identified by the Token ID
44	Authentication	SendOTP	Direct OTP authentication request to issuer
45		VerifyOTP	Request to verify the OTP provided
46		StartOOBAuthen	Direct OOB authentication request to issuer
47		OOBResultInquiry	Inquiry the result of OOB authentication
48	Parameter	DropDownListInquiry	Retrieve lookup table from our system, such as reason list for card replacement