Examples
Payment Flow Example
This example demonstrates how to perform a complete payment flow using the ePay API.
Step 1: Authentication
First, you need to authenticate with the ePay API to obtain an access token. To do this, make a POST request to the authentication endpoint with your clientId and clientSecret.
curl --location '{{API_BASE_URL}}/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"clientId": "{{CLIENT_ID}}",
"clientSecret": "{{CLIENT_SECRET}}",
}'
The response will be an access token that you must include in the headers of your API requests.
{
"accessToken": "some-access-token", // Access token
"tokenType": "Bearer", // Token type
"expiresIn": 3600 // Expiration time in seconds
}
Step 2: Create Payment Method
Next, create a payment method using the payment method creation endpoint.
curl --location '{{API_BASE_URL}}/paymentmethods' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--data-raw '{
"customer": {
"id": "some-customer-id",
"name": "Tim Cook",
"email": "tim.cook@apple.com",
"phoneNumber": "+1 408-555-5555"
},
"card": {
"number": "4000000000001000",
"expirationMonth": "12",
"expirationYear": "2030",
"cvv": "123",
"cardHolder": "TIM COOK",
"singleUse": false
}
}'
The response will be an object containing the ID of the created payment method.
{
"id": "663d52c0e044fede8ea1edbf", // Payment method ID
"type": "card",
"bin": {
"brand": "Visa",
"issuerName": "ITS BANK",
"countryCode": "USA"
}, // BIN information
"success": true, // Indicates if the operation was successful
"message": "The payment method was successfully created"
}
Step 3: Perform a Transaction
Finally, perform a transaction using the charges endpoint.
curl --location '{{API_BASE_URL}}/charges' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--data-raw '{
"order": {
"id": "your-order-id",
"amount": 10,
"description": "some-description",
"name": "some-name"
},
"cardId": "663d52c0e044fede8ea1edbf",
"authenticationId": null,
"billingInfo": {
"countryCode": "USA",
"stateCode": "NC",
"zipCode": "27244"
}
}'
Billing information (billingInfo) is only required when the card issuer country is the USA or CAN. This can be determined from the payment method's BIN country code.
The response parameters for performing a charge are described below:
| Parameter | Type | Description |
|---|---|---|
| status | String | Indicates the status of the charge. |
| message | String | Describes the result of the status parameter. |
| error | Object | Object containing the error code and message. |
| authentication | Object | Object containing the authentication URL and validation ID to complete the transaction. |
| order | Object | Object containing the order information. |
| createdAt | DateTime | Date and time of the transaction in UTC. |
Charge Statuses (status)
There are 3 possible charge statuses:
FAILED
This status indicates that the payment process failed. The error node will contain the error code and message.
Example:
{
"status": "FAILED",
"message": "The payment could not be processed: Charge Under Review, Contact our Customer Service department at +50324086126. Id: 1a77edab-f826-4693-addb-bf0743702270",
"error": {
"code": "FRAUD_PREVENT",
"message": "Charge Under Review, Contact our Customer Service department at +50324086126"
},
"authentication": null,
"order": null,
"createdAt": "2023-08-23T22:57:50.1154760Z"
}
SUCCEEDED
This status indicates that the payment process was successfully completed.
Example:
{
"status": "SUCCEEDED",
"message": "The payment was successfully completed",
"error": null,
"authentication": null,
"order": {
"id": "1", // n1co order id
"reference": "your-order-id", // your order id
"amount": 10,
"currency": "USD",
"authorizationCode": "176981"
},
"createdAt": "2023-08-24T02:03:55.5851570Z"
}
AUTHENTICATION_REQUIRED
This status indicates that the transaction requires 3DS authentication.
Example:
{
"status": "AUTHENTICATION_REQUIRED",
"message": "The payment requires 3DS authentication",
"error": null,
"authentication": {
"url": "https://front-3ds.h4b.dev/authentication/b574cee2-1ce7-4aa7-b176-8a6390e91081",
"id": "b574cee2-1ce7-4aa7-b176-8a6390e91081"
},
"order": null,
"createdAt": "2023-09-28T18:53:51.1070240Z"
}
To validate the transaction, the buyer must be redirected to the URL provided in the authentication node using an iframe. Below are implementation examples of an iframe:
Implementation Explanation
For handling this case, the frontend project should add an event listener that listens for the postMessage sent from the iframe. The structure of the message is as follows:
{
"MessageType": string,
"Status": string,
"AuthenticationId": string,
"OrderId": string,
"OrderAmount": number
}
MessageType
-
authentication.complete→ authentication completed successfully -
authentication.failed→ error processing the authentication
Status
-
PENDING→ pending authentication -
SUCCESS→ successful authentication -
FAILED→ authentication with the issuing bank failed -
ERROR→ internal payment processor error -
EXPIRED→ the authentication has expired
Once the message with MessageType = "authentication.complete" and Status = "SUCCESS" is received, a new charge request must be made. This time, include the authenticationId received in the previous message to complete the transaction.
curl --location '{{API_BASE_URL}}/charges' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--data-raw '{
"order": {
"id": "your-order-id",
"amount": 10,
"description": "some-description",
"name": "some-name"
},
"cardId": "663d52c0e044fede8ea1edbf",
"authenticationId": "b574cee2-1ce7-4aa7-b176-8a6390e91081",
"billingInfo": {
"countryCode": "USA",
"stateCode": "NC",
"zipCode": "27244"
}
}'
The response will be similar to the previous one, with the transaction status and order information.