Epag Payment 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 epag
-
Merchant agrees to contracts terms and conditions
-
Merchant receives credentials to process transactions
-
Merchant authenticates against API and receives JWT Token
-
Merchant requests Contract identification via API and receives Contract Id
-
Merchant creates Payment order and receives Payment Token
-
Merchant submits Payment data and receives Payment Id and status
-
Merchant checks Payment status
Please note: Steps 6 and 7 are repeated for each new payment.
Macro Flow
Getting Started
In order to integrate with epag you will need to:
-
Register your merchant account with epag
-
Accept epag’s merchant terms and conditions
Request API Key
In order to receive your API Key you need to:
-
Accept fees and taxes for a specific Project
-
Request API Key to process transactions
Get Access Token
In order to request an Access Token:
Service: /auth
Method: POST
Request fields:
-
username (string/required)
-
password (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 on 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 'username=MY_USERNAME&password=MY_PASSWORD' 'https://api.epag.io/auth'
Success response body:
{
"user": {
"role": "USER",
"name": "MY_NAME",
"id": "96e779fe-fb95-4074-8247-1d6d90ebb2d1",
"merchant_id": "96e779fe-fb95-4074-8247-1d6d90ebb2d1",
"username": "MY_USERNAME"
},
"token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJsb2phMSIsImV4cCI6MTQ4NTI4MzUzMn0.I9hcOAUk_LQ-JOeYavRjxbJPL-",
"version": “0.5.15”
}
Error response body:
{
"timestamp": 1488823260706,
"status": 401,
"error": "Unauthorized",
"exception": "org.springframework.security.authentication.BadCredentialsException",
"message": "Access Denied",
"path": "/auth"
}
Get Contract Id
In order to request a Contract Id:
Service: /merchant/contracts
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'
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJsb2phMSIsImV4cCI6MTUwMzYxODYyOH0.6ncojMAV3v",
"contract": {
"createdAt": "YYYY-MM-DD-HH:mm:SS",
"id": "4239d673-b23e-42a1-81bd-87d0984fb173"
}
}
Error response body:
{
"timestamp": 1488823431214,
"status": 401,
"error": "Unauthorized",
"message": "Access Denied",
"path": "/merchant/contracts"
}
Create Payment Order
In order to create a Payment Order:
Service: /payment
Method: POST
Request fields:
-
amount (number/required): Total amount of the payment
-
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): External code created by 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.
In case the person (final client) has previous payments:
- person_gateway_id (string): Unique identifier for a person who as previous completed successful payments within epag’s system. This value is returned by epag when the payment is successfully processed.
In case of a new person or unknown person_gateway_id:
-
person_firstname (string/required): First name of this person
-
person_surname (string/required): Surname of this person.
-
person_taxid (string/required): Unique identifier for this person in 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 info of his 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_zipcode (string/required): Billing address zip code
-
address_phone (string/required): Billing address telephone
-
address_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
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": "IYWEGQR 90",
"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": "Brasil",
"address_phone": "1123716520",
"address_zipcode": "04514-041"
}' 'https://api.epag.io/payment'
Notes:
There are two ways to set person fields:
-
Set all person and address fields except person_gateway_id for the first sale for this customer
-
Set only person_gateway_id to an existent customer and then epag will provide all previous fields to this new payment
Response:
-
payment_token: unique payment identification to identify this payment in future actions.
-
refresh_token: updated user token for future calls
-
methods: array with valid payment methods
-
installments: set of installments optional amounts with taxes
-
totals: array with payment totals :
-
amount (float): amount in default region asset
-
asset (string): asset used in this amount
-
originalAmount (float): amount as informed by merchant
-
originalAsset (string): asset used in this originalAmount
-
customerFee (float): total calculated fee assigned to customer
-
customerAmount (float): total amount for customer (amount + customerFee)
-
Success response body:
{
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJsb2phMSIsImV4cCI6MTUwMzYxODcxN30.KMMKhNVJSyZ4CgWJ",
"methods": [
"CREDITCARD",
"BOLETO"
],
"payment": {
"payment_token": "c25a502d-d060-4a1d-a449-3ca78e4341dc"
},
"totals": {
"amount": 780.44,
"originalAmount": 780.44,
"originalAsset": "BRL",
"customerFee": 117.066,
"customerAmount": 897.51,
"asset": "BRL"
}
"installments": [
{
"amount": 55.01,
"installment": 1
},
{
"amount": 28.33,
"installment": 2
},
(...)
{
"amount": 4.77,
"installment": 12
}
]
}
Error response body:
{
"timestamp": 1488824673716,
"status": 500,
"error": "Internal Server Error",
"exception": "epag.exceptions.ContractNotFoundException",
"message": "Request processing failed; nested exception is epag.exceptions.ContractNotFoundException: Contract cannot be found. 889342938-98jfisdf-8dki",
"path": "/payment"
}
Process Payment
In order to process a Payment:
Service: /payment/MY_PAYMENT_TOKEN/sendPayment
Method: Post
CREDIT CARD as payment method
Request fields:
-
method (string/required): Payment Method. Valid options: CREDITCARD
-
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.
All fields are required and there are no optional fields.
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: multipart/form-data' --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
}' '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
-
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:
{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"error": "",
"payment_status": "PROCESSING",
"customer_id": "CUS-9TPEZUNEJQ3L",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJsb2phMSIsIm”
}
Error response body:
{
"timestamp": 1488825108794,
"status": 500,
"error": "Internal Server Error",
"exception": "org.json.JSONException",
"message": "Request processing failed; nested exception is org.json.JSONException: JSONObject[\"card_number\"] not found.",
"path": "/payment/42afe884-f047-4452-a3db-65a7de76a9c5/sendPayment"
}
BOLETO as payment method
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
-
boleto_logo (string/optional): logo image URL to use in boleto image
Example Requests :
curl -X POST --header 'Content-Type: multipart/form-data' --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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZF69Q",
"boleto_amount": "190",
"payment_status": "PROCESSING",
"payment_token": "59557907-98e7-4457-bfc1-9efc3d0968bb",
"gateway_order_id": "ORD-RE1NVX7W7BRP",
"boleto_html": "eNrtXdl2L3bkO8gOfbhcewDOS53k29f7EPbanYPttW8+OLl20ffGTv42ydif7f4McsC/8v/A18OExw=",
"boleto_code": "00190.00009 01014.051005 00000.787176 7 72370000001000",
"error": "",
"customer_id": "CUS-2HH3DZBFTSVI",
"boleto_duedate": "2018-06-16"
}
Error response body:
{
"timestamp": 1488825108794,
"status": 500,
"error": "Internal Server Error",
"exception": "org.json.JSONException",
"message": "Request processing failed; nested exception is org.json.JSONException: JSONObject[\"boleto_expiration_date\"] not found.",
"path": "/payment/42afe884-f047-4452-a3db-65a7de76a9c5/sendPayment"
}
** List of possible payment statuses:**
-
CREATED: Payment was created and is waiting to be sent to acquirer
-
REJECTED: Acquirer rejected the payment. The complementary field ‘error’ may give 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
-
DECLINED: Payment was declined by the acquirer
-
ERROR: Unexpected error occurred during payment processing. The complementary field ‘error’ may give 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** **
Get Payment Status
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",
"createdAt": YYYY-MM-DD-HH:mm:SS,
"payment_status": "PROCESSING",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJsb2phMSIsImV4c",
"errorCode": ""
}
Error response body:
{
"timestamp": 1488825296727,
"status": 500,
"error": "Internal Server Error",
"exception": "java.lang.Exception",
"message": "Request processing failed; nested exception is java.lang.Exception: The payment 987239423879238492324234 cannot be found.",
"path": "/payment/42afe884-f047-4452-a3db-65a7de76a9c5"
}
Payment Status Callback
In order to be notified as soon as a payment status is changed via a callback URL.
Service: As specified to Customer Support
Method: POST
Fields:
- reference_id (string): External code created by merchant to reference this payment
Note:
To use this feature please user one of these options :
-
Create payment indicating an URL to post this callback using "notification_url" field (see Create Payment Order)
-
contact customer support and ask for Callback URL setup to use the same URL to all callbacks
This feature was modified for security reasons.
Example:
curl -X POST --header 'Content-Type: multipart/form-data' --header 'Accept: application/json' -d '{
"reference_id": "order-658-01"
}' '<callbackURL_for_merchant>'
SDKs
Client
-
Android: TBD
-
iOs: TBD
-
Javascript: TBD
-
Unity: TBD
Server
-
Java: TBD
-
.Net C#: TBD
-
Php: TBD