Letpay 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 letpay and integrates letpay's API into Merchant's Store
- User chooses products -> Proceeds to checkout -> Chooses Payment method -> Submits Payment data -> Receives result -> Receives e-mail confirmation.
- letpay 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 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 letpay you will need to:
-
Register your merchant account with letpay
-
Accept letpay’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.letpay.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.17",
"token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTA0MDI5fQ.MN-IpKXB0duPbiao3zsIqb0c-CLDf0sffl5a6TUC6WhXKrIAJXrSvEOPP9OHve41Wb4Oa9lkHLf9iU2d8lJ6zA"
}
Error response body:
{
"timestamp": "2018-10-02T22:43:14.376+0000",
"status": 401,
"error": "Unauthorized",
"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.letpay.io/merchant/contracts'
Response:
- refresh_token: Refreshed token to be used within subsequent API calls
- contract: Contract objetc
- id: Contract Id which will be used when placing orders
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": "2018-10-02T22:46:53.294+0000",
"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.. 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): 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): letpay'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
- 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_area (int/required): number of phone area code
- address_phone_country (int/required): number of country phone 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": "BR",
"address_phone_country": 55,
"address_phone_area": 11,
"address_phone": "23716520",
"address_zipcode": "04514-041",
"notification_url": "https://my-domain.com/callback/"
}' 'https://api.letpay.io/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: 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.eyJzdWIiOiJsb2phMSIsImV4cCI6MTUwMzYxODcxN30.KMMKhNVJSyZ4CgWJ",
"methods": [
"CREDITCARD",
"BOLETO"
],
"payment": {
"payment_token": "c25a502d-d060-4a1d-a449-3ca78e4341dc"
},
"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
}
]
}
Error response body:
{
"timestamp": 1488824673716,
"status": 500,
"error": "Internal Server Error",
"exception": "letpay.exceptions.ContractNotFoundException",
"message": "Request processing failed; nested exception is letpay.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.letpay.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.eyJz....rcKARpP2RoQksvVNlXeiMGGBGNawpIhHQ",
"payment_status": "PROCESSING",
"payment_token": "f26d9745-6480-46b3-a347-5553c26685b7",
"error": ""
}
Error response body:
{
"timestamp": "2018-10-02T22:53:15.348+0000",
"status": 500,
"error": "Internal Server Error",
"message": "Request processing failed; nested exception is org.json.JSONException: Expected a ',' or '}' at 27 [character 3 line 2]",
"path": "/payment/f26d9745-6480-46b3-a347-5553c26685b7/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.letpay.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",
"boleto_html": "eNrtXdl2L3bkO8gOfbhcewDOS53k29f7EPbanYPttW8+OLl20ffGTv42ydif7f4McsC/8v/A18OExw=",
"boleto_code": "00190.00009 01014.051005 00000.787176 7 72370000001000",
"error": "",
"boleto_duedate": "2018-06-16"
}
Error response body:
{
"timestamp": 1488825108794,
"status": 500,
"error": "Internal Server Error",
"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** **
Token Payments
Process transactions with preregistered 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/required): Billing address telephone country
- address_phone_area (int/required): Billing address telephone area
- address_phone (string/required): 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)
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.letpay.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"
}
Error response body:
{
"timestamp": "2018-09-28T20:49:33.071+0000",
"message": "person_firstname: must not be empty",
"status": 500,
"error": "Validation error",
"path": "/token/person"
}
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' 'http://api.letpay.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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNzkxfQ.ROwz_JABEBNWIObTpn3LIFeXwTCOhxBaPrgth39RSxzY_MV-0ZsqL2Enc0QR5K7RBYFuTa-7CcsFOoqDdcSYuw",
"public_card_id": "CAR-1cee9922-47de-4603-b55b-166621a40426",
"status": 200,
"error": ""
}
Error response body:
{
"timestamp": "2018-09-28T20:49:33.071+0000",
"status": 500,
"error": "Internal Server Error",
"message": "Card cannot be found. 0a3ae5c4-0f1a-4a21-9492-016339c84f44",
"path": "/token/person"
}
Delete a Person
In order do 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' 'http://api.letpay.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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxODYwfQ.Vu-lunjVuN2RlgwgpaleTSiEHpv8hSSSgGh74pUPnH6vsvmWHDSD9nllwsjnK5tlUGaSawforRJm4pjF-mnSuQ",
"public_person_id": "PER-173ff98b-7f9c-420a-8059-cdc9a67e6f47",
"status": 200,
"error": ""
}
Error response body:
{
"timestamp": "2018-09-28T20:49:33.071+0000",
"status": 500,
"error": "Internal Server Error",
"message": "Person cannot be found. 90db952d-b7a2-4e3a-8a28-0fc517be0f4a",
"path": "/token/person"
}
List a Person's cards
Service: /token/person/PUBLIC_PERSON_ID
Method: Get
Request fields:
- None
Example Requests :
curl -X GET --header 'Content-Type: multipart/form-data' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
}' 'https://api.leypay.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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4MTgxOTI3fQ.luHkULp3bxap0vhr9qOKSLgVqZ_Szx2BlNDvQ5ytPEzBbqEkbwt3Xu8SU9xJlD31wC6FfoQY4NB8SODhGd6oLg",
"cards": [
"068af311-2438-4ffd-8bb7-b41289652fcb",
"1617c759-7a80-49f1-be63-d9fdcb5068a0"
]
}
Error response body:
{
"timestamp": "2018-09-28T20:49:33.071+0000",
"status": 500,
"error": "Internal Server Error",
"message": "Person cannot be found. 90db952d-b7a2-4e3a-8a28-0fc517be0f4a",
"path": "/token/person"
}
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: multipart/form-data' --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.letpay.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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTQxNDQzODEwfQ.TqsY1r7P_bjmKqjcMrrGEcgBz9Ct07_4VS2AArPkFNTVBn55OymIkksXg9s1aUv2ITLxo25SdF8PzWAwFDR0QA",
"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"
}
}
Error response body:
{
"timestamp": 1488825108794,
"status": 500,
"error": "Internal Server Error",
"message": "contract_id: must not be empty.",
"path": "/token/quote"
}
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): 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.
- 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
Example Requests :
curl -X POST --header 'Content-Type: multipart/form-data' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"amount": 100.10,
"asset": "BRL",
"reference_id": "IYWEGQR 90",
"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/"
}' 'https://api.letpay.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
- 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_fees (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.eyJzdWIiOiJsb2phMSIsImV4cCI6MTU0MTY4Mzc0OX0.AYtwjRlx19pGU_jE4QC1pZPT822C-YmK4n2WTqmiOkYUiZdMDtRVJjHEhLsidUwO6CxeE6nvcPwDNH1iatDNMA",
"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",
"original_amount": 100,
"original_asset": "USD",
"amount": 374.6,
"asset": "BRL",
"total_customer_fees": 37.46,
"customer_amount": 412.06,
"customer_fees": {
"TAXES_FEE": "37.46 BRL"
}
}
Error response body:
{
"timestamp": 1488825108794,
"status": 500,
"error": "Internal Server Error",
"message": "contract_id: must not be empty",
"path": "/token/"
}
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.letpay.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
- payment_token (string): Token to identify 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)
- Or contact customer support and ask for Callback URL setup to use the same URL to all callbacks
Example:
curl -X POST --header 'Content-Type: multipart/form-data' --header 'Accept: application/json' -d '{
"reference_id": "100000096",
"payment_token": "03a7db1b-60af-479b-bcdb-9f1bce328e8d"
}' '<callbackURL_for_merchant>'
Payment Status Lifecycle
Creditcard Payment
Creditcard Refund
Creditcard Chargeback
Boleto Payment
SDKs
Client
- Android: TBD
- iOs: TBD
- Javascript: TBD
- Unity: TBD
Server
- Java: TBD
- .Net C#: TBD
- Php: TBD