Skip to main content

Credit Cards

  POST https://api-sandbox.letpay.io/card/simple

Overview​

This API enables credit card payments by providing a structured request payload that includes contract details, payment information, card details, authentication parameters, and billing address.

Features​

  • Standard Credit Card Payments: Process payments using credit cards securely.
  • Delay Capture/Pre-Authorization: Allows capturing the payment at a later time after authorization.
  • External 3DS Payment: Supports external 3D Secure authentication for fraud prevention.
  • Save Card/Tokenization: Enables saving the card details for future transactions using tokenization.

Payment Flow​

Localizing Card Payment Requests​

To adapt card payment requests for other regions, you must modify the following fields using the international standards described below.

Country and Currency Codes​

  • Country Code: Change the country code (e.g., from BR) to the ISO 3166-1 alpha-2 code (a two-letter code) for your desired country (e.g., PE for Peru, MX for Mexico, etc.).
  • Currency Code: Update the currency code (e.g., from BRL) to the ISO 4217 code (a three-letter code) for the currency used in that country (e.g., PEN, MXN, COP, etc.).

Tax ID (tax_id_type)​

In addition to country and currency, you must provide the tax_id_type that corresponds to the user's identification document. This field, along with the tax_id (the document number itself), is often required for payment processing and tax compliance in Latin American countries.

The table below shows the valid tax_id_type values for each country where card transactions are supported.

CountryCountry CodeCurrency CodeValid tax_id_type ValuesDocument Name (Examples)
BrazilBRBRLCPF CNPJCadastro de Pessoas Físicas Cadastro Nacional de Pessoas Jurídicas
MexicoMXMXNCC CURP PP RFCCédula de Ciudadanía Unique Population Registry Code Passport Registro Federal de Contribuyentes
ColombiaCOCOPCC CE NIT PP TICédula de Ciudadanía Foreign resident card Número de Identificación Tributaria Passport Identity Card
ChileCLCLPCC CI PP RUTCédula de Ciudadanía Cédula de Identidad Passport Rol Único Tributario
PeruPEPENCE DNI PAS RUCForeign resident card Documento Nacional de Identidad Passport Registro Único de Contribuyente

Field Descriptions​

Main Fields​

  • contract_id (string): Identifier of the contract associated with the payment.
  • reference_id (string): Unique reference identifier for transaction tracking.
  • notification_url (string): URL for sending notifications about payment status.
  • ip_address (string): IP address of the customer making the payment.

payment Object​

  • method (string): Payment method used. Example: "CREDITCARD".
  • amount (number): Transaction amount.
  • asset (string): Transaction currency (example: "BRL").
  • soft_descriptor (string): Name appearing on the credit card statement.
  • delay_capture (boolean): Indicates if payment capture will be delayed.
  • save_card (boolean): Indicates if the card will be saved for future transactions.
  • currency (string): Currency used.
  • country (string): Transaction country.

card Object​

  • number (string): Credit card number.
  • holder (string): Cardholder's name.
  • cvv (string): Card security code.
  • year (number): Card expiration year.
  • month (number): Card expiration month.
  • installments (number): Number of installments.

person Object​

  • full_name (string): Payer's full name.
  • email (string): Payer's email.
  • tax_id (string): Payer's tax ID (CPF or CNPJ).
  • birth_date (string): Date of birth in "YYYY-MM-DD" format.

address Object​

  • main (string): Street name.
  • number (string): House/building number.
  • additional (string): Address complement.
  • locality (string): Neighborhood.
  • city (string): City.
  • state (string): State.
  • country (string): Country.
  • zip_code (string): ZIP code.

extra_data Object​

Additional data related to the transaction.

Considerations​

  • Ensure to use real and secure data in the implementation.
  • The notification URL must be prepared to receive POST calls with transaction status updates.
  • Additional features such as 3DS authentication and tokenization are covered in separate documentation.

Authorization​

AUTHORIZATIONAPI Key
KeyX-Auth-Token
ValueMY_ACCESS_TOKEN

Body Raw(json)​

json
{
    "contract_id": "MY_CONTRACT_ID",
    "reference_id": "MY_REFERENCE_ID",
    "notification_url": "https://my.notification.url/callback/",
    "ip_address": "0.0.0.0",
    "payment": {
        "method": "CREDITCARD",
        "amount": 123.45,
        "asset": "BRL",
        "soft_descriptor": "SOFT_DESCRIPTOR",
        "delay_capture": false,
        "save_card": false,
        "currency": "BRL",
        "country": "BR",
        "card": {
            "number": "5240082975622454",
            "holder": "Alice Sonnentag",
            "cvv": "123",
            "year": 2026,
            "month": 12,
            "installments": 1,
            "authentication": {
                "cavv": "BwABBylVaQAAAAFwllVpAAAAAAA=",
                "xid": "BwABBylVaQAAAAFwllVpAAAAAAA=",
                "eci": "05",
                "version": "2.1.0",
                "dstrans_id": "DIR_SERVER_TID"
            }
        }
    },
    "person": {
        "full_name": "Alice Sonnentag",
        "email": "[email protected]",
        "tax_id": "39784045087",
        "birth_date": "1978-08-21"
    },
    "extra_data": {
        "my-conciliation-number": "xxxxxx"
    }
}

This documentation provides an overview of how to integrate credit card payments using this API.

Example Request​

Credit Card (2DS)
    curl --location 'https://api-sandbox.letpay.io/card/simple' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN' \
    --data '{
        "contract_id": "MY_CONTRACT_ID",
        "reference_id": "MY_REFERENCE_ID",
        "notification_url": "https://my.notification.url/callback/",
        "payment": {
            "method": "CREDITCARD",
            "amount": 123.45,
            "asset": "BRL",
            "soft_descriptor": "SOFT_DESCRIPTOR",
            "currency": "BRL",
            "country": "BR",
            "card": {
                "number": "5240082975622454",
                "holder": "Alice Sonnentag",
                "cvv": "123",
                "year": 2026,
                "month": 12,
                "installments": 1
            }
        },
        "person": {
            "tax_id": "39784045087"
        }
    }'

Example Response​

Header
  Content-Type: application/json
Body
    {
      "transaction_status": "PROCESSING",
      "payment_token": "0196e128-c6c7-4249-9f20-21a4c2eb1506",
      "reference_id": "MY_REFERENCE_ID",
      "amount": "123.45",
      "totals": {
        "amount": 123.45,
        "original_amount": 123.45,
        "original_asset": "BRL",
        "customer_fees": 0,
        "customer_amount": 123.45,
        "asset": "BRL"
      },
      "customer_fees": {},
      "refresh_token": "MY_ACCESS_TOKEN"
    }