Welcome to epag's API Documentation
Our developer resources and API documentation have been created for developers to familiarize themselves with epag's products, explore the features and the different ways to use our API.
Considerations
RESTful: The API is based on a RESTful architecture.
Stateless: The API does not handle states, all necessary data is sent by the client.
URLs: Each method has its unique URL.
HTTP methods: All requests have to respect the correct HTTP method:
-
GET: Read data;
-
POST: Store data;
-
PUT: Update data;
-
DELETE: Delete data.
Macro Flow
-
Merchant registers at epag and integrates epag's API into Merchant's Store
-
User chooses products -> Proceeds to checkout -> Chooses Payment method -> Submits Payment data -> Receives result -> Receives e-mail confirmation.
-
Epag updates Payment status.
API Macro Flow
-
Merchant registers at LetPay
-
Merchant agrees to contracts terms and conditions
-
Merchant receives credentials to process transactions
-
Merchant authenticates against API and receives JWT Token
-
Merchant submits Payment data and receives, API response, Payment Id and status
-
Merchant is notified via webhook when the payment status changes
-
Merchant checks Payment status
Please note: Steps 6 and 7 are repeated for each new payment.
Getting Started
In order to integrate with epag you will need to:
-
Register your merchant
-
Accept merchant terms and conditions
-
Receive credentials from our team
-
Integrate to our API
API Keys
In order to receive your API Key you need to:
-
Accept fees and taxes for a specific Project
-
Request API Key to process transactions
Create an Api Key
In order to create my api keys
Service: /access-key
Method: POST
Example Request:
curl -X POST --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/access-key'
Response :
- api_key: Key that can be used to authenticate to Epag
- api_secret: Secret that can be used to authenticate with api_key to Epag. You won't be able to see the API Secret anymore. Be sure you have it safely stored elsewhere
Success response body:
{
"api_key": "4f9da3dd-e428-42b1-b592-42cc3fd09876",
"api_secret": "gTn4w2ugBeh2sIGNVE6UWTw4CTenFKb8tvQRo0qa93axqaEGqdslKw87U2qZwjAV"
}
List Api Keys
In order to list my api keys
Service: /access-key
Method: GET
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/access-key'
Response :
- List of my api keys containing:
- api_key (string): Code that can be used to authenticate to Epag
- created_at (date): Api key creation date
- last_access (date): Date of last access using the api key (may be hidden if the api key has not been used yet)
Success response body:
[
{
"api_key": "4f9da3dd-e428-42b1-b592-42cc3fd09876",
"created_at": "2023-06-15T18:29:12.227+0000",
"last_access": "2023-06-15T18:38:12.713+0000"
}
]
Revoke an Api Key
In order to revoke my specific api key
Service: /access-key/API_KEY
Method: DELETE
Request fields:
- None
Example Request:
curl -X DELETE --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/access-key/API_KEY'
Success response body:
- No response body
Attempt to revoke an api key that doesn't belong to me:
{
"timestamp": "2023-06-15T18:45:05.610+0000",
"status": 403,
"error": "Forbidden",
"message": "The user does not have permission to delete this accessKey",
"path": "/access-key/QgiDAH6JWyFSn53mpwso1TZoqN1Y2DssEIM0qGL9tOCutmDsVxir38fDPtGPg0cm",
"errors": null
}
Transaction Details
In order to get the details for a particular transaction:
Service: /transactionDetails/MY_PAYMENT_TOKEN
Method: GET
Request fields:
none
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/transactionDetails/8d434f4b-dcc1-4ae2-8a5a-57fc943e625f'
Response :
{
"general_info" : {
"transaction_status" : "APPROVED",
"transaction_id" : "8d434f4b-dcc1-4ae2-8a5a-57fc943e625f",
"additional info" : "",
"external_id" : "dd3e11a3-3227-4a5a-964e-09794dc45bfe",
"project_id" : "756bfe21-3321-45e5-91a1-db3ff2db8438"
},
"customer_info" : {
"customer_id" : "Alice Sonnentag",
"tax_id" : "123******09",
"customer_contact" : "[email protected]",
"order_ip" : "1.1.1.1",
"order_ip_country" : "Brazil"
},
"payment_info" : {
"order_method" : "CREDITCARD",
"order_method_country" : "Brazil",
"card_number" : "123456******12",
"card_scheme" : "Mastercard",
"card_holder" : "Alice Sonnentag",
"order_amount" : 100.0,
"order_currency" : "BRL",
"currency_fx" : "",
"fx_updated_date" : "",
"payment_amount" : 100.0,
"payment_currency" : "BRL",
"refunded_amount" : 0
},
"fee_info":{
"total_fee_values":0.0,
"merchant_amount":1.0,
"fee":[
{
"fee_type":"TAXES_FEE",
"value":0.46,
"currency":"BRL",
"fxInfo":{
"original_currency":"USD",
"counter_currency":"BRL",
"rate":"2",
"rate_timestemp":"2018-06-18"
}
},
{
"fee_type":"SERVICE_FEE",
"value":0.45,
"currency":"BRL",
"fxInfo":{
"original_currency":"USD",
"counter_currency":"BRL",
"rate":"2",
"rate_timestemp":"2018-06-18"
}
}
]
},
"other_info" : {
"dispute_id" : ""
},
"transaction_history" : [
{
"status": "APPROVED",
"timestamp": "2023-02-02 18:47:54"
},
{
"status": "CREATED",
"timestamp": "2023-02-02 18:42:11"
}
]
}
Get Access Token
In order to request an Access Token:
Service: /auth
Method: POST
Request fields:
- apiKey (string/required)
- apiSecret (string/required)
Notes about tokens:
-
A token is returned for every successfully authenticated user.
-
The token must be used on every action in the same session, such as create or send payments.
-
Every action returns a new refreshed token which can be used in the same session.
-
Tokens are configured to expire after 5 minutes.
Example Request:
curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' -d 'apiKey=MY_API_KEY' -d 'apiSecret=MY_API_SECRET' 'https://api.epag.io/auth'
Response:
- user: User Object with all related data
- token: Token to be used within subsequent API calls
Success response body:
{
"user": {
"role": "USER",
"enable": true,
"name": "MY_NAME",
"id": "32fef81a-24ad-4888-9bae-7a244debc938",
"merchant_id": "32fef81a-24ad-4888-9bae-7a244debc938",
"open": true,
"username": "MY_USERNAME"
},
"version": "0.5.18",
"token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTA0MDI5fQ.MN-IpKXB0duPbiao3zsIqb0c-CLDf0sffl5a6TUC6WhXKrIAJXrSvEOPP9OHve41Wb4Oa9lkHLf9iU2d8lJ6zA"
}
Get Contract Id
Contract IDs are used to group business rules and configurations, like fees, payment methods, payment and settlement cycles. By using a contract ID you are choosing which service under which conditions the transaction being submitted is subject to.
Different types of service will require different contract IDs. Contract IDs can also be used to segregate the activity of different services or stores operating under the same entity.
In order to retrieve your Contract IDs:
Service: /merchant/contracts/list
Method: GET
Request fields:
- None
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/merchant/contracts'
Response:
- refresh_token: Refreshed token to be used within subsequent API calls
- contract: Contract object
- id: Contract Id which will be used when placing orders
Success response body:
{
"contracts": [
{
"createdAt": "YYYY-MM-DDTHH:mm:SSS",
"contractType": "PAYIN",
"methods": [
{
"name": "CREDITCARD",
"active": true,
"currency": "BRL",
"country": "Brasil",
"fees": [
{
"country": "BR",
"amount": 0,
"method": "CREDITCARD",
"endDate": "2050-11-30",
"percentage": 2.89,
"active": true,
"type": "TRANSACTION_FEE",
"value": "2.89%",
"startDate": "2023-11-14"
},
{
"country": "BR",
"amount": 0.18,
"method": "CREDITCARD",
"endDate": "2050-11-30",
"percentage": 0,
"active": true,
"type": "PLATFORM_FEE",
"value": "USD 0.18",
"startDate": "2023-11-14"
},
{
"country": "BR",
"amount": 0.12,
"method": "CREDITCARD",
"endDate": "2050-11-30",
"percentage": 0,
"active": true,
"type": "FRAUD_PROTECTION_FEE",
"value": "USD 0.12",
"startDate": "2023-11-14"
}
]
}
]
}
],
"refresh_token": "REFRESH_TOKEN"
}
Error Response
General format for all error responses
{
"timestamp": "YYYY-MM-DDTHH:mm:SS",
"status": 500,
"error": "Internal Server Error",
"message": "Unknown error. Please contact support.",
"path": "REQUESTED_PATH"
"errors": [
{
"code": "00.00.0000",
"description": "Unknown error. Please contact support."
}
],
"refresh_token": "REFRESH_TOKEN"
}
Simulate states
Aproved state:
To make a payment simulate a aproved state:
"person_firstname": "APPROVED"
Cancelled state:
To make a payment simulate a cancelled state:
"person_firstname": "CANCELED"
In Analysis state:
To make a payment simulate a in analysis state:
"person_firstname": "IN_ANALYSIS"
Declined state:
To make a payment simulate a declined state:
"person_firstname": "DECLINED"
List of possible payment statuses:
-
CREATED: Payment was created and is waiting to be sent to acquirer
-
DECLINED: The payment was declined. The complementary field "errors" will provide an ‘error code’ and a "description" with more information about the cause of the rejection
-
PROCESSING: Acquirer accepted the payment and is processing the request
-
APPROVED: Acquirer approved the payment
-
CANCELED: Payment was canceled and may not exist for acquirer
-
ERROR: Unexpected error occurred during payment processing. The complementary field "errors" will provide an ‘error code’ and a "description" with more information about the cause of the error
-
CHARGED_BACK: Payment was charged back. Upon a request by the cardholder, the issuing bank reversed an initially successfully processed payment
-
IN_MEDIATION: Payment is in dispute
-
REFUNDED: Payment has been approved but was refunded later by the merchant
-
PARTIALLY_REFUNDED: The payment was refunded but not for its total amount
-
PRE_AUTH: Payment has been pre-authorized and can be captured
Create Payment Order
This method allows the preparation of a payment order before submitting it to be processed. If you want to create payments without preparing them first, use the “simple” methods further below.
This method is also useful when there is a need to retrieve information before sending a payment, like currency conversion rates, installments amounts, fees that should be pushed to the customer to pay.
In order to create a Payment Order:
Service: /payment
Method: POST
Request fields Description:
- amount (number/required): Total amount of the payment. Value must have a maximum of two decimal places and must not be less than BRL 0.75.
-
asset (string/required): Reference code for asset for the sale's amount.
Valid options are:
- BRL: Brazilian Real - USD: US Dollar - EUR: Euro
-
reference_id (string/required/max 45 characters): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- contract_id (string/required): epag's contract_id to be used in this sale. This key is necessary to deduct applicable fees and calculate the corresponding settlements.
- person_firstname (string/required): First name of this person. Min 3 characters for
OXXO
,SPEI
andPAYNET
methods. - person_surname (string/required): Surname of this person.
- person_taxid (string/required): Unique identifier for this person in the country tax system (e.g. in Brazil: CPF).
- person_email (string/required): Person’s email provided to the merchant
- person_birth (date, format: YYYY-MM-DD/required): Date of birth
- address_main (string/required*): Main information of the address (e.g. street or Avenue)
- address_number (int/required*): Number for this address
- address_additional (string/required*): Additional information for this address (e.g. department)
- address_locality (string/required*): Billing address locality (e.g. neighborhood)
- address_city (string/required*): Billing address city
- address_state (string/required*): Billing address state code
- address_country (string/required*): Country code as ISO 3166-1 alpha-2 code
- address_zipcode (string/required*): Billing address zip code
- address_phone_area (int/optional/max 2 characters): number of phone area code
- address_phone_country (int/optional/ max 2 characters): number of country phone code
- address_phone (string/optional): Billing address telephone
Optional fields:
- notification_url (string/optional): URL to post callbacks to this payment
-
disable_address (boolean/optional): true to turn off required address fields. Default false.
- All fields below will be ignored when disable_address is true:
- address_main, address_number, address_additional, address_locality, address_city, address_state, address_zipcode
-
extra_data (JSON/optional): Any data pertinent to the merchant
- soft_descriptor (string/optional): Soft descriptor to use at transaction
- ip_address (string/optional): Remote IP Address(IPv4/IPv6)
Example Request:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"amount": 100.10,
"reference_id": "MY_REFERENCE_ID",
"contract_id": "MY_CONTRACT_ID",
"asset": "BRL",
"person_firstname": "Alice",
"person_surname": "Sonnentag",
"person_email": "[email protected]",
"person_taxid": "39784045087",
"person_birth": "1978-08-21",
"address_main": "Rua Araguari",
"address_number": 817,
"address_additional": "Apto 54",
"address_locality": "Vila Sônia",
"address_city": "São Paulo",
"address_state": "SP",
"address_country": "BR",
"address_phone_country": 55,
"address_phone_area": 11,
"address_phone": "23716520",
"address_zipcode": "04514-041",
"notification_url": "https://my-domain.com/callback/",
"soft_descriptor": "SOFT_DESCRIPTOR",
"ip_address": "0.0.0.0",
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
}
}' 'https://api.epag.io/payment'
Response:
- payment_token: unique payment identification for this payment
- refresh_token: updated user token for future calls
- methods: array with valid payment methods
- installments: set of installments optional amounts with taxes
- totals: object with payment totals:
- amount (float): amount in default region asset
- asset (string): asset used in this amount
- original_amount (float): amount as informed by merchant
- original_asset (string): asset used in this originalAmount
- customer_fees (float): total calculated fee assigned to customer
- customer_amount (float): total amount for customer (amount + customerFee)
- customer_fees (object): list of incident customer fees and respective values
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"methods": [
"CREDITCARD",
"BOLETO",
"PIX"
],
"payment": {
"payment_token": "UUID_TOKEN"
},
"totals": {
"amount": 780.44,
"original_amount": 780.44,
"original_asset": "BRL",
"customer_fees": 117.66,
"customer_amount": 897.51,
"asset": "BRL"
},
"customer_fees": {
"TAXES_FEE": "117.66 BRL"
},
"installments": [
{
"amount": 55.01,
"installment": 1
},
{
"amount": 28.33,
"installment": 2
},
(...)
{
"amount": 4.77,
"installment": 12
}
]
}
Process Payment
This method is specific for payment orders that were already created using the “Create Payment Order” method.
In order to process a Payment Order:
Service: /payment/UUID_TOKEN/sendPayment
Method: Post
Card Payments
Request fields:
- method (string/required): Payment Method. Valid options:
CREDITCARD
,DEBITCARD
. - card_number (string/required): Credit Card number (only numbers)
- card_holder (string/required): Name of credit card owner as printed on the credit card
- card_cvv (string/required): Security code of the card
- card_year (int/required): Expiration year of the card (with century, e.g. 2023)
- card_month (int/required): Expiration month to the card
- card_installments (int/required): Number of installments. 0 or 1 values are considered as ‘without installments’. Default: 1.
Optional fields:
- delay_capture (boolean/optional): true to pre-authorize payment for later capture. Default false. Pre-auth cancelation has a TTL of 5 days.
- fraud_protection_token (string/optional/min 32 characters/max 128 characters): Unique token to identify the payment for fraud protection.
Debit card required fields:
- cavv (string/required): Cardholder Authentication Verification Value.
- xid (string/required): Transaction identifier resulting from authentication processing.
- eci (string/required): Electronic Commerce Indicator.
- version (string/required): 3DS version used for authentication.
- dstrans_id (string/required): Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.
Important: The credit card data is not stored in any moment nor attached to a person, only transferred to the acquirer. For a new payment for this person, the credit card data has to be submitted again.
Merchant’s name must have 11 characters length and will be used as a soft descriptor for each payment process. Merchant´s name is previously stored in Merchant´s database when merchant is created.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"method": "CREDITCARD",
"card_number": "5239032934640116",
"card_holder": "Alice Sonnentag",
"card_cvv": "029",
"card_year": 2025,
"card_month": 11,
"card_installments": 2,
"delay_capture": false,
"authentication": {
"cavv": "BwABBylVaQAAAAFwllVpAAAAAAA=",
"xid": "BwABBylVaQAAAAFwllVpAAAAAAA=",
"eci": "05",
"version": "2.1.0",
"dstrans_id": "DIR_SERVER_TID"
}
}' 'https://api.epag.io/payment/42afe884-f047-4452-a3db-65a7de76a9c5/sendPayment'
Response :
- payment_token (string): Token to identify this payment
- refresh_token: updated user token for next calls
- payment_status (string): Status of this payment
- error (string): In case of an error, message describes the error's origin or cause
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "f26d9745-6480-46b3-a347-5553c26685b7",
"error": ""
}
Capture
In order to capture a Pre-Authorized Payment:
Service: /payment/MY_PAYMENT_TOKEN/capture
Method: POST
Request fields:
- amount (number/required): Total amount of the payment. Amount must be equal to pre-authorized amount.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"amount": 100.10
}' 'https://api.epag.io/payment/42afe884-f047-4452-a3db-65a7de76a9c5/capture'
Response :
- payment_token (string): Token to identify this payment
- refresh_token: updated user token for next calls
- payment_status (string): Status of this payment
- customer_id (string): Person identification (final customer) involved in this payment. This id may be used in future payments for this person (final customer)
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "f26d9745-6480-46b3-a347-5553c26685b7",
"customer_id": "CUS-000000000000"
}
Cancel
In order to cancel a Pre-Authorized Payment:
Service: /payment/UUID_TOKEN/cancel
Method: POST
Response :
- payment_token (string): Token to identify this payment
- refresh_token: updated user token for next calls
- payment_status (string): Status of this payment
- customer_id (string): Person identification (final customer) involved in this payment. This id may be used in future payments for this person (final customer)
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "UUID_TOKEN",
"customer_id": "CUS-000000000000"
}
Boleto
Request fields:
- method (string/required): Payment Method. Valid option:
BOLETO
.
Optional fields:
- boleto_expiration_date (date, format: YYYY-MM-DD/optional): Expiration date (if not informed system will assume five days of current date).
- boleto_line1 (string/optional): First line string to introduce as instructions to cashier and final client
- boleto_line2 (string/optional): Second line string to introduce as instructions to cashier and final client
- boleto_line3 (string/optional): Third line string to introduce as instructions to cashier and final client
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"method": "BOLETO",
"boleto_expiration_date": "2019-12-12",
"boleto_line1": "NÃO RECEBER APÓS VENCIMENTO",
"boleto_line2": "PAGÁVEL EM TODA A REDE BANCÁRIA ATÉ O VENCIMENTO",
"boleto_line3": "PAGADOR: CPF 176.787.444-03"
}' 'https://api.epag.io/payment/42afe884-f047-4452-a3db-65a7de76a9c5/sendPayment'
Response :
- payment_token (string): Token to identify this payment
- payment_status (string): Status of this payment
- error (string): In case of an error, message describes the error's origin or cause
- customer_id (string): Person identification (final customer) involved in this payment. This id may be used in future payments for this person (final customer)
- boleto_amount: amount of the boleto
- boleto_duedate (date: YYYY-MM-DD): expiration date of the boleto
- boleto_code (string): numbered string containing code to pay the boleto
- boleto_html (string): Base64 Zipped HTML representation of the boleto
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"boleto_amount": "190",
"payment_status": "PROCESSING",
"payment_token": "59557907-98e7-4457-bfc1-9efc3d0968bb",
"boleto_html": "eNrtXdl2L3bkO8gOfbhcewDOS53k29f7EPbanYPttW8+OLl20ffGTv42ydif7f4McsC/8v/A18OExw=",
"boleto_code": "00190.00009 01014.051005 00000.787176 7 72370000001000",
"error": "",
"boleto_duedate": "2018-06-16"
}
PIX
Request fields:
- method (string/required): Payment Method. Valid option:
PIX
.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"method": "PIX"
}' 'https://api.epag.io/payment/42afe884-f047-4452-a3db-65a7de76a9c5/sendPayment'
Response :
- payment_token (string): Token to identify this payment
- payment_status (string): Status of this payment
- error (string): In case of an error, message describes the error's origin or cause
- gateway_order_id (string): Id to identify this payment along with the acquirer
- pix_amount: amount of the PIX
- pix_qr_code: Base64 Zipped PNG representation of PIX QR code
- pix_code (string): text string containing code to pay the PIX
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "59557907-98e7-4457-bfc1-9efc3d0968bb",
"pix_amount": "190",
"pix_qr_code": "eNrtXdl2L3bkO8gOfbhcewDOS53k29f7EPbanYPttW8+OLl20ffGTv42ydif7f4McsC/8v/A18OExw=",
"pix_code": "00020101021226600016IO.EPAG0136D6299C0D-00D0-42F0-AACD-389A105C892B520489995303986540510.005802BR5925ELPL Tecnologia em Pagame6009Sao Paulo6304B250",
"error": "",
}
OXXO (Mexico)
Request fields:
- method (string/required): Payment Method. Valid option:
OXXO
. - expiration_date (date, format: YYYY-MM-DD/required): Expiration date.
- description (string/optional): This is a message that goes attached to the OXXO transaction and will show at the recipient's bank statement.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"method": "OXXO",
"expiration_date": "2023-05-09",
"description": "Payment via OXXO"
}' 'https://api.epag.io/payment/42afe884-f047-4452-a3db-65a7de76a9c5/sendPayment'
Response:
- payment_token (string): Token to identify this payment
- payment_status (string): Status of this payment
- error (string): In case of an error, message describes the error's origin or cause
- gateway_order_id (string): Id to identify this payment along with the acquirer
- oxxo_amount: amount of the OXXO payment
- oxxo_barcode_image: Base64 Zipped PNG representation of OXXO barcode
- oxxo_barcode (string): text string containing the barcode
- oxxo_pdf: payment confirmation in Base64 Zipped PDF format
Success response body:
{
"payment_status": "PROCESSING",
"error": "",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"gateway_order_id": "ord_z5kCsNDlZZxxOevK6xcow",
"oxxo_barcode": "64000012578123060900025032",
"oxxo_barcode_image": "eJzrDPBz5+WS4mJgYOD19HAJYmBgzACy/RiBBIOqzMbnQMrX08UxpCIu+Qc/YzjrenY5fs09EVrCEXqvq5aHfNmRsTDnwceCg07fhb4XFK7Qagu8uniVe2j/KrlQ21VVIV9XvEISaAllZjh8kWm78Bv5qSALPF39XNY5JTQBAJ+MLxk=",
"oxxo_amount": "25.03",
"oxxo_pdf": "",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdG9ydm8iLCJleHAiOjE2ODU0NTM2NTB9.eXvDIOJkDl7UcVf1P9__hNjJuhytdbmkXIU8-Fz38Tw8DyHKNZXb0I6wypPSZ7bOMYWiUY4ZithLpyOMT5tliw"
}
Paynet (Mexico)
Request fields:
- method (string/required): Payment Method. Valid option:
PAYNET
. - expiration_date (date, format: YYYY-MM-DD/required): Expiration date.
- description (string/optional): This is a message that goes attached to the Paynet transaction and will show at the recipient's bank statement.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"method": "PAYNET",
"expiration_date": "2023-05-09",
"description": "Payment via Paynet"
}' 'https://api.epag.io/payment/42afe884-f047-4452-a3db-65a7de76a9c5/sendPayment'
Response:
- payment_token (string): Token to identify this payment
- payment_status (string): Status of this payment
- error (string): In case of an error, message describes the error's origin or cause
- gateway_order_id (string): Id to identify this payment along with the acquirer
- paynet_amount: amount of the Paynet payment
- paynet_barcode_image: Base64 Zipped PNG representation of Paynet barcode
- paynet_barcode (string): text string containing the barcode
- paynet_pdf: payment confirmation in Base64 Zipped PDF format
Success response body:
{
"payment_status": "PROCESSING",
"error": "",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"gateway_order_id": "ord_z5kCsNDlZZxxOevK6xcow",
"paynet_barcode": "64000012578123060900025032",
"paynet_barcode_image": "eJzrDPBz5+WS4mJgYOD19HAJYmBgzACy/RiBBIOqzMbnQMrX08UxpCIu+Qc/YzjrenY5fs09EVrCEXqvq5aHfNmRsTDnwceCg07fhb4XFK7Qagu8uniVe2j/KrlQ21VVIV9XvEISaAllZjh8kWm78Bv5qSALPF39XNY5JTQBAJ+MLxk=",
"paynet_amount": "25.03",
"paynet_pdf": "",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdG9ydm8iLCJleHAiOjE2ODU0NTM2NTB9.eXvDIOJkDl7UcVf1P9__hNjJuhytdbmkXIU8-Fz38Tw8DyHKNZXb0I6wypPSZ7bOMYWiUY4ZithLpyOMT5tliw"
}
SPEI (Mexico)
Request fields:
- method (string/required): Payment Method. Valid option:
SPEI
. - description (string/optional): This is a message that goes attached to the SPEI transaction and will show at the recipient's bank statement.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"method": "SPEI",
"description": "Payment via SPEI"
}' 'https://api.epag.io/payment/78461461-997d-4dd0-9d9c-1277a7f25356/sendPayment'
Response:
- payment_token (string): Token to identify this payment
- payment_status (string): Status of this payment
- error (string): In case of an error, message describes the error's origin or cause
- gateway_order_id (string): Id to identify this payment along with the acquirer
- spei_amount: amount of the SPEI payment
- spei_clabe: Unique interbank CLABE
- spei_pdf: payment confirmation in Base64 Zipped PDF format
Success response body:
{
"payment_status": "PROCESSING",
"error": "",
"payment_token": "78461461-997d-4dd0-9d9c-1277a7f25356",
"customer_id": "per_08b9c2a39f1718",
"gateway_order_id": "ord_Czx0PXbQiqAb9lTaFtZ8r",
"spei_clabe": "646180179900004256",
"spei_amount": "25.03",
"spei_pdf": "",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdG9ydm8iLCJleHAiOjE2ODU0NTQxNjF9.S-0df9tTxvSOkHAM2DGNherO-riyvGVs2vP2AdzOq4K_oARU0vQBK7IkdKB1Qfao_V1csizuI35VsFpAUgzT5A"
}
3DS 2.0
In order to process Payments with 3DS 2.0 the following steps are necessary:
- Collect some data in accordance to the 3DS 2.0 standard
- Send the collected data set to an MPI to be analyzed by the card issuer
- Receive an authentication token for that data set
- Send this token along with the transactional data when submitting the payment
3DS 2.0 payments require more data than non-3DS payments but they provide protection against some types of fraud and are significantly more secure against chargebacks.
Payment Form
In order to get 3DS authentication
Prerequisite:
- Host epag's 3DS SDK available here.
- Have valid epag Contract Id
- Have notification URL for payment status change callbacks
How to implement
- Step 1: To import the epag's 3DS SDK, place the script in the
<head>
, or in the<body>
section of your HTML page.
<script src="https://3ds.epag.io/scripts/client-v1.0.min.js"></script>
- Step 2: Configure the SDK. Call the
setUp
method, and inform the environment and the contract id.
EPag.setUp({
env: 'PROD',
contractId: 'MY_CONTRACT_ID',
});
field | required | type | description |
---|---|---|---|
env | yes | string | The SDK environment. Valid options: PROD , SANDBOX . |
contractId | yes | string | Merchant's contract id. |
- Step 3: Create the request object.
const request = {
"notificationUrl": "https://mynotificationurl.com",
"referenceId": "PHY",
"disableAddress": false,
"customer": {
"id": "39784045087",
"name": "Alice Sonnentag",
"email": "[email protected]",
"phones": [
{
"country": "55",
"area": "11",
"number": "912345678",
"type": "MOBILE"
}
]
},
"paymentMethod": {
"type": "CREDIT_CARD",
"installments": "1",
"card": {
"number": "4000000000002503",
"expMonth": "12",
"expYear": "2028",
"cvv": "123",
"holder": {
"name": "Alice Sonnentag"
}
}
},
"amount": {
"value": 2503,
"currency": "BRL"
},
"billingAddress": {
"partialAddress": false,
"street": "Rua Araguari",
"number": "817",
"complement": "Conj. 74",
"regionCode": "SP",
"country": "BRA",
"city": "São Paulo",
"postalCode": "04514041"
},
"shippingAddress": {
"partialAddress": false,
"street": "Rua Araguari",
"number": "817",
"complement": "Conj. 74",
"regionCode": "SP",
"country": "BRA",
"city": "São Paulo",
"postalCode": "04514041"
}
}
Request fields:
field | required | type | description |
---|---|---|---|
notificationUrl | yes | string | Url to notify when the payment status changes. |
referenceId | yes | string | External code created by merchant to reference the payment. |
disableAddress | no | boolean | If true disables the person's address. billingAddress and shippingAddress is no longer required and can be omitted. Default: false. |
customer | yes | object | Object containing the person's data. |
customer.id | yes | string | Unique identifier for this person in country tax system (e.g. in Brazil: CPF). |
customer.name | yes | string | Person’s full name. |
customer.email | yes | string | Person’s email provided to the merchant. |
customer.phones[] | yes | array | Person's telephone list provided to the merchant. |
customer.phones[].country | no | integer | Person's telephone country code. Default: 55. |
customer.phones[].area | yes | integer | Person's telephone area code. Must be two digits. |
customer.phones[].number | yes | integer | Person's telephone number. Must be between 8 and 9 digits. |
customer.phones[].type | yes | string | Person's telephone type. Valid option: MOBILE . |
paymentMethod | yes | object | Object containing the payment method data. |
paymentMethod.type | yes | string | Payment Method. Valid option: CREDIT_CARD . |
paymentMethod.installments | no | integer | Number of installments. Must be between 1 and 12. Default: 1. |
paymentMethod.card | yes | object | Object containing the data of the card. |
paymentMethod.card.number | yes | string | Credit Card number (only numbers). |
paymentMethod.card.expMonth | yes | string | Expiration month of the card. |
paymentMethod.card.expYear | yes | string | Expiration year of the card (with century, e.g. 2028). |
paymentMethod.card.cvv | yes | string | Security code of the card. |
paymentMethod.card.holder.name | yes | string | Name of credit card owner as printed on the credit card. |
amount | yes | object | Object containing the amount of the payment. |
amount.value | yes | integer | Total amount of the payment (in cents). |
amount.currency | yes | string | Asset used in this amount. Valid option: BRL . |
billingAddress | yes | object | Object containing the card's billing address data. Can be omitted if disableAddress is true. |
billingAddress.partialAddress | yes | boolean | If true , billingAddress requires only postalCode and number . |
billingAddress.street | yes | string | Main information of the address (e.g. street or avenue). Optional if partialAddress is true. |
billingAddress.number | yes | string | Number for this address. |
billingAddress.complement | no | string | Additional information for this address (e.g. department). |
billingAddress.regionCode | yes | string | Address state code. Optional if partialAddress is true. |
billingAddress.country | no | string | Country code as ISO 3166-1 alpha-3 code. Optional if partialAddress is true. Default: BRA. |
billingAddress.city | yes | string | Address city. Optional if partialAddress is true. |
billingAddress.postalCode | yes | string | Address zip code. |
shippingAddress | no | object | Object containing the person's shipping address data. Can be omitted if disableAddress is true. |
shippingAddress.partialAddress | yes | boolean | If true , shippingAddress requires only postalCode and number . |
shippingAddress.street | yes | string | Main information of the address (e.g. street or avenue). Optional if partialAddress is true. |
shippingAddress.number | yes | string | Number for this address. |
shippingAddress.complement | no | string | Additional information for this address (e.g. department). |
shippingAddress.regionCode | yes | string | Address state code. Optional if partialAddress is true. |
shippingAddress.country | no | string | Country code as ISO 3166-1 alpha-3 code. Optional if partialAddress is true. Default: BRA. |
shippingAddress.city | yes | string | Address city. Optional if partialAddress is true. |
shippingAddress.postalCode | yes | string | Address zip code. |
- Step 4: Call the authentication method.
Call the authenticate3DS
method, pass the request
as parameter and handle the callback events.
await EPag.authenticate3DS(request, {
onSuccess: (e) => {
const id = e.id;
const paymentToken = e.paymentToken;
},
onUnenrolled: () => {
},
onFailure: () => {
},
onError: (e) => {
},
});
The authenticate3DS
method returns a Promise
, so use await
or then
.
Handle the events to get the payment info or error details.
event | description |
---|---|
onSuccess | Card allows authentication and customer was successfully authenticated. id : The 3DS authentication id. Use it to process payment. paymentToken : Token to identify the payment. |
onUnenrolled | Card allows authentication, however, customer authentication did not succeed. |
onFailure | Card does not allow authentication. |
onError | Error during authentication process. |
Example
<html>
<head>
<title>3DS 2.0 Demo</title>
<script type="text/javascript">
function init() {
const contractId = "MY_CONTRACT_ID";
EPag.setUp({
env: 'PROD',
contractId: contractId,
});
}
async function sendOrder() {
const request = {
notificationUrl: document.getElementsByName('notificationUrl')[0].value,
referenceId: document.getElementsByName('referenceId')[0].value,
customer: {
id: document.getElementsByName('customerId')[0].value,
name: document.getElementsByName('customerName')[0].value,
email: document.getElementsByName('customerEmail')[0].value,
phones: [
{
country: '55',
area: document.getElementsByName('customerPhone')[0].value.substring(0, 2),
number: document.getElementsByName('customerPhone')[0].value.substring(2),
type: 'MOBILE',
},
],
},
paymentMethod: {
type: 'CREDIT_CARD',
installments: document.getElementsByName('installments')[0].value,
card: {
number: document.getElementsByName('cardNumber')[0].value,
expMonth: document.getElementsByName('expMonth')[0].value,
expYear: document.getElementsByName('expYear')[0].value,
cvv: document.getElementsByName('cardCvv')[0].value,
holder: {
name: document.getElementsByName('cardHolderName')[0].value,
},
},
},
amount: {
value: parseInt(document.getElementsByName('amount')[0].value),
currency: 'BRL',
},
disableAddress: false,
billingAddress: {
street: document.getElementsByName('addressStreet')[0].value,
number: document.getElementsByName('addressNumber')[0].value,
complement: document.getElementsByName('addressAdditional')[0].value,
regionCode: document.getElementsByName('addressState')[0].value,
country: 'BRA',
city: document.getElementsByName('addressCity')[0].value,
postalCode: document.getElementsByName('addressZipcode')[0].value,
},
shippingAddress: {
street: document.getElementsByName('addressStreet')[0].value,
number: document.getElementsByName('addressNumber')[0].value,
complement: document.getElementsByName('addressAdditional')[0].value,
regionCode: document.getElementsByName('addressState')[0].value,
country: 'BRA',
city: document.getElementsByName('addressCity')[0].value,
postalCode: document.getElementsByName('addressZipcode')[0].value,
},
};
await EPag.authenticate3DS(request, {
onSuccess: (e) => {
const id = e.id;
const paymentToken = e.paymentToken;
},
onUnenrolled: () => {
},
onFailure: () => {
},
onError: (e) => {
console.error(e);
},
});
}
</script>
</head>
<body>
<div>
<h2>3DS 2.0 Demo</h2>
<div>
<b>*</b><label>Amount:</label>
<input type="number" step="1" size="50" name="amount" value="2503" />
<!-- in cents -->
</div>
<fieldset>
<legend>Card</legend>
<div>
<b>*</b><label>Installments:</label>
<input type="text" size="2" name="installments" value="1" />
</div>
<div>
<b>*</b><label>Card Holder Name:</label>
<input type="text" size="50" name="cardHolderName" value="Alice Sonnentag" />
</div>
<div>
<b>*</b><label>Card Number:</label>
<input type="text" size="50" name="cardNumber" value="4000000000002503" />
</div>
<div>
<b>*</b><label>Expiration date:</label>
<input type="text" size="2" name="expMonth" value="12" />
<input type="text" size="4" name="expYear" value="2028" />
</div>
<div>
<label>Cvv:</label>
<input type="text" size="4" name="cardCvv" value="123" />
</div>
</fieldset>
<!-- Billing data -->
<fieldset>
<legend>Billing Address</legend>
<div>
<label>Customer ID (CPF/CNPJ):</label>
<input type="text" size="14" name="customerId" value="39784045087" />
</div>
<div>
<b>*</b><label>Name:</label>
<input type="text" size="50" name="customerName" value="Alice Sonnentag" />
</div>
<div>
<b>*</b><label>Phone number:</label>
<input type="text" size="11" name="customerPhone" value="11912345678" />
</div>
<div>
<b>*</b><label>Email:</label>
<input type="text" size="50" name="customerEmail" value="[email protected]" />
</div>
<div>
<b>*</b><label>Street:</label>
<input type="text" size="50" name="addressStreet" value="Rua Araguari" />
</div>
<div>
<b>*</b><label>Number:</label>
<input type="text" size="50" name="addressNumber" value="817" />
</div>
<div>
<b>*</b><label>Additional:</label>
<input type="text" size="50" name="addressAdditional" value="Conj. 74" />
</div>
<div>
<b>*</b><label>City:</label>
<input type="text" size="50" name="addressCity" value="São Paulo" />
</div>
<div>
<b>*</b><label>State:</label>
<input type="text" size="50" name="addressState" value="SP" />
</div>
<div>
<b>*</b><label>Zipcode:</label>
<input type="text" size="50" name="addressZipcode" value="04514041" />
</div>
</fieldset>
<!-- Order data -->
<fieldset>
<legend>Order</legend>
<div>
<b>*</b><label>Merchant URL:</label>
<input type="text" size="50" name="notificationUrl" value="https://mynotificationurl.com" />
</div>
<div>
<b>*</b><label>Reference Id:</label>
<input type="text" size="50" name="referenceId" value="PHY" />
</div>
</fieldset>
<input type="button" onclick="sendOrder()" value="Send Order" id="btnSendOrder" />
</div>
</body>
<script src="epag.js" type="text/javascript"></script>
<script type="text/javascript">
init();
</script>
</html>
Process Payment
In order to process a Payment:
Service: /payment/MY_PAYMENT_TOKEN/sendPayment
Method: Post
Request fields:
- id (string/required): 3DS id number returned by javascript events.
Optional fields:
- save_card (boolean/optional): true to tokenize card for future uses. Default false.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
{
"authentication": {
"id": "3DS_A0B1C2D4-0123-E5F6-G7H8-I9J0K1L2M3N4"
},
"save_card": false
}' 'https://api.epag.io/payment/3DSa502d-d060-4a1d-a449-3ca78e4341dc/sendPayment'
Response :
- payment_token (string): Token to identify this payment
- customer_id (string): Person identification (final customer) involved in this payment. This id may be used in future payments for this person (final customer)
- gateway_order_id (string): Id to identify this payment along with the acquirer
- refresh_token (string): updated user token for next calls
- payment_status (string): Status of this payment
- public_person_id (string): Unique Person identification for future actions. This field is returned only when "save_card" has been sent as true
- public_card_id (string): Unique Creditcard identification for future actions. This field is returned only when "save_card" has been sent as true
- error (string): In case of an error, message describes the error's origin or cause
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "3DSa502d-d060-4a1d-a449-3ca78e4341dc",
"customer_id": "CUS-000000000000",
"gateway_order_id": "59557907-98e7-4457-bfc1-9efc3d0968bb",
"public_person_id": "PER-715a6579-e420-4098-b18a-918cc732224d",
"public_card_id": "CAR-cbd3dfd8-4e0e-4525-a80b-db361f3189be",
"error": ""
}
External MPI
If you use your own MPI provider you still can use our API to process 3DS 2.0 transactions.
In order to process a 3DS Payment with external MPI:
Service: /payment/MY_PAYMENT_TOKEN/sendPayment
Method: Post
Request fields:
- method (string/required): Payment Method. Valid options:
CREDITCARD
,DEBITCARD
. - card_encrypted (string/required): Encrypted card. See below how to encrypt the card.
- cavv (string/required): Cardholder Authentication Verification Value.
- xid (string/required): Transaction identifier resulting from authentication processing.
- eci (string/required): Electronic Commerce Indicator.
- version (string/required): 3DS version used for authentication.
- dstrans_id (string/required): Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
{
"method": "CREDITCARD",
"card_encrypted": "MY_ENCRYPTED_CARD",
"authentication": {
"cavv": "BwABBylVaQAAAAFwllVpAAAAAAA=",
"xid": "BwABBylVaQAAAAFwllVpAAAAAAA=",
"eci": "05",
"version": "2.1.0",
"dstrans_id": "DIR_SERVER_TID"
}
}' 'https://api.epag.io/payment/a502d-d060-4a1d-a449-3ca78e4341dc/sendPayment'
Response:
- payment_token (string): Token to identify this payment
- customer_id (string): Person identification (final customer) involved in this payment. This id may be used in future payments for this person (final customer)
- gateway_order_id (string): Id to identify this payment along with the acquirer
- refresh_token (string): updated user token for next calls
- payment_status (string): Status of this payment
- public_person_id (string): Unique Person identification for future actions. This field is returned only when "save_card" has been sent as true
- public_card_id (string): Unique Creditcard identification for future actions. This field is returned only when "save_card" has been sent as true
- error (string): In case of an error, message describes the error's origin or cause
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "3DSa502d-d060-4a1d-a449-3ca78e4341dc",
"customer_id": "CUS-000000000000",
"gateway_order_id": "59557907-98e7-4457-bfc1-9efc3d0968bb",
"public_person_id": "PER-715a6579-e420-4098-b18a-918cc732224d",
"public_card_id": "CAR-cbd3dfd8-4e0e-4525-a80b-db361f3189be",
"error": ""
}
Encrypting the card
- Step 1: Import the EPag's 3DS SDK, place the script in the
<head>
, or in the<body>
section of your HTML page.
<script src="https://3ds.epag.io/scripts/client-v1.0.min.js"></script>
- Step 2: Configure the SDK. Call the
setUp
method, and inform the environment and the contract id.
EPag.setUp({
env: 'PROD',
contractId: 'MY_CONTRACT_ID',
});
- Step 3: Call the
encryptCard
method.
const { encrypted } = EPag.encryptCard({
holder: 'Alice Sonnentag',
number: '4000000000002503',
expMonth: 12,
expYear: 2028,
securityCode: '123'
})
encrypted
is a Base64 encoded string.
Simple Boleto
In order to create a Boleto with minimal requirements:
Service: /boleto/simple
Method: Post
Request fields:
- contract_id (string/required): Merchant's contract_id
- amount (number/required): Total amount of the payment. Value must have a maximum of two decimal places
- asset (string/required): Reference code for asset for the sale's amount
- full_name (string/required): Person’s full name
- email (string/required): Person’s email provided to the merchant
- tax_id (string/required): Unique identifier for this person in country tax system (e.g. in Brazil: CPF)
- birth_date (date/required, format: YYYY-MM-DD/required): Person’s date of birth
- country (string/required): Country code as ISO 3166-1 alpha-2 code
Optional fields:
- notification_url (string/optional): URL to post callbacks to this payment
-
reference_id (string/optional/max 45 characters): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
-
expiration_date (date, format: YYYY-MM-DD/optional): Expiration date (if not informed system will assume five days of current date).
- line1 (string/optional): First line string to introduce as instructions to cashier and final client
- line2 (string/optional): Second line string to introduce as instructions to cashier and final client
-
line3 (string/optional): Third line string to introduce as instructions to cashier and final client
-
main (string/optional): Main information of the address (e.g. street or Avenue)
- number (string/optional): Number for the address
- additional (string/optional): Additional information for this address (e.g. department)
- locality (string/optional): Billing address locality (e.g. neighborhood)
- city (string/optional): Billing address city
- state (string/optional): Billing address state code
-
zip_code (string/optional): Billing address zip code
-
extra_data (JSON/optional): Any data pertinent to the merchant
- soft_descriptor (string/optional): Soft descriptor to use at transaction
- ip_address (string/optional): Remote IP Address(IPv4/IPv6)
Example Requests :
Simplified version
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"contract_id": "MY_CONTRACT_ID",
"payment": {
"amount": 10.00,
"asset": "BRL"
},
"person": {
"full_name": "Alice Sonnentag",
"email": "[email protected]",
"tax_id": "39784045087",
"birth_date": "1978-08-21"
},
"address": {
"country": "BR"
}
}' 'https://api.epag.io/boleto/simple'
Complete version
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"contract_id": "MY_CONTRACT_ID",
"reference_id": "MY_REFERENCE_ID",
"notification_url": "https://my-domain.com/callback/",
"ip_address": "0.0.0.0",
"payment": {
"amount": 10.00,
"asset": "BRL",
"boleto": {
"expiration_date": "2019-12-20",
"line1": "NÃO RECEBER APÓS VENCIMENTO",
"line2": "PAGÁVEL EM TODA A REDE BANCÁRIA ATÉ O VENCIMENTO",
"line3": "PAGADOR: CPF 397.840.450-87"
},
"soft_descriptor": "SOFT_DESCRIPTOR"
},
"person": {
"full_name": "Alice Sonnentag",
"email": "[email protected]",
"tax_id": "39784045087",
"birth_date": "1978-08-21"
},
"address": {
"main": "Rua Araguari",
"number": "817",
"additional": "Apto 54",
"locality": "Vila Sônia",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"zip_code": "04514-041"
},
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
}
}' 'https://api.epag.io/boleto/simple'
Response :
- payment_token (string): Token to identify this payment
- payment_status (string): Status of this payment
- reference_id (string): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- customer_id (string): Person identification (final customer) involved in this payment. This id may be used in future payments for this person (final customer)
- boleto_amount: amount of the boleto
- boleto_duedate (date: YYYY-MM-DD): expiration date of the boleto
- boleto_code (string): Numbered string containing code to pay the boleto
- boleto_html (string): Base64 Zipped HTML representation of the boleto
- refresh_token: Updated token for next calls
- totals: object with payment totals:
- amount (float): amount in default region asset
- asset (string): asset used in this amount
- original_amount (float): amount as informed by merchant
- original_asset (string): asset used in this original amount
- customer_fees (float): total calculated fees assigned to customer
- customer_amount (float): total amount for customer (amount + customer fees)
- customer_fees (object): list of incident taxes and respective values
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"boleto_amount": "10.00",
"payment_status": "PROCESSING",
"payment_token": "59557907-98e7-4457-bfc1-9efc3d0968bb",
"reference_id": "reference-test",
"customer_id": "CUS-000000000000",
"boleto_html": "eNrtXdl2L3bkO8gOfbhcewDOS53k29f7EPbanYPttW8+OLl20ffGTv42ydif7f4McsC/8v/A18OExw=",
"boleto_code": "00190.00009 01014.051005 00000.787176 7 72370000001000",
"boleto_duedate": "2020-06-16",
"totals": {
"amount": 38.07000,
"original_amount": 10.00,
"original_asset": "USD",
"customer_fees": 1.53,
"customer_amount": 39.60,
"asset": "BRL"
},
"customer_fees": {
"CURRENCY_CONVERSION_FEE": "1.53 BRL"
}
}
Simple PIX
In order to create a PIX with minimal requirements:
Service: /pix/simple
Method: Post
Request fields:
- contract_id (string/required): Merchant's contract_id
- amount (number/required): Total amount of the payment. Value must have a maximum of two decimal places
- full_name (string/required): Person’s full name
- email (string/required): Person’s email provided to the merchant
- tax_id (string/required): Unique identifier for this person in country tax system (e.g. in Brazil: CPF)
Optional fields:
- notification_url (string/optional): URL to post callbacks to this payment
- reference_id (string/optional/max 45 characters): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- birth_date (date/optional, format: YYYY-MM-DD/required): Person’s date of birth
-
asset (string/optional): Reference code for asset for the sale's amount. Default: BRL.
Valid options are:
- BRL: Brazilian Real - USD: US Dollar - EUR: Euro
-
extra_data (JSON/optional): Any data pertinent to the merchant
- soft_descriptor (string/optional): Soft descriptor to use at transaction
- ip_address (string/optional): Remote IP Address(IPv4/IPv6)
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"contract_id": "MY_CONTRACT_ID",
"reference_id": "MY_REFERENCE_ID",
"notification_url": "https://my-domain.com/callback/",
"ip_address": "0.0.0.0",
"payment": {
"amount": 10.00,
"asset": "USD",
"soft_descriptor": "SOFT_DESCRIPTOR"
},
"person": {
"full_name": "Alice Sonnentag",
"email": "[email protected]",
"tax_id": "39784045087",
"birth_date": "1978-08-21"
},
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
}
}' 'https://api.epag.io/pix/simple'
Response :
- payment_token (string): Token to identify this payment
- payment_status (string): Status of this payment
- reference_id (string): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- pix_amount: amount of the PIX
- pix_qr_code: Base64 Zipped PNG representation of PIX QR code
- pix_code (string): text string containing code to pay the PIX
- refresh_token: Updated token for next calls
- totals: object with payment totals:
- amount (float): amount in default region asset
- asset (string): asset used in this amount
- original_amount (float): amount as informed by merchant
- original_asset (string): asset used in this original amount
- customer_fees (float): total calculated fees assigned to customer
- customer_amount (float): total amount for customer (amount + customer fees)
- customer_fees (object): list of incident taxes and respective values
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "59557907-98e7-4457-bfc1-9efc3d0968bb",
"pix_amount": "190",
"pix_qr_code": "eNrtXdl2L3bkO8gOfbhcewDOS53k29f7EPbanYPttW8+OLl20ffGTv42ydif7f4McsC/8v/A18OExw=",
"pix_code": "00020101021226600016IO.EPAG0136D6299C0D-00D0-42F0-AACD-389A105C892B520489995303986540510.005802BR5925ELPL Tecnologia em Pagame6009Sao Paulo6304B250",
"error": "",
"totals": {
"amount": 723.33000,
"original_amount": 190.00,
"original_asset": "USD",
"customer_fees": 28.94,
"customer_amount": 752.27,
"asset": "BRL"
},
"customer_fees": {
"CURRENCY_CONVERSION_FEE": "28.94 BRL"
}
}
Simple OXXO (Mexico)
In order to create a OXXO payment with minimal requirements:
Service: /oxxo/simple
Method: Post
Request fields:
- contract_id (string/required): Merchant's contract_id
- amount (number/required): Total amount of the payment. Value must have a maximum of two decimal places
- full_name (string/required, min 3 characters): Person’s full name
- email (string/required): Person’s email provided to the merchant
Optional fields:
- notification_url (string/optional): URL to post callbacks to this payment
- reference_id (string/optional/max 45 characters): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- birth_date (date/optional, format: YYYY-MM-DD/required): Person’s date of birth
- asset (string/optional): Reference code for asset for the sale's amount. Default: MXN.
- extra_data (JSON/optional): Any data pertinent to the merchant
- soft_descriptor (string/optional): Soft descriptor to use at transaction
- ip_address (string/optional): Remote IP Address(IPv4/IPv6)
- expiration_date (date, format: YYYY-MM-DD/required): Expiration date.
- description (string/optional): This is a message that goes attached to the OXXO transaction and will show at the recipient bank statement.
Example Requests:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"contract_id": "MY_CONTRACT_ID",
"reference_id": "MY_REFERENCE_ID",
"notification_url": "https://my-domain.com/callback/",
"ip_address": "0.0.0.0",
"payment": {
"amount": 10.00,
"asset": "MXN",
"soft_descriptor": "SOFT_DESCRIPTOR",
"oxxo": {
"expiration_date": "2023-06-20",
"description": "Payment via OXXO"
}
},
"person": {
"full_name": "Alice Sonnentag",
"email": "[email protected]",
"birth_date": "1978-08-21"
},
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
}
}' 'https://api.epag.io/oxxo/simple'
Response :
- payment_token (string): Token to identify this payment
- payment_status (string): Status of this payment
- reference_id (string): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- amount: amount of the payment
- barcode (string): text string containing the barcode
- barcode_png_gzip_base_64: Base64 Zipped PNG representation of OXXO barcode
- pdf_gzip_base_64 (string): payment confirmation in Base64 Zipped PDF format
- refresh_token: Updated token for next calls
- totals: object with payment totals:
- amount (float): amount in default region asset
- asset (string): asset used in this amount
- original_amount (float): amount as informed by merchant
- original_asset (string): asset used in this original amount
- customer_fees (float): total calculated fees assigned to customer
- customer_amount (float): total amount for customer (amount + customer fees)
- customer_fees (object): list of incident taxes and respective values
Simple Paynet (Mexico)
In order to create a Paynet payment with minimal requirements:
Service: /paynet/simple
Method: Post
Request fields:
- contract_id (string/required): Merchant's contract_id
- amount (number/required): Total amount of the payment. Value must have a maximum of two decimal places
- full_name (string/required, min 3 characters): Person’s full name
- email (string/required): Person’s email provided to the merchant
Optional fields:
- notification_url (string/optional): URL to post callbacks to this payment
- reference_id (string/optional/max 45 characters): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- birth_date (date/optional, format: YYYY-MM-DD/required): Person’s date of birth
- asset (string/optional): Reference code for asset for the sale's amount. Default: MXN.
- extra_data (JSON/optional): Any data pertinent to the merchant
- soft_descriptor (string/optional): Soft descriptor to use at transaction
- ip_address (string/optional): Remote IP Address(IPv4/IPv6)
- expiration_date (date, format: YYYY-MM-DD/required): Expiration date.
- description (string/optional): This is a message that goes attached to the Paynet transaction and will show at the recipient bank statement.
Example Requests:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"contract_id": "MY_CONTRACT_ID",
"reference_id": "MY_REFERENCE_ID",
"notification_url": "https://my-domain.com/callback/",
"ip_address": "0.0.0.0",
"payment": {
"amount": 10.00,
"asset": "MXN",
"soft_descriptor": "SOFT_DESCRIPTOR",
"paynet": {
"expiration_date": "2023-06-20",
"description": "Payment via Paynet"
}
},
"person": {
"full_name": "Alice Sonnentag",
"email": "[email protected]",
"birth_date": "1978-08-21"
},
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
}
}' 'https://api.epag.io/paynet/simple'
Response :
- payment_token (string): Token to identify this payment
- payment_status (string): Status of this payment
- reference_id (string): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- amount: amount of the payment
- barcode (string): text string containing the barcode
- barcode_png_gzip_base_64: Base64 Zipped PNG representation of Paynet barcode
- pdf_gzip_base_64 (string): payment confirmation in Base64 Zipped PDF format
- refresh_token: Updated token for next calls
- totals: object with payment totals:
- amount (float): amount in default region asset
- asset (string): asset used in this amount
- original_amount (float): amount as informed by merchant
- original_asset (string): asset used in this original amount
- customer_fees (float): total calculated fees assigned to customer
- customer_amount (float): total amount for customer (amount + customer fees)
- customer_fees (object): list of incident taxes and respective values
Simple SPEI (Mexico)
In order to create a SPEI payment with minimal requirements:
Service: /spei/simple
Method: Post
Request fields:
- contract_id (string/required): Merchant's contract_id
- amount (number/required): Total amount of the payment. Value must have a maximum of two decimal places
- full_name (string/required, min 3 characters): Person’s full name
- email (string/required): Person’s email provided to the merchant
Optional fields:
- notification_url (string/optional): URL to post callbacks to this payment
- reference_id (string/optional/max 45 characters): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- birth_date (date/optional, format: YYYY-MM-DD/required): Person’s date of birth
- asset (string/optional): Reference code for asset for the sale's amount. Default: MXN.
- extra_data (JSON/optional): Any data pertinent to the merchant
- ip_address (string/optional): Remote IP Address(IPv4/IPv6)
- description (string/optional): This is a message that goes attached to SPEI transaction and will show at the recipient bank statement.
Example Requests:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"contract_id": "MY_CONTRACT_ID",
"reference_id": "MY_REFERENCE_ID",
"notification_url": "https://my-domain.com/callback/",
"ip_address": "0.0.0.0",
"payment": {
"amount": 10.00,
"asset": "MXN",
"soft_descriptor": "SOFT_DESCRIPTOR",
"spei": {
"description": "Payment via SPEI"
}
},
"person": {
"full_name": "Alice Sonnentag",
"email": "[email protected]",
"birth_date": "1978-08-21"
},
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
}
}' 'https://api.epag.io/spei/simple'
Response :
- payment_token (string): Token to identify this payment
- payment_status (string): Status of this payment
- reference_id (string): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- amount: amount of the payment
- clabe (string): Unique interbank CLABE
- pdf_gzip_base_64 (string): payment confirmation in Base64 Zipped PDF format
- refresh_token: Updated token for next calls
- totals: object with payment totals:
- amount (float): amount in default region asset
- asset (string): asset used in this amount
- original_amount (float): amount as informed by merchant
- original_asset (string): asset used in this original amount
- customer_fees (float): total calculated fees assigned to customer
- customer_amount (float): total amount for customer (amount + customer fees)
- customer_fees (object): list of incident taxes and respective values
Success response body:
{
"payment_status": "PROCESSING",
"payment_token": "8cc850b7-a223-45aa-9811-69264483d326",
"reference_id": "cca38ab9-b058-440a-988d-499c040fa059",
"clabe": "646180179900004256",
"pdf_gzip_base_64": "",
"amount": "25.03",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdG9ydm8iLCJleHAiOjE2ODU0NTU2ODl9.P0rr9_lohPG7NFVP4G76axOm1YQlOexut7e56NUCBBVPUdT58w8t6osQBgsUCeHUGSOhWHG2C6zLQSfY12Q7UQ",
"totals": {
"amount": 25.03,
"original_amount": 25.03,
"original_asset": "MXN",
"customer_fees": 0.00,
"customer_amount": 25.03,
"asset": "MXN"
},
"customer_fees": {}
}
Token Payments
Process transactions with pre registered payment data
Create a Person & Credit Card
In order to create a Person and a Creditcard
Service: /token/person
Method: Post
Request fields:
- contract_id (string/required): Merchant's contract_id
- person_firstname (string/required): Person’s first name
- person_surname (string/required): Person’s Surname
- person_birth (date/required, format: YYYY-MM-DD/required): Person’s date of birth
- person_email (string/required): Person’s email provided to the merchant
- person_taxid (string/required): Unique identifier for this person in country tax system (e.g. in Brazil: CPF)
- address_city (string/required*): Billing address city
- address_country (string/required*): Country code as ISO 3166-1 alpha-2 code
- address_locality (string/required*): Billing address locality (e.g. neighborhood)
- address_main (string/required*): Main information of the address (e.g. street or Avenue)
- address_number (string/required*): Number for the address
- address_additional (string/optional): Additional information for this address (e.g. department)
- address_state (string/required*): Billing address state code
- address_zipcode (string/required*): Billing address zip code
- address_phone_country (int/optional/max 2 characters): Billing address telephone country
- address_phone_area (int/optional/max 2 characters): Billing address telephone area
- address_phone (string/optional): Billing address telephone
- card_cvv (string/required): Security code of the card
- card_holder (string/required): Name of credit card owner as printed on the credit card
- card_month (int/required): Expiration month of the card
- card_number (string/required): Credit Card number (only numbers)
- card_year (int/required): Expiration year of the card (with century, e.g. 2023)
Optional fields:
- disable_address (boolean/optional): true to turn off required address fields. Default false.
- All fields below will be ignored when disable_address is true:
- address_city, address_country, address_locality, address_main, address_number, address_state, address_zipcode
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"contract_id": "MY_CONTRACT_ID",
"person_firstname": "Alice",
"person_surname": "Sonnentag",
"person_birth": "1978-08-21",
"person_email": "[email protected]",
"person_taxid": "39784045087",
"address_city": "São Paulo",
"address_country": "BR",
"address_locality": "Vila Sônia",
"address_main": "Rua Araguari",
"address_number": "817",
"address_additional": "Conj. 74",
"address_state": "SP",
"address_zipcode": "04514-041",
"address_phone_country": 55,
"address_phone_area": 11,
"address_phone": "23716520",
"card_number": "5239032934640116",
"card_holder": "Alice Sonnentag",
"card_month": 11,
"card_year": 2025,
"card_cvv": "029"
}' 'https://api.epag.io/token/person'
Response :
- refresh_token: Updated token for next calls
- public_person_id: Unique Person identification for future actions
- public_card_id: Unique Creditcard identification for future actions
- error (string): In case of an error, message describes the error's origin or cause
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"error": "",
"public_person_id": "PER-715a6579-e420-4098-b18a-918cc732224d",
"public_card_id": "CAR-cbd3dfd8-4e0e-4525-a80b-db361f3189be"
}
Delete a Credit Card
In order to delete a Card from a Person
Service: /token/card/PUBLIC_CARD_ID
Method: Delete
Request fields:
- None
Example Requests :
curl -X DELETE --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/token/card/0a3ae5c4-0f1a-4a21-9492-016339c84f44'
Response :
- refresh_token: Updated token for next calls
- public_card_id: Deleted Card Id
- error (string): In case of an error, message describes the error's origin or cause
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"public_card_id": "CAR-1cee9922-47de-4603-b55b-166621a40426",
"status": 200,
"error": ""
}
Delete a Person
In order to delete a Person and its related Cards
Service: /token/person/PUBLIC_PERSON_ID
Method: Delete
Request fields:
- None
Example Requests :
curl -X DELETE --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/token/person/90db952d-b7a2-4e3a-8a28-0fc517be0f4a'
Response :
- refresh_token: Updated token for next calls
- public_person_id: Deleted Person Id
- error (string): In case of an error, message describes the error's origin or cause
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"public_person_id": "PER-173ff98b-7f9c-420a-8059-cdc9a67e6f47",
"status": 200,
"error": ""
}
List a Person's cards
Service: /token/person/PUBLIC_PERSON_ID
Method: Get
Request fields:
- None
Example Requests :
curl -X GET --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
}' 'https://api.epag.io/token/person/90db952d-b7a2-4e3a-8a28-0fc517be0f4a'
Response :
- refresh_token: Updated token for next calls
- cards: Array containing Cards Ids
- error (string): In case of an error, message describes the error's origin or cause
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"cards": [
"068af311-2438-4ffd-8bb7-b41289652fcb",
"1617c759-7a80-49f1-be63-d9fdcb5068a0"
]
}
Quote final user amount
Service: /token/quote
Method: Post
Request fields:
- amount (number/required): Total amount of the payment. Value must have a maximum of two decimal places.
-
asset (string/required): Reference code for asset for the sale's amount.
Valid options are:
- BRL: Brazilian Real - USD: US Dollar - EUR: Euro
-
contract_id (string/required): epag's contract_id to be used in this sale. This key is necessary to deduct applicable fees and calculate the corresponding settlements.
- public_person_id (string/required): Person identification
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"contract_id": "3db7cd4d-20fa-43d2-a38c-cb2c13a6e3bc",
"public_person_id": "PER-04f1db66-2ae5-4f41-acdd-96bf152bf99e",
"amount": 100.00,
"asset": "USD"
}' 'https://api.epag.io/token/quote'
Response:
- refresh_token: updated user token for next calls
- totals: object with payment totals:
- amount (float): amount in default region asset
- asset (string): asset used in this amount
- original_amount (float): amount as informed by merchant
- original_asset (string): asset used in this original amount
- customer_fees (float): total calculated fees assigned to customer
- customer_amount (float): total amount for customer (amount + customer fees)
- customer_fees (object): list of incident taxes and respective values
- error (string): In case of an error, message describes the error's origin or cause
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"totals": {
"amount": 376.1,
"original_amount": 100,
"original_asset": "USD",
"customer_fees": 37.61,
"customer_amount": 413.71,
"asset": "BRL"
},
"customer_fees": {
"TAXES_FEE": "37.61 BRL"
}
}
Process payment
Service: /token/
Method: Post
Request fields:
- amount (number/required): Total amount of the payment. Value must have a maximum of two decimal places.
-
asset (string/required): Reference code for asset for the sale's amount.
Valid options are:
- BRL: Brazilian Real - USD: US Dollar - EUR: Euro
-
reference_id (string/required/max 45 characters): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- contract_id (string/required): epag's contract_id to be used in this sale. This key is necessary to deduct applicable fees and calculate the corresponding settlements.
- public_person_id (string/required): Person identification.
- public_card_id (string/required): Creditcard identification.
- card_installments (int): Number of installments. 0 or 1 values are considered as ‘without installments’. Default: 1.
Optional fields:
- method (string/optional): Payment Method. Valid options:
CREDITCARD
,DEBITCARD
. DefaultCREDITCARD
. - delay_capture (boolean/optional): true to pre-authorize payment for later capture. Default false. Pre-auth cancelation has a TTL of 5 days.
-
notification_url (string/optional): URL to post callbacks to this payment
-
extra_data (JSON/optional): Any data pertinent to the merchant
- soft_descriptor (string/optional): Soft descriptor to use at transaction
- ip_address (string/optional): Remote IP Address(IPv4/IPv6)
- fraud_protection_token (string/optional/min 32 characters/max 128 characters): Unique token to identify the payment for fraud protection.
Debit card required fields:
- cavv (string/required): Cardholder Authentication Verification Value.
- xid (string/required): Transaction identifier resulting from authentication processing.
- eci (string/required): Electronic Commerce Indicator.
- version (string/required): 3DS version used for authentication.
- dstrans_id (string/required): Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"amount": 100.10,
"asset": "BRL",
"reference_id": "MY_REFERENCE_ID",
"contract_id": "MY_CONTRACT_ID",
"public_person_id": "90db952d-b7a2-4e3a-8a28-0fc517be0f4a",
"public_card_id": "0a3ae5c4-0f1a-4a21-9492-016339c84f44",
"notification_url": "https://callbackurl.com/",
"delay_capture": false,
"soft_descriptor": "SOFT_DESCRIPTOR",
"ip_address": "0.0.0.0",
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
},
"authentication": {
"cavv": "BwABBylVaQAAAAFwllVpAAAAAAA=",
"xid": "BwABBylVaQAAAAFwllVpAAAAAAA=",
"eci": "05",
"version": "2.1.0",
"dstrans_id": "DIR_SERVER_TID"
}
}' 'https://api.epag.io/token/'
Response :
- payment_token (string): Token to identify this payment
- refresh_token: updated user token for next calls
- payment_status (string): Status of this payment
- public_person_id (string/required): Person identification
- public_card_id (string/required): Creditcard identification
- totals: object with payment totals:
- amount (float): amount in default region asset
- asset (string): asset used in this amount
- original_amount (float): amount as informed by merchant
- original_asset (string): asset used in this originalAmount
- total_customer_fee (float): total calculated fee assigned to customer
- customer_amount (float): total amount for customer (amount + customerFee)
- customer_fees (object): list of incident taxes and respective values
- error (string): In case of an error, message describes the error's origin or cause
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "420b8de1-4947-4e2a-9a9d-be8087353190",
"error": "",
"public_person_id": "PER-2cb9e10c-bbd6-41f1-b067-e32e8f7eb2e2",
"public_card_id": "CAR-87f7dc3c-0ddb-4cb7-87fb-e6e45edbd085",
"totals": {
"amount": 376.1,
"original_amount": 100,
"original_asset": "USD",
"customer_fees": 37.61,
"customer_amount": 413.71,
"asset": "BRL"
},
"customer_fees": {
"TAXES_FEE": "37.46 BRL"
}
}
Capture a Pre-Auth
In order to capture a Pre-Authorized Payment:
Service: /token/MY_PAYMENT_TOKEN/capture
Method: POST
Request fields:
- amount (number/required): Total amount of the payment. Amount must be less than or equal to pre-authorized amount.
- public_person_id (string/required): Person identification.
- public_card_id (string/required): Creditcard identification.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"amount": 100.10
}' 'https://api.epag.io/token/42afe884-f047-4452-a3db-65a7de76a9c5/capture'
Response :
- payment_token (string): Token to identify this payment
- refresh_token: updated user token for next calls
- payment_status (string): Status of this payment
- customer_id (string): Person identification (final customer) involved in this payment. This id may be used in future payments for this person (final customer)
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "f26d9745-6480-46b3-a347-5553c26685b7",
"customer_id": "CUS-000000000000"
}
Cancel a Pre-Auth
In order to cancel a Pre-Authorized Payment:
Service: /token/MY_PAYMENT_TOKEN/cancel
Method: POST
Response :
- payment_token (string): Token to identify this payment
- refresh_token: updated user token for next calls
- payment_status (string): Status of this payment
- customer_id (string): Person identification (final customer) involved in this payment. This id may be used in future payments for this person (final customer)
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "f26d9745-6480-46b3-a347-5553c26685b7",
"customer_id": "CUS-000000000000"
}
Process payment (Mexico)
Service: /token/
Method: Post
Request fields:
- amount (number/required): Total amount of the payment. Value must have a maximum of two decimal places.
-
asset (string/required): Reference code for asset for the sale's amount.
Valid options are:
- MXN: Mexican Peso - USD: US Dollar - EUR: Euro
-
reference_id (string/required/max 45 characters): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
- contract_id (string/required): EPag's contract_id to be used in this sale. This key is necessary to deduct applicable fees and calculate the corresponding settlements.
- public_person_id (string/required): Person identification.
- public_card_id (string/required): Creditcard identification.
Optional fields:
- notification_url (string/optional): URL to post callbacks to this payment
- extra_data (JSON/optional): Any data pertinent to the merchant
- ip_address (string/optional): Remote IP Address(IPv4/IPv6)
- card_cvv (string/optional): Security code of the card. If provided, it enables the 3DS authentication.
- return_url (string/optional): If 3DS is enabled, you must send the url where the client will be redirected after 3DS authentication.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"amount": 100.10,
"asset": "MXN",
"reference_id": "MY_REFERENCE_ID",
"contract_id": "MY_CONTRACT_ID",
"public_person_id": "90db952d-b7a2-4e3a-8a28-0fc517be0f4a",
"public_card_id": "0a3ae5c4-0f1a-4a21-9492-016339c84f44",
"notification_url": "https://callbackurl.com/",
"ip_address": "0.0.0.0",
"card_cvv": "123",
"return_url": "https://merchanturl.com",
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
}
}' 'https://api.epag.io/token/'
Response:
- payment_token (string): Token to identify this payment
- refresh_token: updated user token for next calls
- payment_status (string): Status of this payment
- public_person_id (string/required): Person identification
- public_card_id (string/required): Creditcard identification
- totals: object with payment totals:
- amount (float): amount in default region asset
- asset (string): asset used in this amount
- original_amount (float): amount as informed by merchant
- original_asset (string): asset used in this originalAmount
- total_customer_fee (float): total calculated fee assigned to customer
- customer_amount (float): total amount for customer (amount + customerFee)
- customer_fees (object): list of incident taxes and respective values
- error (string): In case of an error, message describes the error's origin or cause
- redirect_url(string): You must redirect the client to this URL. Required only if 3DS is enabled.
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "420b8de1-4947-4e2a-9a9d-be8087353190",
"error": "",
"public_person_id": "PER-2cb9e10c-bbd6-41f1-b067-e32e8f7eb2e2",
"public_card_id": "CAR-87f7dc3c-0ddb-4cb7-87fb-e6e45edbd085",
"redirect_url": "https://test.redpayonline.com/pay/review/a10828b0-9eb0-4",
"totals": {
"amount": 100,
"original_amount": 100,
"original_asset": "MXN",
"customer_fees": 0.0,
"customer_amount": 100,
"asset": "MXN"
},
"customer_fees": {}
}
Checkout
Hosted Credit Card tokenization and Boleto payment solution.
Flows
Credit Card
- Initiate Checkout solution using Credit Card as payment method
- User informs Personal information and Credit Card data
- Data is encripted
- Retrieve Credit Card payment token
- Authenticate on API
- Request Tokenized Credit Card Ids
- Process Payment
Boleto
- Initiate Checkout solution using Boleto as payment method
- User informs Personal information
- Boleto is presented to the user
- Retrieve payment token
Pix
- Initiate Checkout solution using Pix as payment method
- User informs Personal information
- Pix code is presented to the user
- Retrieve payment token
OXXO (Mexico)
- Initiate Checkout solution using OXXO as payment method
- User informs Personal information
- OXXO barcode is presented to the user
- Retrieve payment token
Paynet (Mexico)
- Initiate Checkout solution using PAYNET as payment method
- User informs Personal information
- Paynet barcode is presented to the user
- Retrieve payment token
SPEI (Mexico)
- Initiate Checkout solution using SPEI as payment method
- User informs Personal information
- SPEI CLABE is presented to the user
- Retrieve payment token
Demo
Available here
Front end
Include our javascript library in the <head>
section of your HTML
<script src="https://checkout.epag.io/checkout-v0.1.js">
Initiate the sollution using html markup:
Method I: HTML
<body>
...
<epag-checkout
amount="137.76"
asset="BRL"
reference-id="MY_REFERENCE_ID"
contract-id="MY_CONTRACT_ID"
method="CREDITCARD"
><epag-checkout/>
...
</body>
Method II: Javascript
...
const ePagCheckout = new EPagCheckout({
amount: "137.76",
asset: "BRL",
referenceId: "MY_REFERENCE_ID",
contractId: "MY_CONTRACT_ID",
method: "CREDITCARD",
});
...
In specific element
...
const ePagCheckout = new EPagCheckout({
amount: "137.76",
asset: "BRL",
referenceId: "MY_REFERENCE_ID",
contractId: "MY_CONTRACT_ID",
method: "CREDITCARD",
});
ePagCheckout.mountIn('#checkout-container-element')
...
Start
...
const ePagCheckout = new EPagCheckout({
amount: "137.76",
asset: "BRL",
referenceId: "MY_REFERENCE_ID",
contractId: "MY_CONTRACT_ID",
method: "CREDITCARD",
});
ePagCheckout.start();
...
Configuration Options
Required
HTML attribute | JS Prop | Type | Required | Default | Description |
---|---|---|---|---|---|
asset | asset | string | yes | n/a | Reference code for asset for the sale's amount. |
reference-id | referenceId | string | yes | n/a | External code created by merchant to reference the payment |
contract-id | contractId | string | yes | n/a | epag's contract_id to be used in this sale |
amount | amount | number | yes | n/a | Total amount of the payment. Value must have a maximum of two decimal places and must not be less than BRL 0.75 |
Payment
HTML attribute | JS Prop | Type | Required | Default | Description |
---|---|---|---|---|---|
method | method | string | yes | n/a | Payment Method. Valid options: CREDITCARD , DEBITCARD , PIX , BOLETO , OXXO , PAYNET , SPEI |
card-installments | cardInstallments | number | no | 1 | Number of installments. Used if method is equal to CREDITCARD |
soft-descriptor | softDescriptor | string | no | n/a | Soft descriptor to use at card transaction |
boleto-expiration-date | boletoExpirationDate | YYYY-MM-DD | no | 5 days from now | Expiration date (if not informed system will assume five days of current date). |
boleto-line1 | boletoLine1 | string | no | n/a | First line string to introduce as instructions to cashier and final client |
boleto-line2 | boletoLine2 | string | no | n/a | Second line string to introduce as instructions to cashier and final client |
boleto-line3 | boletoLine3 | string | no | n/a | Third line string to introduce as instructions to cashier and final client |
notification-url | notificationUrl | string | no | n/a | Url to notify when transaction is successful. |
support-text | supportText | string | no | n/a | Text that will be sent in the footer of the email that is sent to the customer, so that he can contact you in case of doubts (e.g. Questions? Email [email protected]) |
Customer Details
HTML attribute | JS Prop | Type | Required | Default | Description |
---|---|---|---|---|---|
address-additional | addressAdditional | string | no | n/a | Additional information for this address (e.g. department) |
address-city | addressCity | string | no | n/a | Billing address city |
address-country | addressCountry | string | no | n/a | Country code as ISO 3166-1 alpha-2 code |
address-locality | addressLocality | string | no | n/a | Billing address locality (e.g. neighborhood) |
address-main | addressMain | string | no | n/a | Main information of the address (e.g. street or Avenue) |
address-number | addressNumber | number | no | n/a | Number for this address |
address-state | addressState | string | no | n/a | Billing address state code |
address-zip-code | addressZipCode | string | no | n/a | Billing address zip code |
person-birth | personBirth | YYYY-MM-DD | no | n/a | Date of birth |
person-email | personEmail | string | no | n/a | Person's email provided to the merchant |
person-first-name | personFirstName | string | no | n/a | First name of this person. Min 3 characters for OXXO , SPEI and PAYNET methods. |
person-phone | personPhone | string | no | n/a | Billing address telephone |
person-phone-area | personPhoneArea | number/max 2 digits | no | n/a | Number of phone area code |
person-phone-country | personPhoneCountry | number/max 2 digits | no | n/a | Number of country phone code |
person-surname | personSurname | string | no | n/a | Surname of this person. |
person-tax-id | personTaxId | string | no | n/a | Unique identifier for this person in country tax system (e.g. in Brazil: CPF). |
disable-dob | disableDob | boolean | no | false | Hides the date of birth |
lock-email | lockEmail | boolean | no | false | Prevents edit the person's email |
process-payment | processPayment | boolean | no | false | Automatically process the payment |
delay-capture | delayCapture | boolean | no | false | Pre-authorizes the payment for later capture (requires processPayment = true) |
Widget options
HTML attribute | JS Prop | Type | Required | Default | Description |
---|---|---|---|---|---|
button-label | buttonLabel | string | no | Pay now | String that defines the widget button text |
button-color | buttonColor | valid css color | no | #3375C9 | Valid CSS color for the button |
button-text-color | buttonTextColor | valid css color | no | #FFFFFF | Valid CSS color for the button text |
Lightbox options
HTML attribute | JS Prop | Type | Required | Default | Description |
---|---|---|---|---|---|
lightbox-logo-url | lightboxLogoUrl | string | no | ePag logo | the URL of your logo (180 x 30 pixels) beginning with https. |
lightbox-primary-color | lightboxPrimaryColor | valid css color | no | #303740 | color applied to header |
lightbox-secondary-color | lightboxSecondaryColor | valid css color | no | #314259 | color applied to action buttons |
lightbox-accent-color | lightboxAccentColor | valid css color | no | #027BE3 | color applied to input focus and active stepper |
lightbox-positive-color | lightboxPositiveColor | valid css color | no | #A5DC86 | color applied to success icon and success messages |
lightbox-negative-color | lightboxNegativeColor | valid css color | no | #F27474 | color applied to error icon and error messages |
lightbox-info-color | lightboxInfoColor | valid css color | no | #F8BB86 | color applied to loader icon and info messages |
lightbox-warning-color | lightboxWarningColor | valid css color | no | #F2C037 | color applied to warning icon and warning messages |
lightbox-address-bar-color | lightboxAddressBarColor | valid css color | no | #292F36 | color applied to address bar when in mobile |
lightbox-complete-purchase-button-label | lightboxCompletePurchaseButtonLabel | string | no | Concluir compra | String that defines the button's complete purchase text in boleto success feedback page |
lightbox-disable-address | lightboxDisableAddress | boolean | no | false | If true disables the user's address collection step. |
lightbox-partial-address | lightboxPartialAddress | boolean | no | false | If true requires only user's zip code and number |
lightbox-use-3ds | lightboxUse3ds | boolean | no | false | If true enables 3DS authentication |
lightbox-use-external-3ds | lightboxUseExternal3ds | boolean | no | false | If true enables 3DS authentication with an external MPI |
Events
Event name | When |
---|---|
checkout-success | event emitted when successfully processed the payment |
checkout-ready | event emitted when checkout modal is ready |
checkout-dismissed | event emitted when checkout modal is closed |
checkout-error | event emitted when an error occurs with the payment |
boleto-copy | event emitted when payment with boleto mode is successful and user has copied the barcode |
boleto-complete-purchase | event emitted when payment with boleto mode is successful and user clicks complete purchase button |
pix-copy | event emitted when payment with pix mode is successful and user has copied the pix code |
pix-complete-purchase | event emitted when payment with pix mode is successful and user clicks complete purchase button |
3ds-success | event emitted when successfully processed the 3DS payment |
3ds-unenrolled | event emitted when card does not allow 3DS authentication |
3ds-failure | event emitted when an error occurs with the 3DS payment |
3ds-error | event emitted when an error occurs during 3DS authentication process |
Instance methods
Method | Parameter | Return | Description |
---|---|---|---|
mountIn | HTMLElement / CSS selector | void | Mount the checkout in the DOM and display the pay button |
start | no | void | Mount the checkout in the DOM and launch the lightbox. with this method the pay button will not get visible |
closeLightbox | no | void | Used for programmatically close the lightbox |
on | event, function | void | Add an event handler. Act the same way as .addEventListener from HTML |
off | event, function | void | Remove an event handler. Act the same way as .removeEventListener from HTML |
Element methods
method | Parameter | return | Description |
---|---|---|---|
closeLightbox | no | void | used for programmatically close the lightbox |
Handling Events
Using on(event, function)
/ off(event, function)
methods
const ePagCheckout = new EPagCheckout({...});
function handler(event) {
console.log(event.detail[0])
};
// to add a listener
ePagCheckout.on('checkout-success', handler);
// to remove a listener
ePagCheckout.off('checkout-success', handler);
Using addEventListener(type, listener)
/ removeEventListener(type, listener)
methods
const ePagCheckout = document.querySelector('epag-checkout');
function handler(event) {
console.log(event.detail[0])
};
// to add a listener
ePagCheckout.addEventListener('checkout-success', handler);
// to remove a listener
ePagCheckout.removeEventListener('checkout-success', handler);
Closing the lightbox
ePagCheckout.closeLightbox()
Back end
Credit Card
Get Person & Credit Card
Retrieve the Person and Credit Card tokenized Ids using the payment_token returned by CheckoutJS library. Dont forget to authenticate first.
Service: /checkout/PAYMENT_TOKEN
Method: GET
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/checkout/PAYMENT_TOKEN'
Success response body:
{
"public_person_id": "PER-00000000-0000-0000-0000-000000000000",
"public_card_id": "CAR-00000000-0000-0000-0000-000000000000"
}
Process payment
In order to process a payment with retrieved Person and Credit Card Ids.
Service: /checkout/sendPayment
Method: POST
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"contract_id": "MY_CONTRACT_ID",
"reference_id": "MY_REFERENCE_ID",
"notification_url": "https://my-domain.com/callback/",
"public_person_id": "PER-00000000-0000-0000-0000-000000000000",
"public_card_id": "CAR-00000000-0000-0000-0000-000000000000",
"payment": {
"method": "CREDITCARD",
"amount": 90.00,
"asset": "BRL",
"installments": "1",
"delay_capture": false,
"soft_descriptor": "SOFT_DESCRIPTOR"
},
"ip_address": "0.0.0.0",
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
},
"authentication": {
"cavv": "BwABBylVaQAAAAFwllVpAAAAAAA=",
"xid": "BwABBylVaQAAAAFwllVpAAAAAAA=",
"eci": "05",
"version": "2.1.0",
"dstrans_id": "DIR_SERVER_TID"
}
}' 'https://api.epag.io/checkout/sendPayment'
authentication
object is required only when 3DS authentication with an external MPI is enabled.
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "00000000-0000-0000-0000-000000000000",
"error": "",
"public_person_id": "PER-00000000-0000-0000-0000-000000000000",
"public_card_id": "CAR-00000000-0000-0000-0000-000000000000",
"totals": {
"amount": 376.1,
"original_amount": 100,
"original_asset": "USD",
"customer_fees": 37.61,
"customer_amount": 413.71,
"asset": "BRL"
},
"customer_fees": {
"TAXES_FEE": "37.46 BRL"
}
}
Process payment (Mexico)
In order to process a payment with retrieved Person and Credit Card Ids.
Service: /checkout/sendPayment
Method: POST
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"contract_id": "MY_CONTRACT_ID",
"reference_id": "MY_REFERENCE_ID",
"notification_url": "https://my-domain.com/callback/",
"public_person_id": "PER-00000000-0000-0000-0000-000000000000",
"public_card_id": "CAR-00000000-0000-0000-0000-000000000000",
"payment": {
"method": "CREDITCARD",
"amount": 90.00,
"asset": "MXN"
},
"ip_address": "0.0.0.0",
"return_url": "https://merchanturl.com",
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
}
}' 'https://api.epag.io/checkout/sendPayment'
authentication
object is required only when 3DS authentication with an external MPI is enabled.
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "00000000-0000-0000-0000-000000000000",
"error": "",
"public_person_id": "PER-00000000-0000-0000-0000-000000000000",
"public_card_id": "CAR-00000000-0000-0000-0000-000000000000",
"totals": {
"amount": 100.0,
"original_amount": 100.0,
"original_asset": "MXN",
"customer_fees": 100.0,
"customer_amount": 100.0,
"asset": "MXN"
},
"customer_fees": {}
}
return_url
is the url where the client will be redirected after 3DS authentication.
Capture
In order to capture a Pre-Authorized Payment:
Service: /checkout/MY_PAYMENT_TOKEN/capture
Method: POST
Request fields:
- amount (number/required): Total amount of the payment. Amount must be less than or equal to pre-authorized amount.
- public_person_id (string/required): Person identification.
- public_card_id (string/required): Creditcard identification.
Example Requests :
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"amount": 100.10
}' 'https://api.epag.io/checkout/42afe884-f047-4452-a3db-65a7de76a9c5/capture'
Response :
- payment_token (string): Token to identify this payment
- refresh_token: updated user token for next calls
- payment_status (string): Status of this payment
- customer_id (string): Person identification (final customer) involved in this payment. This id may be used in future payments for this person (final customer)
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "f26d9745-6480-46b3-a347-5553c26685b7",
"customer_id": "CUS-000000000000"
}
Cancel
In order to cancel a Pre-Authorized Payment:
Service: /checkout/MY_PAYMENT_TOKEN/cancel
Method: POST
Response :
- payment_token (string): Token to identify this payment
- refresh_token: updated user token for next calls
- payment_status (string): Status of this payment
- customer_id (string): Person identification (final customer) involved in this payment. This id may be used in future payments for this person (final customer)
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"payment_status": "PROCESSING",
"payment_token": "f26d9745-6480-46b3-a347-5553c26685b7",
"customer_id": "CUS-000000000000"
}
Boleto
Retrieve the payment_token returned by the CheckoutJS library.
Generated Checkout Page
In order to generate a URL to access the checkout page.
Service: /checkout/generate
Method: POST
Request fields:
Required
Attribute Name | Type | Default | Description |
---|---|---|---|
asset | string | n/a | Reference code for asset for the sale's amount. |
referenceId | string | n/a | External code created by merchant to reference the payment |
contractId | string | n/a | epag's contract_id to be used in this sale |
amount | number | n/a | Total amount of the payment. Value must have a maximum of two decimal places and must not be less than BRL 0.75 |
method | CREDITCARD / BOLETO / PIX | n/a | Payment Method |
Payment
Attribute Name | Type | Default | Description |
---|---|---|---|
cardInstallments | number | 1 | Number of installments. Used if method is equal to CREDITCARD |
softDescriptor | string | n/a | Soft descriptor to use at card transaction |
expirationDate | YYYY-MM-DD | 5 days from now | Expiration date (if not informed system will assume five days of current date). |
boletoLine1 | string | n/a | First line string to introduce as instructions to cashier and final client |
boletoLine2 | string | n/a | Second line string to introduce as instructions to cashier and final client |
boletoLine3 | string | n/a | Third line string to introduce as instructions to cashier and final client |
notificationUrl | string | n/a | Url to notify when transaction is successful. |
supportText | string | n/a | Text that will be sent in the footer of the email that is sent to the customer, so that he can contact you in case of doubts (e.g. Questions? Email [email protected]) |
paymentCountry | string | 'BR' | Country code in ISO 3166-2 for the amount |
paymentCurrency | string | 'BRL' | Currency code in ISO-4217 for the amount |
returnUrl | string | n/a | Url to redirect the customer when checkout is finished. |
Customer Details
Attribute Name | Type | Default | Description |
---|---|---|---|
addressAdditional | string | n/a | Additional information for this address (e.g. department) |
addressCity | string | n/a | Billing address city |
addressCountry | string | n/a | Country code as ISO 3166-1 alpha-2 code |
addressLocality | string | n/a | Billing address locality (e.g. neighborhood) |
addressMain | string | n/a | Main information of the address (e.g. street or Avenue) |
addressNumber | number | n/a | Number for this address |
addressState | string | n/a | Billing address state code |
addressZipCode | string | n/a | Billing address zip code |
personBirth | YYYY-MM-DD | n/a | Date of birth |
personEmail | string | n/a | Person's email provided to the merchant |
personFirstName | string | n/a | First name of this person |
personPhone | string | n/a | Billing address telephone |
personPhoneArea | number/max 2 digits | n/a | Number of phone area code |
personPhoneCountry | number/max 2 digits | n/a | Number of country phone code |
personSurname | string | n/a | Surname of this person. |
personTaxId | string | n/a | Unique identifier for this person in country tax system (e.g. in Brazil: CPF). |
disableDob | boolean | false | Hides the date of birth |
lockEmail | boolean | false | Prevents edit the person's email |
delayCapture | boolean | false | Pre-authorizes the payment for later capture |
Widget options
Attribute Name | Type | Default | Description |
---|---|---|---|
buttonLabel | string | Pay now | String that defines the widget button text |
buttonColor | valid css color | #3375C9 | Valid CSS color for the button |
buttonTextColor | valid css color | #FFFFFF | Valid CSS color for the button text |
Lightbox options
Attribute Name | Type | Default | Description |
---|---|---|---|
lightboxLogoUrl | string | ePag logo | the URL of your logo (180 x 30 pixels) beginning with https. |
lightboxPrimaryColor | valid css color | #303740 | color applied to header |
lightboxSecondaryColor | valid css color | #314259 | color applied to action buttons |
lightboxAccentColor | valid css color | #027BE3 | color applied to input focus and active stepper |
lightboxPositiveColor | valid css color | #A5DC86 | color applied to success icon and success messages |
lightboxNegativeColor | valid css color | #F27474 | color applied to error icon and error messages |
lightboxInfoColor | valid css color | #F8BB86 | color applied to loader icon and info messages |
lightboxWarningColor | valid css color | #F2C037 | color applied to warning icon and warning messages |
lightboxAddressBarColor | valid css color | #292F36 | color applied to address bar when in mobile |
lightboxCompletePurchaseButtonLabel | string | Concluir compra | String that defines the button's complete purchase text in boleto success feedback page |
lightboxDisableAddress | boolean | false | If true disables the user's address collection step. |
lightboxPartialAddress | boolean | false | If true requires only user's zip code and number |
lightboxUse3ds | boolean | false | If true enables 3DS authentication |
Generated URL options
Attribute Name | Type | Default | Description |
---|---|---|---|
expiresIn | number | 5 | The lifetime in minutes of the generated URL |
Example Request:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"amount": 10.00,
"asset": "BRL",
"referenceId": "MY_REFERENCE_ID",
"contractId": "MY_CONTRACT_ID",
"method": "PIX",
"lightboxDisableAddress": true,
"returnUrl": "https://mysite.com"
}' 'https://api.epag.io/checkout/generate'
Response:
{
"url": "https://checkout.epag.io/payment.html?token=TOKEN",
"expires_at": "2023-09-28T17:34:12.59299-03:00",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdG9ydm8tZXBhZyIsImV4cCI6MTY5NTk0NzM1Mn0.lDNHrQDZVPWxyQrq9lblWGf5PPbZ5eGMRBu0SbMpGUjk5ue1ULCmxdMPR5Kd6Z_obMQ-TC-XPUnVKPzPrH4jBA"
}
Payment Status
By Payment Token
In order to get status of a Payment:
Service: /payment/MY_PAYMENT_TOKEN
Method: GET
Request fields:
- none
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/payment/42afe884-f047-4452-a3db-65a7de76a9c5'
Success response body:
{
"paymentToken": "42afe884-f047-4452-a3db-65a7de76a9c5",
"reference": "PAY-000001",
"createdAt": "yyyy-MM-dd'T'HH:mm:ss.SSS",
"paymentStatus": "PROCESSING",
"currency": "BRL",
"amount_received": 100.10,
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
},
"refunded_amount" : 0,
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"errorCode": ""
}
Canceled payment:
{
"paymentToken": "42afe884-f047-4452-a3db-65a7de76a9c5",
"reference": "PAY-000001",
"createdAt": "yyyy-MM-dd'T'HH:mm:ss.SSS",
"paymentStatus": "CANCELED",
"currency": "BRL",
"amount_received": 100.10,
"cancellation_details": {
"cancelled_by": "ACQUIRER",
"code": "3",
"description": "Issuer policy violation"
},
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
},
"refunded_amount" : 0,
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"errorCode": ""
}
Decline codes
Declined by | Code | Description |
---|---|---|
ACQUIRER | 1 | Invalid data |
ACQUIRER | 2 | Problems when contacting Acquirer |
ACQUIRER | 3 | Issuer policy violation |
ACQUIRER | 4 | Card expired |
ACQUIRER | 5 | Unauthorized transaction |
ACQUIRER | 6 | Duplicated transaction |
ACQUIRER | 11 | Unknown error |
ACQUIRER | 12 | Issuer policy violation |
ACQUIRER | 16 | Invalid Security Code |
EPAG | 7 | Epag policy |
EPAG | 8 | Requested by the buyer |
EPAG | 9 | Requested by the merchant |
EPAG | 10 | Transaction not processed |
EPAG | 13 | Invalid amount |
EPAG | 14 | Epag security pollicy |
By Reference
In order to get status of a Payment by its reference:
Service: /payment/reference/MY_PAYMENT_REFERENCE
Method: GET
Request fields:
- none
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/payment/reference/PAY-000001'
Success response body:
{
"payments": [
{
"paymentToken": "42afe884-f047-4452-a3db-65a7de76a9c5",
"reference": "PAY-000001",
"createdAt": "yyyy-MM-dd'T'HH:mm:ss.SSS",
"paymentStatus": "PROCESSING",
"currency": "BRL",
"amount_received": 100.10,
"extra_data": {
"my-conciliation-number": "xxxxxx",
"my-desired-json-object": {
"property-01": 10,
"property-02": "test"
}
},
"refunded_amount": 0,
"errorCode": ""
}
],
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ"
}
Callbacks
If the notification_url was provided when creating the payment, you will receive a callback as soon as the payment status changes from one of the following IPs: 34.202.209.44 , 34.198.208.154.
Example callback:
{
"reference_id": "jth1bphjo69fr0z2vzpv31rktsuyxe3ho6newfdw0kvgo253o",
"payment_token": "91e0203e-520c-4946-9e7c-887f2a87d6d5"
}
Once the callback received, check the updated status oh the payment via the Payment Status method.
Refunds
In order to request a refund for a transaction.
Currently only BRL asset is supported.
Refunds will be accept within the following periods of time from the payment date:
Payment method | Time limit |
---|---|
PIX | 90 days |
Credit card | 6 months |
Boleto | No limit |
Credit Card
In order to request a refund for a credit card payment:
Service: /refund
Method: POST
Request fields:
- payment_token (string/required): Token to identify the payment
- amount (number/optional): amount to be refunded. Must be equal or inferior to the customer amount.
- notification_url (string/optional): URL to post callbacks to this refund
Example Request:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5"
}' 'https://api.epag.io/refund'
Success response body:
{
"refund_id": "09149b82-ea0f-4818-977b-634344ead0e1",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_status": "PROCESSING",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"errorCode": ""
}
Boleto
In order to request a refund for a boleto payment:
Service: /refund
Method: POST
Request fields:
- payment_token (string/required): Token to identify the payment
- type (string/required): CHECKING or SAVINGS
- bank_number (string/required): The number of the bank
- agency_number (string/required): The agency number
- agency_check_digit (string/required): The agency check digit
- account_number (string/required): The account number
- account_check_digit (string/required): The account check digit
- amount (number/optional): amount to be refunded. Must be equal or inferior to the customer amount.
- notification_url (string/optional): URL to post callbacks to this refund
Example Request:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"type": "CHECKING",
"bank_number": "237",
"agency_number": "12345",
"agency_check_digit": "3",
"account_number": "123456",
"account_check_digit": "4"
}' 'https://api.epag.io/refund'
Success response body:
{
"refund_id": "09149b82-ea0f-4818-977b-634344ead0e1",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_status": "PROCESSING",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"errorCode": ""
}
PIX
In order to request a refund for a PIX payment:
Service: /refund
Method: POST
Request fields:
- payment_token (string/required): Token to identify the payment
- notification_url (string/optional): URL to post callbacks to this refund
Example Request:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5"
}' 'https://api.epag.io/refund'
Success response body:
{
"refund_id": "09149b82-ea0f-4818-977b-634344ead0e1",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_status": "PROCESSING",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"errorCode": ""
}
OXXO (Mexico)
In order to request a refund for a OXXO payment:
Service: /refund
Method: POST
Request fields:
- payment_token (string/required): Token to identify the payment
- bank_code (string/required): The code of the institution to which the payment is directed
- clabe (string/required): CLABE customer interbank
- notification_url (string/optional): URL to post callbacks to this refund
Example Request:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"bank_code": 123456,
"clabe": "646180179900004256"
}' 'https://api.epag.io/refund'
Success response body:
{
"refund_id": "09149b82-ea0f-4818-977b-634344ead0e1",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_status": "PROCESSING",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"errorCode": ""
}
Paynet (Mexico)
In order to request a refund for a Paynet payment:
Service: /refund
Method: POST
Request fields:
- payment_token (string/required): Token to identify the payment
- bank_code (string/required): The code of the institution to which the payment is directed
- clabe (string/required): CLABE customer interbank
- notification_url (string/optional): URL to post callbacks to this refund
Example Request:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"bank_code": 123456,
"clabe": "646180179900004256"
}' 'https://api.epag.io/refund'
Success response body:
{
"refund_id": "09149b82-ea0f-4818-977b-634344ead0e1",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_status": "PROCESSING",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"errorCode": ""
}
SPEI (Mexico)
In order to request a refund for a SPEI payment:
Service: /refund
Method: POST
Request fields:
- payment_token (string/required): Token to identify the payment
- bank_code (string/required): The code of the institution to which the payment is directed
- clabe (string/required): CLABE customer interbank
- notification_url (string/optional): URL to post callbacks to this refund
Example Request:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"bank_code": 123456,
"clabe": "646180179900004256"
}' 'https://api.epag.io/refund'
Success response body:
{
"refund_id": "09149b82-ea0f-4818-977b-634344ead0e1",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_status": "PROCESSING",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"errorCode": ""
}
Status
In order to get the status of a Refund request:
** Service:** /refund/REFUND_ID
Method: GET
Request fields:
none
Possible statuses
- REQUESTED: The refund request has been received
- PROCESSING: The refund is being processed
- COMPLETED: The refund has been successfully executed
- FAILED: The refund has failed and could not have been completed
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/refund/42afe884-f047-4452-a3db-65a7de76a9c5'
Success response body:
{
"refund_id": "09149b82-ea0f-4818-977b-634344ead0e1",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_status": "COMPLETED",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"error_code": ""
}
All status by payment
In order to get the status of a Refund request:
** Service:** /refund/payment/PAYMENT_TOKEN
Method: GET
Request fields:
none
Possible statuses
- REQUESTED: The refund request has been received
- PROCESSING: The refund is being processed
- COMPLETED: The refund has been successfully executed
- FAILED: The refund has failed and could not have been completed
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/refund/42afe884-f047-4452-a3db-65a7de76a9c5'
Success response body:
[
{
"refund_id": "09149b82-ea0f-4818-977b-634344ead0e1",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_status": "COMPLETED",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"error_code": ""
},
{
"refund_id": "d99f7cd9-c9dd-449f-8b43-9e8c706276b0",
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-02-10 12:24:33.657",
"refund_status": "COMPLETED",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"error_code": ""
}
]
Fraud Protection
In order to integrate with Fraud Protection solution.
Get Fraud Protection Token
Retrieve a token to identify the payment for fraud protection.
Service: /fraud-protection/token
Method: Get
Example Requests:
curl -X GET --header 'Content-Type: application/json' --header 'Accept: application/json' 'https://api.epag.io/fraud-protection/token'
Response:
- fraud_protection_token (string): Unique token to identify the payment for fraud protection.
Success response body:
{
"fraud_protection_token": "667d38d9-ae8e-4b7f-8e92-22f35bd20aba"
}
JavaScript SDK
A JavaScript file must be included in the site body.
<script>
function init() {
const attemptReference = 'MY_FRAUD_PROTECTION_TOKEN';
const options = {
attemptReference: attemptReference,
sensitiveFields: ['taxid', 'cardnumber', 'cvv'],
secretFields: ['password'],
};
dftp.init(options);
}
</script>
<script onload="init()" async crossorigin="use-credentials" src="https://profiling.epag.io/s/164469/dAGVfc.js"></script>
Please use the crossorigin="use-credentials"
property when attaching the JavaScript and add async
property.
The initializing function dftp.init
must be executed in the merchant’s service to gather user’s browser data.
It should be called when the form has loaded. Function requires one argument, called options
which is a JavaScript object with multiple properties.
Parameter | Required | Type | Description |
---|---|---|---|
attemptReference | yes | string | unique token generated by calling the endpoint /fraud-protection/token |
sensitiveFields | yes/no | array | a list of strings containing sensitive field IDs |
allowedFields | yes/no | array | a list of strings containing allowed field IDs |
secretFields | no | array | a list of strings containing secret field IDs |
Handling of behavioral data gathered by the profiling script is controlled by sensitiveFields
, allowedFields
and secretFields
parameters.
Passing only sensitiveFields
, fields not otherwise specified will have full behavioral data gathered. secretFields
can be additionally passed.
Passing only allowedFields
, fields not otherwise specified will be stripped of any sensitive information. secretFields
can be additionally passed.
Behavioral data gathered by the profiling script is grouped by form field IDs. It is highly recommended that all form fields have HTML IDs that remain stable over time.
In order to ensure that all necessary profiling data was collected, it’s recommended to use dftp.profileCompleted
function. It returns a Promise object that is resolved when we have completed processing.
async function submit() {
try {
await dftp.profileCompleted();
} catch (e) {
console.error("Profiling failed with error: " + e);
} finally {
doWorkAfterProfiling();
}
}
Example
<html>
<head>
<script>
var attemptReference;
async function init() {
const response = await fetch('https://api.epag.io/fraud-protection/token', {
method: 'GET'
});
const responseBody = await response.json();
attemptReference = responseBody.fraud_protection_token;
const options = {
attemptReference: attemptReference,
sensitiveFields: ['ccn', 'cvv'],
};
dftp.init(options);
}
async function submit() {
try {
await dftp.profileCompleted();
} catch (e) {
console.error("Profiling failed with error: " + e);
} finally {
checkout();
}
}
function checkout() {
}
</script>
<script onload="init()" async crossorigin="use-credentials" src="https://profiling.epag.io/s/164469/dAGVfc.js"></script>
</head>
<body>
<form>
<label>
Name:<br>
<input type="text" name="name" id="name">
</label>
<br>
<label>
Credit card number:<br>
<input type="text" name="ccn" id="ccn">
</label>
<br>
<label>
Expiration date:<br>
<input type="text" name="expiration" id="expiration">
</label>
<br>
<label>
CVV:<br>
<input type="text" name="cvv" id="cvv">
</label>
</form>
<button onclick="submit()">Submit</button>
</body>
</html>
Balance
In order to get available Balance:
** Service:** /wallet/balance
Method: GET
Request fields:
none
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/wallet/balance'
Success response body:
{
"balances": [
{ "asset": "USD", "balance": 100.00 },
{ "asset": "EUR", "balance": 500.00 },
{ "asset": "BRL", "balance": 300.00 },
...
],
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdG9ydm8iLCJleHAiOjE2OTM0MzUyNzV9.6c25PWu1lAgpy7-sQ1ifVpVFWY4eVMOb6lfb3au2qk7a0ksW8DqqqH2rwYlhSGoCxfmg8tOlJ-PkHl6i0EMHJg"
}
Financial Institutions
In order to list all the brazilian Financial Institutions
Service: /financialInstitution
Method: GET
Optional fields:
- FINANCIAL_INSTITUTION_CODE (string/optional): Three digit string code for de Financial Institution. The search by code will only return the matching Financial Institution and the service should be called as follows:
Service: /financialInstitution/FINANCIAL_INSTITUTION_CODE
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/financialInstitution'
Response :
- refresh_token: Updated user token for next calls
- financial_institutions (object): List of brazilian Financial Institution names and codes
- code (string): Code used to identify the Financial Institution in brazilian payment services
- name (string): Short name for the Financial Institution
- full_name (string): Full name registered to the Financial Institution
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
"financial_institutions": [
{
"code": "246",
"name": "BCO ABC BRASIL S.A.",
"full_name": "Banco ABC Brasil S.A."
},
......
......
......
{
"code": "084",
"name": "UNIPRIME NORTE DO PARANÁ - CC",
"full_name": "UNIPRIME NORTE DO PARANÁ - COOPERATIVA DE CRÉDITO LTDA"
}
]
}
Get balance
In order to get my balance
Service: /wallet/balance
Method: GET
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/wallet/balance'
Response :
- My balance containing:
- balances (list): Object list containing balances information
- asset (string): String containing asset relative to balance
- balance (number): Two decimal places number corresponding to the available balance
- balances (list): Object list containing balances information
Success response body:
{
"balances": [
{
"asset": "BRL",
"balance": 21.78
},
{
"asset": "EUR",
"balance": 15.10
}
]
}
Get Tax Id Document Status
In order to get tax id document status
Service: /identityValidation/CONTRACT_ID/JURISDICTION/DOCUMENT
Method: GET
Example Request:
curl -X GET --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' 'https://api.epag.io/identityValidation/CONTRACT_ID/BR/11111111111'
Response :
- Object containing following fields:
- document (string): Same document informed in the request
- status (string): String indicating whether the document is valid (VALID_DOCUMENT) or invalid (INVALID_DOCUMENT)
- status_code (string): In case of invalid document, an epag error code will be returned
- status_message (string): In case of invalid document, a message describing the status_code will be returned
Success response body:
{
"document": "11111111111",
"status": "VALID_DOCUMENT"
}
Payment Status Lifecycle
Creditcard Payment
Creditcard Refund
Creditcard Chargeback
Boleto / PIX Payment
Testing Credit Cards
Bogus credit card data for testing pourposes
Brand | Type | Number | Valid through | CVV |
---|---|---|---|---|
Mastercard | Credit Card | 5240082975622454 | 12/2026 | 123 |
Visa | Credit Card | 4539620659922097 | 12/2026 | 123 |
Amex | Credit Card | 345817690311361 | 12/2026 | 1234 |
Hiper | Credit Card | 6062828598919021 | 12/2026 | 123 |
Elo | Credit Card | 4514161122113757 | 12/2026 | 123 |
Visa | 3DS | 4000000000002503 | 12/2026 | 123 |
Mastercard | 3DS | 5200000000001096 | 12/2026 | 123 |
Elo | 3DS | 6505050000001091 | 12/2026 | 123 |
Error Codes
error code | description |
---|---|
00.00.0000 | Unknown error. Please contact support. |
00.01.0001 | The authentication request is invalid. Please make sure you are providing the right credentials. |
00.01.0002 | The state provided in the address is invalid |
00.01.0003 | Person with empty or non-existent country. |
00.01.0004 | Merchant not found |
00.01.0005 | invalid domain for this host |
00.01.0006 | invalid realm for host |
00.01.0007 | The asset or currency you are trying to use was not found. Please use a valid asset |
00.01.0008 | Invalid card installments: Must be less or equal to 12 |
00.01.0009 | There is no account related to this API key, please make sure you are using the right key in the right environment |
00.01.0010 | We couldn't find a valid user for the credentials provided. Please check if you are using the right user, password or key |
00.01.0011 | Financial institution not found for code |
00.01.0012 | We couldn't find this access key. Please make sure you are using the right credentials and the right environment. |
00.01.0013 | Please provide a valid payment token |
00.01.0014 | Merchant Account not found |
00.01.0015 | No merchant signature found for contract |
00.01.0016 | Error when retrieving address from zip code . Please make sure it is a valid zip code for this region. |
00.01.0017 | Public person id invalid or not found |
00.01.0018 | Public card id invalid or not found |
00.01.0019 | The zip code provided is invalid |
00.01.0020 | Please make sure to send public person id and public card id |
00.01.0021 | Invalid contract / project |
00.01.0022 | Invalid country |
00.01.0023 | Payment method is not allowed for this contract / project |
00.01.0024 | field %s must not be blank |
00.01.0025 | Invalid date. Date must be before |
00.01.0026 | One of the parameters provided are incorrect: Date of birth, Full name, Tax Id |
00.01.0027 | Inactive contract. Please contact the support team. |
00.01.0028 | There is not enough balance for this transaction. |
00.01.0029 | Asset {currencyCode} not found for this contract {contractId} |
00.01.0030 | The contract id field must not be empty. |
00.01.0031 | In order to refund this transaction please inform the type of bank account (CHECKING or SAVINGS). |
00.01.0032 | The card number provided is invalid. Please verify and try again. |
00.01.0033 | The email address provided is invalid. Please verify and try again. |
00.01.0034 | We can't find the card you are trying to use. Please verify and try again. |
00.01.0035 | This payment method is not available in the this country. |
00.01.0036 | The contract id provided doesn't exist. Please provide a valid contract id. |
00.01.0037 | This currency cannot be used with this payment method. |
00.01.0038 | This transaction id {paymentToken} could not be found. |
00.01.0039 | field must not be null |
00.01.0040 | must not be null for method |
00.01.0041 | must be null for method |
00.01.0042 | size must be between {minLength} and {maxLength} |
00.01.0043 | Request processing failed; nested exception is java.lang.IllegalArgumentException: No enum constant epag.model.enumeration.CurrencyCode.{asset} |
00.01.0044 | Malformed JSON request. |
00.01.0045 | Currency incompatible with the given country |
00.01.0046 | Please provide a username for the account. |
00.01.0047 | Please provide a contract id for the account. |
00.01.0048 | Please provide the payment methods for this account. |
00.01.0049 | (field_name) : must be not blank |
00.01.0050 | Required Field Its Not Filled |
00.01.0051 | Validation Error |
00.01.0052 | We can only create exceptions for global rules. Please check and try again. |
00.01.0054 | This rule already exists. |
00.01.0056 | Merchant signature not found for this merchant |
00.01.0057 | The order id must be provided |
00.01.0058 | The payment amount must be greater than 0 |
00.01.0059 | The holder must be filled |
00.01.0060 | The credit card number must be filled |
00.01.0061 | The CVV must be filled |
00.01.0062 | The credit card year must be filled |
00.01.0063 | The credit card month is invalid |
00.01.0064 | The credit card year and month must be in the future |
00.01.0065 | Debit card transaction does not support delay capture |
00.01.0066 | Debit card transaction does not support installments |
00.02.0001 | There was an issue when contacting an external API, please contact support |
00.03.0001 | There was an issue when contacting an external API, please contact support |
00.03.0002 | There was an issue when contacting an external API, please contact support |
00.03.0003 | There was an issue when contacting an external API, please contact support |
00.03.0004 | Erro em serviços que valida a identificação fiscal. Tente mais tarde. |
00.03.0005 | Your notification URL returned an error or timed out when receiving a callback notification. callMerchant error : HTTP error code |
00.03.0006 | We are having trouble retrieving the current FX rates, please try again later. |
00.03.0007 | Unexpected error while processing request with acquirer. Please contact the support team |
00.04.0001 | The user does not have permission to delete this accessKey |
00.04.0002 | The payment does not belong to merchant. |
00.04.0003 | Current contract cannot perform this action |
00.04.0005 | This payment {paymentToken} does not belong to this merchant, user {username} Merchant This payment {paymentToken} does not belong to this merchant, user {username} |
00.04.0006 | The current STATUS of the transaction prevents it from being refunded |
00.04.0007 | Invalid Payment Method |
00.04.0008 | This transaction requires 3DS 2.0 authentication |
00.04.0009 | Invalid Operation.The supported operations are CREDIT and DEBIT. |
00.04.0010 | The payment token was not pre-authorized, so it can't be captured. |
00.04.0011 | The request amount is higher than the pre-authorized amount available |
00.04.0012 | Transaction status can not change |
00.04.0013 | You are trying to make a 3DS authenticated transaction. The only methods accepted for this are credit card and debit card. |
00.04.0014 | The refund could not proceed because the requested amount is too high, please check and try again with a smaller amount. |
00.04.0016 | The name and the Tax ID provided don't match. Please verify and try again. |
00.04.0017 | You don't have permission to create a firewall rule for this account. Please use the correct account. |
00.04.0019 | Blocked by firewall rules: " + rule.getRuleType() |
00.04.0020 | The 3DS authentication failed. |
00.04.0021 | This payment method is not allowed for this contract. |
00.04.0022 | This payment token has already been used in a previous call to sendPayment |
00.05.0001 | There was an unexpected error in our application, please contact support |
00.05.0002 | There was an error when decoding a QR code or a barcode. Please try again. If the problem persists, please contact support. |
00.05.0003 | There was an unexpected error in our application, please contact support if the problem persists. |
00.05.0004 | There was an unexpected error in our application, please contact support if the problem persists. |
00.05.0005 | There was an error when trying to fetch the account |
00.05.0006 | There was an error when trying to create the account |
00.05.0007 | There was an error when trying to create the contract |
00.05.0008 | There was an error when trying to fetch the fees |
00.05.0009 | There was an error when trying to fetch the signatures |
00.05.0010 | There was an error when trying to fetch the accounts |
00.05.0011 | There seems to be an issue with our gateway's configuration, please contact support. |
00.05.0012 | The credentials to issue this refund seems to be missing. Please contact support. |
00.05.0013 | There was an issue fetching a configuration for this account. Please contact support. |
00.05.0014 | We couldn't find a rate for this currency pair, please make sure to use a valid one. |
00.05.0016 | There was an error when creating the merchant account. Please contact support. |
00.06.0001 | No settlements found when searching for listing |
01.01.0001 | Transaction declined, an obligatory parameter(s) is missing |
01.01.0002 | Transaction declined, invalid or malformed parameters |
01.01.0003 | Transaction is invalid |
01.01.0004 | Installment invalid. Please change it before trying again. |
01.01.0005 | Incorrect date format. |
01.02.0001 | Communication failure when reaching payment provider. Please try again later. |
01.02.0002 | Please submit the transaction again. |
01.03.0001 | Transaction declined |
01.03.0002 | Transaction declined, please contact the card issuer |
01.03.0003 | Transaction not allowed. |
01.03.0004 | Merchant, please contact us. |
01.03.0005 | Unauthorized. moderate risk Identified by the issuer. |
01.04.0001 | Card data might be wrong. Please check and try again. |
01.04.0002 | Invalid password. |
01.04.0003 | There is an issue with the destination account for this transaction, please contact the account provider or use a different account. |
01.04.0004 | There is an issue with the origin account for this transaction, please contact the account provider or use a different account. |
01.04.0005 | Invalid card data. |
01.04.0006 | Invalid bank branch |
01.04.0007 | Invalid bank account number |
01.04.0008 | The destination bank account doesnt belong to this account holder |
01.04.0009 | The origin bank account doesnt belong to this account holder |
01.04.0010 | Account not found |
01.04.0011 | Invalid transaction id |
01.04.0012 | Transaction not found |
01.04.0013 | Unauthorized. Nonexistent card. |
01.04.0014 | Transaction already sent. |
01.05.0001 | Transaction declined, referenced transaction can not be refunded, captured or reversed (already refunded, captured or reversed) |
01.05.0002 | Transaction declined, cannot refund (already refunded/reversed, invalid workflow or amount exceeded) |
01.05.0003 | Capture already performed or expired |
01.05.0004 | Reimbursement already performed, or amount requested above the allowed |
01.05.0005 | Transaction not allowed for this card. |
01.05.0006 | Amount is different from the approved pre-authorization. |
01.05.0007 | Please change the type of card from debit to credit. |
01.05.0008 | Please change the type of card from credit to debit. |
01.05.0009 | Transaction not authorized. Please try again. |
01.05.0010 | Transaction not authorized. Please try again using 3DS authentication. |
01.05.0011 | Card not elligible for international transactions. |
01.05.0012 | Card blocked. Please unblock the card before trying again. |
01.05.0013 | Unauthorized transaction. |
01.05.0014 | Insufficient balance or credit limit |
01.05.0015 | Scheduling denied |
01.05.0016 | The authentication required to validate the transaction failed |
01.05.0017 | This transaction is already being processed. |
01.05.0018 | Refund period expired |
01.05.0019 | Wrong authentication code |
01.05.0020 | Transaction not allowed for this type of product/service |
01.05.0021 | Expired card. Transaction cannot be resubmitted. Contact issuer. |
01.05.0022 | There is an issue with this card. Please contact the issuer. |
01.05.0023 | Unauthorized. Check the situation of the store with the card issuer. |
01.05.0024 | Unauthorized. Restricted card. |
01.05.0025 | Unauthorized. Card expired. |
01.05.0026 | Unauthorized. The card does not belong to the payment network. |
01.05.0027 | Unauthorized. Invalid security code. |
01.05.0028 | Cardholder not registered in the issuer's authentication program. |
01.05.0029 | Error trying to validate tax id document. |
01.05.0030 | Current payment status does not allow refund |
01.06.0001 | Blocked by firewall rules: %s |
01.06.0003 | Payment rejected by risk analysis. |
01.06.0004 | User limit exceeded. |
01.06.0005 | Configuration Error. |
01.07.0001 | The owner of the payment instrument revoked the permission for this transaction. |
01.08.0001 | transaction declined for unknown reason |
01.10.0001 | Exceeded attempts - Do not try again |
01.10.0002 | Transaction amount not allowed. Please check the transaction limits on you account. |
01.10.0003 | Limit for Invalid password attempts exceeded. Please contact the card issuer. |
01.10.0004 | Not authorized. Exceeded the limit of allowed transactions for the period |
01.11.0001 | TaxID suspended |
01.11.0002 | TaxID holder was declared deceased |
01.11.0003 | TaxID pending regularization |
01.11.0004 | TaxID canceled, the owner has a new TaxID number |
01.11.0005 | Impeached TaxID |
01.11.0006 | TaxID canceled by local authority |
01.11.0007 | Impeached Corporate TaxID |
01.11.0008 | Corporate TaxID suspended |
01.11.0009 | Corporate TaxID suspended |
01.11.0010 | Corporate TaxID is active but pending regularization |
01.11.0011 | Corporate TaxID canceled |
01.11.0012 | Tax ID doesnt exist |
01.11.0013 | CPF query for minors blocked in compliance with the General Data Protection Law - LGPD |