Welcome to LetPay's API Documentation
Our developer resources and API documentation have been created for developers to familiarize themselves with letpay'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 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.18",
"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 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 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 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_zipcode (string/required): Billing address zip code
- address_phone_area (int/required/max 2 characters): number of phone area code
- address_phone_country (int/required/max 2 characters): 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 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.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"
}
List of possible validation errors status/messages:
- status: 422
error: Unprocessable Entity
message: One of the parameters provided are incorrect: Date of birth, Full name, Tax Id.
- status: 500
error: Internal Server Error
message: Validation by CNPJ is not implemented yet
- status: 502
error: Bad Gateway
message: Error on services that validates tax id. Try again later
Simulate states
Cancelled state:
To make a payment simulate a cancelled state:
"person_firstname": "CANCEL",
"person_surname": "CANCEL",
"person_taxid": "11111111111"
In Analysis state:
To make a payment simulate a in analysis state:
"person_firstname": "ANALYZE",
"person_surname": "ANALYZE",
"person_taxid": "22222222222"
Rejected state:
To make a payment simulate a rejected state:
"person_firstname": "REJECT",
"person_surname": "REJECT",
"person_taxid": "00000000000"
Process Payment
In order to process a Payment:
Service: /payment/MY_PAYMENT_TOKEN/sendPayment
Method: Post
CREDIT CARD
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: 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
}' '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"
}
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
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
- boleto_logo (string/optional): logo image URL to use in boleto image
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.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/max 2 characters): Billing address telephone country
- address_phone_area (int/required/max 2 characters): 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-10-02T17:37:50.741+0000",
"status": 500,
"error": "Validation error",
"message": "personFirstname: must not be empty",
"path": "/token/person"
}
List of possible validation errors status/messages:
- status: 422
error: Unprocessable Entity
message: One of the parameters provided are incorrect: Date of birth, Full name, Tax Id.
- status: 500
error: Internal Server Error
message: Validation by CNPJ is not implemented yet
- status: 502
error: Bad Gateway
message: Error on services that validates tax id. Try again later
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: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
}' 'https://api.letpay.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): letpay'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.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/max 45 characters): 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.
- 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: application/json' --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
- 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.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",
"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"
}
}
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** **
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": ""
}
Canceled payment:
{
"paymentToken": "42afe884-f047-4452-a3db-65a7de76a9c5",
"createdAt": YYYY-MM-DD-HH:mm:SS,
"payment_status": "CANCELED",
"cancellation_details": {
"cancelled_by": "ACQUIRER",
"code": "3",
"description": "Issuer policy violation"
},
"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"
}
Cancelation codes
Cancelled 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 |
letpay | 7 | letpay policy |
letpay | 8 | Requested by the buyer |
letpay | 9 | Requested by the merchant |
letpay | 10 | Transaction not processed |
letpay | 13 | Invalid amount |
letpay | 14 | letpay security pollicy |
Callbacks
If the notification_url was provided when creating the payment, you will receive a callback as soon as the payment status changes.
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
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.
Example Request:
curl -X POST --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5"
}' 'https://api.letpay.io/refund'
Success response body:
{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_status": "PROCESSING",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJsb2phMSIsImV4c",
"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 payment amount
Example Request:
curl -X POST --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.letpay.io/refund'
Success response body:
{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_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 42afe884-f047-4452-a3db-65a7de76a9c5 cannot be found.",
"path": "/refund"
}
Status
In order to get the status of a Refund request:
** Service:** /refund/MY_PAYMENT_TOKEN
Method: GET
Request fields:
none
Possible statuses
- PROCESSING: The refund request has been received and it 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.letpay.io/refund/42afe884-f047-4452-a3db-65a7de76a9c5'
Success response body:
{
"payment_token": "42afe884-f047-4452-a3db-65a7de76a9c5",
"created_at": "2019-03-10 12:24:33.657",
"refund_status": "COMPLETED",
"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJsb2phMSIsImV4c",
"error_code": ""
}
Payment Status Lifecycle
Creditcard Payment
Creditcard Refund
Creditcard Chargeback
Boleto Payment
Testing Credit Cards
Bogus credit card data for testing pourposes
Brand | Number | Valid through | CVV |
---|---|---|---|
Mastercard | 5555666677778884 | 06/2022 | 123 |
Visa | 4012001037141112 | 06/2022 | 123 |
Amex | 376449047333005 | 06/2022 | 1234 |
Diners | 36490102462661 | 06/2022 | 123 |
Hiper | 6370950000000005 | 06/2022 | 123 |
Hipercard | 6062825624254001 | 06/2022 | 123 |
SDKs
Client
- Android: TBD
- iOs: TBD
- Javascript: TBD
- Unity: TBD
Server
- Java: TBD
- .Net C#: TBD
- Php: TBD