Skip to content
LetPay

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

  1. Merchant registers at LetPay and integrates LetPay's API into Merchant's Store

  2. User chooses products -> Proceeds to checkout -> Chooses Payment method -> Submits Payment data -> Receives result -> Receives e-mail confirmation.

  3. LetPay updates Payment status.

API Macro Flow

  1. Merchant registers at LetPay

  2. Merchant agrees to contracts terms and conditions

  3. Merchant receives credentials to process transactions

  4. Merchant authenticates against API and receives JWT Token

  5. Merchant requests Contract identification via API and receives Contract Id

  6. Merchant creates Payment order and receives Payment Token

  7. Merchant submits Payment data and receives Payment Id and status

  8. Merchant checks Payment status

Please note: Steps 6 and 7 are repeated for each new payment.

Macro Flow

image alt text

Getting Started

In order to integrate with LetPay you will need to:

  1. Register your merchant account with LetPay

  2. Accept LetPay’s merchant terms and conditions

Request API Key

In order to receive your API Key you need to:

  1. Accept fees and taxes for a specific Project

  2. 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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
  "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_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/required): 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

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/"
}' '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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
  "methods": [
    "CREDITCARD",
    "BOLETO",
    "PIX"
  ],
  "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.

Optional fields:

  • delay_capture (boolean/optional): true to pre-authorize payment for later capture. Default false.

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 3viously 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
}' '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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
    "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

  • PRE_AUTH: Payment has been pre-authorized and can be captured

Capture

In order to 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.letpay.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"
}

Error response body:

{
    "timestamp": "2018-10-02T22:53:15.348+0000",
    "status": 422,
    "error": "Unprocessable Entity",
    "message": "Payment token not pre authorized",
    "path": "/payment/f26d9745-6480-46b3-a347-5553c26685b7/capture"
}

Cancel

In order to to cancel a Pre-Authorized Payment:

Service: /payment/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"
}

Error response body:

{
    "timestamp": "2018-10-02T22:53:15.348+0000",
    "status": 422,
    "error": "Unprocessable Entity",
    "message": "Payment token not pre authorized",
    "path": "/payment/f26d9745-6480-46b3-a347-5553c26685b7/cancel"
}

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.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"
}

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

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.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
  • 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.LETPAY0136D6299C0D-00D0-42F0-AACD-389A105C892B520489995303986540510.005802BR5925ELPL Tecnologia em Pagame6009Sao Paulo6304B250",
  "error": "",
}

Error response body:

{
    "timestamp": "2018-10-02T17:37:50.741+0000",
    "status": 422,
    "error": "Unprocessable Entity",
    "message": "Error decription",
    "path": "/payment/42afe884-f047-4452-a3db-65a7de76a9c5/sendPayment"
}

3DS 2.0

In order to process Payments with 3DS 2.0

Macro Flow

image alt text

Get 3DS Token

Service: /payment/3ds/token

Method: Get

Prerequisite:

  • Have valid Access Token
  • Have valid Contract Id

Request fields:

  • 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.

Example Requests:

curl -X GET --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Auth-Token: MY_ACCESS_TOKEN' -d '{
  "contract_id": "MY_CONTRACT_ID"
}' 'https://api.letpay.io/payment/3ds/token'

Response:

  • 3ds_token (string): Token to identify this payment
  • refresh_token: Updated user token for next calls
  • expiration_date: expiration date of the token

Success response body:

{
    "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
    "3ds_token": "3DSd9745-6480-46b3-a347-5553c26685b7",
    "expiration_date": "2020-12-13T18:21:52.887161"
}

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/3ds/token"
}

Payment Form

In order to get 3DS authentication

Prerequisite:

  • Have valid 3DS Token
  • Host letpay's 3DS Javascript avaliable here.
  • Have valid letpay Contract Id
  • Have notification URL for payment status change callbacks

Example Html:

<html>
<head>
    <title>3DS 2.0 Demo</title>
    <script type="text/javascript">
        function init() {
            const token3DS = "MY_3DS_TOKEN"
            const contractId = "MY_CONTRACT_ID";
            const notificationURL = "MY_NOTIFICATION_URL";
            bpmpi_load(token3DS, contractId, notificationURL);
        }
        function sendOrder() {
            bpmpi_authenticate();
        }
    </script>
</head>
<body>
    <div>
        <h2>3DS 2.0 Demo</h2>
        <input type="hidden" name="authEnabled" class="bpmpi_auth" value="true" />
        <input type="hidden" name="authEnabledNotifyonly" class="bpmpi_auth_notifyonly" value="false" />
        <input type="hidden" name="currency" class="bpmpi_currency" value="986" />
        <input type="hidden" name="paymentMethod" class="bpmpi_paymentmethod" value="credit" />
        <input type="hidden" name="newCustomer" class="bpmpi_merchant_newcustomer" value="credit" />
        <input type="hidden" id="token3DS" name="accessToken" class="bpmpi_accesstoken"/>
        <input type="hidden" id="contractId" name="contractId" class="bpmpi_contract_id"/>
        <input type="hidden" id="notificationURL" name="notificationURL" class="bpmpi_notification_url" />
        <fieldset style="width:0">
            <legend>Pre Load Data</legend>
            <div>
                <b>*</b><label>3DS token:</label>
                <input type="text" size="50" id="token3DS" name="accessToken" class="bpmpi_accesstoken" value=""
                />
            </div>
            <div>
                <b>*</b><label>Contract Id:</label>
                <input type="text" size="50" id="contractId" name="contractId" class="bpmpi_contract_id" value="bcb88369-5cf1-4d6d-ae83-94994dd4d180" />
            </div>
            <input type="button" onclick="init()" value="Initialize JS" id="btnInit" />
        </fieldset>
        <div>
            <b>*</b><label>Reference Id:</label>
            <input type="text" size="50" name="orderNumber" class="bpmpi_ordernumber" value="MY_REFERENCE_ID" />
        </div>
        <div>
            <b>*</b><label>Amount:</label>
            <input type="text" size="50" name="amount" class="bpmpi_totalamount" value="1000" />
            <!-- in cents -->
        </div>
        <div>
            <b>*</b><label>Installments:</label>
            <input type="text" size="2" name="installments" class="bpmpi_installments" value="1" />
        </div>
        <div>
            <b>*</b><label>Payment Method:</label>
            <select name="paymentMethod" class="bpmpi_paymentmethod">
                <option value="credit" selected="selected">Credit</option>
                <option value="debit">Debit</option>
            </select>
        </div>
        <div>
            <b>*</b><label>Card Number:</label>
            <input type="text" size="50" name="cardNumber" class="bpmpi_cardnumber" value="4000000000001091" />
        </div>
        <div>
            <b>*</b><label>Expiration date:</label>
            <input type="text" size="2" name="expMonth" class="bpmpi_cardexpirationmonth" value="01" />
            <input type="text" size="4" name="expYear" class="bpmpi_cardexpirationyear" value="2021" />
        </div>
        <div>
            <label>Card Cvv:</label>
            <input type="text" size="4" name="cardCvv" class="bpmpi_cardcvv" value="123" />
        </div>
        <!-- Billing data -->
        <fieldset style="width:0">
            <legend>Billing Address</legend>
            <div>
                <label>Customer ID (CPF/CNPJ):</label>
                <input type="text" size="14" class="bpmpi_billto_customerid" value="12345678909" />
            </div>
            <div>
                <b>*</b><label>Name:</label>
                <input type="text" size="50" class="bpmpi_billto_contactname" value="Comprador de Teste" />
            </div>
            <div>
                <b>*</b><label>Phone number:</label>
                <input type="text" size="50" class="bpmpi_billto_phonenumber" value="999225626381" />
            </div>
            <div>
                <b>*</b><label>E-mail:</label>
                <input type="text" size="50" class="bpmpi_billto_email" value="[email protected]" />
            </div>
            <div>
                <b>*</b><label>Street 1:</label>
                <input type="text" size="50" class="bpmpi_billto_street1" value="Av Marechal Camara 160" />
            </div>
            <div>
                <b>*</b><label>Street 2:</label>
                <input type="text" size="50" class="bpmpi_billto_street2" value="Sala 934 Centro" />
            </div>
            <div>
                <b>*</b><label>City:</label>
                <input type="text" size="50" class="bpmpi_billto_city" value="Rio de Janeiro" />
            </div>
            <div>
                <b>*</b><label>State:</label>
                <input type="text" size="50" class="bpmpi_billto_state" value="RJ" />
            </div>
            <div>
                <b>*</b><label>Country:</label>
                <input type="text" size="2" class="bpmpi_billto_country" value="BR" />
            </div>
            <div>
                <b>*</b><label>Zipcode:</label>
                <input type="text" size="50" class="bpmpi_billto_zipcode" value="20020080" />
            </div>
        </fieldset>
        <!-- Order data -->
        <fieldset style="width:0">
            <legend>Order</legend>
            <div>
                <b>*</b><label>Merchant URL:</label>
                <input type="text" size="50" class="bpmpi_merchant_url" value="MY_ECOMMERCE_URL" />
            </div>
            <div>
                <b>*</b><label>Product code:</label>
                <input type="text" size="50" class="bpmpi_order_productcode" value="PHY" />
            </div>
        </fieldset>
        <input type="button" onclick="sendOrder()" value="Send Order" id="btnSendOrder" disabled=true title="Initialize JS first" />
    </div>
</body>

<script type="text/javascript">
    var env = getQueryString("env");

    function bpmpi_config() {
        return {
            onReady: function() {
                // Called when script initialization is finished
                document.getElementById("btnSendOrder").disabled = false;
                document.getElementById("btnInit").disabled = false;
            },
            onSuccess: function(e) {
                // Card allows authentication and customer was successfully authenticated
                var cavv = e.Cavv;
                var xid = e.Xid;
                var eci = e.Eci;
                var version = e.Version;
                var referenceId = e.ReferenceId;
                var paymentToken = e.PaymentToken;
            },
            onFailure: function(e) {
                // Card allows authentication, however, customer authentication did not succeed
                var xid = e.Xid;
                var eci = e.Eci;
                var version = e.Version;
                var referenceId = e.ReferenceId;
            },
            onUnenrolled: function(e) {
                // Card do not allow authentication
                var xid = e.Xid;
                var eci = e.Eci;
                var version = e.Version;
                var referenceId = e.ReferenceId;
            },
            onDisabled: function() {
                // Establishment does not require card authentication, or authentication is disabled
            },
            onError: function(e) {
                // Error during authentication process
                var xid = e.Xid;
                var eci = e.Eci;
                var returnCode = e.ReturnCode;
                var returnMessage = e.ReturnMessage;
                var referenceId = e.ReferenceId;
            },
            onUnsupportedBrand: function(e) {
                // Card brand does not support authentication
                var returnCode = e.ReturnCode;
                var returnMessage = e.ReturnMessage;
            },
            Environment: env ? env : "PRD",
            Debug: true
        };
    }

    function getQueryString(field) {
        var href = window.location.href;
        var reg = new RegExp('[?&]' + field + '=([^&#]*)', 'i');
        var string = reg.exec(href);
        return string ? string[1] : null;
    }
</script>
<script src="MY_PATH/client-v0.1.min.js" type="text/javascript"></script>
<script type="text/javascript">
    init();
</script>
</html>

Response:

Available through javascript events

  • onReady: Called when script initialization is finished
  • onSuccess: Card allows authentication and customer was successfully authenticated
  • onFailure: Card allows authentication, however, customer authentication did not succeed
  • onUnenrolled: Card do not allow authentication
  • onDisabled: Establishment does not require card authentication, or authentication is disabled
  • onError: Error during authentication process
  • onUnsupportedBrand: Card brand does not support authentication

Process Payment

In order to process a Payment:

Service: /payment/MY_PAYMENT_TOKEN/sendPayment

Method: Post

Request fields:

  • cavv (string/required): Cavv number returned by javascript events
  • eci (string/required): ECI number returned by javascript events
  • version (string/required): Version number returned by javascript events
  • request_id (string/required): Request 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": {
    "cavv": "AAABB2gHA1B5EFNjWQcDAAAAAAB=",
    "eci": "5",
    "version": "2",
    "request_id": ""
  },
  "save_card": false
}' 'https://api.letpay.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": ""
}

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

  • PRE_AUTH: Payment has been pre-authorized and can be captured

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 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

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.letpay.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/",
  "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"
    }
  },
  "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"
  }
}' 'https://api.letpay.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 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

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"
}

Error response body:

{
    "timestamp": "2018-10-02T17:37:50.741+0000",
    "status": 422,
    "error": "Unprocessable Entity",
    "message": "Invalid country",
    "path": "/boleto/simple"
}

List of possible validation errors status/messages:

- status: 403
  error: Forbidden
  message: Current contract cannot perform this action
- status: 422
  error: Unprocessable Entity
  message: Invalid country
- status: 502
  error: Bad Gateway
  message: Error contacting external service. Try again later

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

  • 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

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 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

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/",
    "payment": {
        "amount": 10.00
    },
    "person": {
        "full_name": "Alice Sonnentag",
        "email": "[email protected]",
        "tax_id": "39784045087",
        "birth_date": "1978-08-21"
    }
}' 'https://api.letpay.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 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

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.LETPAY0136D6299C0D-00D0-42F0-AACD-389A105C892B520489995303986540510.005802BR5925ELPL Tecnologia em Pagame6009Sao Paulo6304B250",
  "error": "",
}

Error response body:

{
    "timestamp": "2018-10-02T17:37:50.741+0000",
    "status": 422,
    "error": "Unprocessable Entity",
    "message": "Error description",
    "path": "/pix/simple"
}

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/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.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' 'https://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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
    "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' 'https://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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
    "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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
  "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.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"
    }
}

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:

  • delay_capture (boolean/optional): true to pre-authorize payment for later capture. Default false.
  • 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": "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
}' '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.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"
    }
}

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

Capture

In order to 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.letpay.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"
}

Error response body:

{
    "timestamp": "2018-10-02T22:53:15.348+0000",
    "status": 422,
    "error": "Unprocessable Entity",
    "message": "Payment token not pre authorized",
    "path": "/token/f26d9745-6480-46b3-a347-5553c26685b7/capture"
}

Cancel

In order to 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"
}

Error response body:

{
    "timestamp": "2018-10-02T22:53:15.348+0000",
    "status": 422,
    "error": "Unprocessable Entity",
    "message": "Payment token not pre authorized",
    "path": "/token/f26d9745-6480-46b3-a347-5553c26685b7/cancel"
}

Checkout

Hosted Credit Card tokenization and Boleto payment solution.

Flows

Credit Card

  1. Initiate Checkout solution using Credit Card as payment method
  2. User informs Personal information and Credit Card data
  3. Data is encripted
  4. Retrieve Credit Card payment token
  5. Authenticate on API
  6. Request Tokenized Credit Card Ids
  7. Process Payment

Boleto

  1. Initiate Checkout solution using Boleto as payment method
  2. User informs Personal information
  3. Boleto is presented to the user
  4. Retrieve payment token

Pix

  1. Initiate Checkout solution using Pix as payment method
  2. User informs Personal information
  3. Pix code is presented to the user
  4. Retrieve payment token

Front end

Include our javascript library in the section of your HTML

<script src="https://checkout.letpay.io/checkout-v0.1.js">

Initiate the sollution using html markup:

Method I: HTML

<body>
  ...
  <letpay-checkout
    amount="137.76"
    asset="BRL"
    reference-id="MY_REFERENCE_ID"
    contract-id="MY_CONTRACT_ID"
    method="CREDITCARD"
  ><letpay-checkout/>
  ...
</body>

Method II: Javascript

...
const letpayCheckout = new letpayCheckout({
  amount="137.76",
  asset="BRL",
  referenceId="MY_REFERENCE_ID",
  contractId="MY_CONTRACT_ID",
  method="CREDITCARD",
}); 
...

In specific element

...
const letpayCheckout = new letpayCheckout({
  amount="137.76",
  asset="BRL",
  referenceId="MY_REFERENCE_ID",
  contractId="MY_CONTRACT_ID",
  method="CREDITCARD",
}); 
letpayCheckout.mountIn('#checkout-container-element')
...

Start

...
const letpayCheckout = new letpayCheckout({
  amount="137.76",
  asset="BRL",
  referenceId="MY_REFERENCE_ID",
  contractId="MY_CONTRACT_ID",
  method="CREDITCARD",
}); 
letpayCheckout.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 letpay'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 CREDITCARD / BOLETO / PIX yes n/a Payment Method.
card-installments cardInstallments number no 1 Number of installments. Used if method is equal to CREDITCARD
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
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).

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 ba 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-use-mobile lightboxUseMobile boolean no false Force to open the payment form inside the own page instead of in another tab on mobile devices
lightbox-disable-address lightboxDisableAddress boolean no false If true disables the user's address collection step. Doesn't have effect when using 3ds
lightbox-partial-address lightboxPartialAddress boolean no false If true requires only user's zip code and number

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

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

Handlinbg Events

Using .on(event, function) / .off(event, function) methods

const letpayCheckout = new LetPayCheckout({...});

function handler(event) {
  console.log(event.detail[0])
};

// to add a listener
letpayCheckout.on('checkout-success', handler);

// to remove a listener
letpayCheckout.off('checkout-success', handler);

Using .addEventListener(type, listener) / .removeEventListener(type, listener) methods

const letpayCheckout = document.querySelector('letpay-checkout');

function handler(event) {
  console.log(event.detail[0])
};

// to add a listener
letpayCheckout.addEventListener('checkout-success', handler);

// to remove a listener
letpayCheckout.removeEventListener('checkout-success', handler);

Closing the lightbox

letpayCheckout.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.letpay.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"
}

Error response body:

{
    "timestamp": "2018-10-02T17:37:50.741+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Invalid payment token.",
    "path": "/checkout/PAYMENT_TOKEN"
}

List of possible validation errors status/messages:

- status: 401
  error: Unauthorized
  message: Invalid payment token.
- status: 500
  error: Internal Server Error
  message: Error on retrieve publicCardId from paymentToken 'PAYMENT_TOKEN'
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
  }
}' 'https://api.letpay.io/checkout/sendPayment'

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"
    }
}

Error response body:

{
  "timestamp": 1488825108794,
  "status": 502,
  "error": "Bad Gateway",
  "message": "Error contacting external service. Try again later",
  "path": "/checkout/sendPayment"
}

List of possible validation errors status/messages:

- status: 422
  error: Unprocessable Entity
  message: Invalid public person id
- status: 500
  error: Internal Server Error
  message: Method 'TEST_METHOD' is not implemented yet
- status: 502
  error: Bad Gateway
  message: "Error contacting external service. Try again later

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

Capture

In order to 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.letpay.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"
}

Error response body:

{
    "timestamp": "2018-10-02T22:53:15.348+0000",
    "status": 422,
    "error": "Unprocessable Entity",
    "message": "Payment token not pre authorized",
    "path": "/checkout/f26d9745-6480-46b3-a347-5553c26685b7/capture"
}
Cancel

In order to 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"
}

Error response body:

{
    "timestamp": "2018-10-02T22:53:15.348+0000",
    "status": 422,
    "error": "Unprocessable Entity",
    "message": "Payment token not pre authorized",
    "path": "/checkout/f26d9745-6480-46b3-a347-5553c26685b7/cancel"
}

Boleto

Retrieve the payment_token returned by the CheckoutJS library.

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,
  "paymentStatus": "PROCESSING",
  "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
  "errorCode": ""
}

Canceled payment:

{
  "paymentToken": "42afe884-f047-4452-a3db-65a7de76a9c5",
  "createdAt": YYYY-MM-DD-HH:mm:SS,
  "paymentStatus": "CANCELED",
  "cancellation_details": {
      "cancelled_by": "ACQUIRER",
      "code": "3",
      "description": "Issuer policy violation"
  },
  "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
  "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 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.

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 '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.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.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 payment amount

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.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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
  "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"
}

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
  • amount (number/optional): amount to be refunded. Must be equal or inferior to the customer amount.

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.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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
  "errorCode": ""
}

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.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
  "error_code": ""
}

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.letpay.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"
        }
    ]
}

Payment Status Lifecycle

Creditcard Payment

Creditcard Lyfecylcle

Creditcard Refund

Creditcard Refund Lyfecylcle

Creditcard Chargeback

Creditcard Chargeback Lyfecylcle

Boleto Payment

Boleto Lyfecylcle

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