Skip to main content

PIX

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

Overview​

This process is designed with a smart approach to handle the compulsory Tax ID verification for all international transactions in Brazil, while maintaining optimal conversion rates. The process facilitates:

  • Immediate display of a QR code to the payer without the need for preliminary data collection, resulting in a higher conversion rate.
    • In order to use this process just send the required fields as marked below.
  • Utilization of a CPF (Cadastro de Pessoas Físicas) linked to the transaction, which merchants have previously gathered, or the option to collect it on the checkout page—this method generally yields a lower conversion rate, but can be advantageous in certain scenarios based on the merchant's specific needs.
    • In order to this process send the payer's CPF or CNPJ on the identifier field. In the case of an invalid tax id the transaction may be declined.

Minimum and Maximum Amounts​

CountryMinimumMaximumCurrency
Brazil0.0175,000BRL

Reference Checkout UI PIX​

Reference UI - PIXReference UI - PIX

PIX Flow​

Request description​

This HTTP POST request is used to create a PIX payment using the provided payload in the raw request body. The request payload includes the following fields:

  • contract_id (required/string): Merchant's contract id.
  • reference_id (required/string/max 45 chars): External code created by the merchant to reference this payment (e.g. order number).
  • notification_url (required/string): URL to post callbacks to this payment.
  • ip_address (optional/string): Remote IP Address(IPv4/IPv6).
  • payment (required/object): The payment data:
    • amount (required/float): Total amount of the payment. Value must have a maximum of two decimal places.
    • asset (optional/string): Reference code for asset for the sale's amount. Default: BRL.
    • currency (required/string): Currency code in ISO-4217.
    • country (required/string): Country code in ISO 3166-2.
    • pix (optional/object): The PIX data:
      • expiration_date (optional/string): Expiration date. If not provided, the system will assume 2 days from the current date. Supported formats: YYYY-MM-DD, YYYY-MM-DDTHH:mm:ss, YYYY-MM-DDTHH:mm:ss-03:00. If the time is not specified, the system will default to 23:59:59. The timezone will be UTC unless explicitly included in the string. The minimum allowed is 1 minute and the maximum is 10 days from the current date.
  • person (optional/object): The person data:
    • full_name (optional/string): Person’s full name.
    • email (optional/string): Person’s email provided to the merchant.
    • identifier (optional/string): Unique identifier for this person in country tax system (e.g. in Brazil: CPF).
    • birth_date (optional/date/YYYY-MM-DD): Person’s date of birth.

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": {
        "amount": 123.45,
        "asset": "BRL",
        "currency": "BRL",
        "country": "BR",
        "pix": {
            "expiration_date": "2025-08-22T12:34:56-03:00"
        }
    },
    "person": {
        "full_name": "Alice Sonnentag",
        "email": "[email protected]",
        "identifier": "39784045087",
        "birth_date": "1978-08-21"
    },
    "extra_data": {
        "my-conciliation-number": "xxxxxx"
    }
}

Example Request​

Example Request​

200 - Success
    curl --location 'https://api-sandbox.letpay.io/pix/simple' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN' \
    --data-raw '{
        "contract_id": "MY_CONTRACT_ID",
        "reference_id": "MY_REFERENCE_ID",
        "notification_url": "https://my.notification.url/callback/",
        "ip_address": "0.0.0.0",
        "payment": {
            "amount": 123.45,
            "asset": "BRL",
            "currency": "BRL",
            "country": "BR",
            "pix": {
                "expiration_date": "2025-08-22T12:34:56-03:00"
            }
        },
        "person": {
            "full_name": "Alice Sonnentag",
            "email": "[email protected]",
            "identifier": "39784045087",
            "birth_date": "1978-08-21"
        },
        "extra_data": {
            "my-conciliation-number": "xxxxxx"
        }
    }'

Example Response​

Header
  Content-Type: application/json
Body
    {
      "transaction_status": "PROCESSING",
      "payment_token": "0196e128-c6c7-4249-9f20-21a4c2eb1506",
      "reference_id": "MY_REFERENCE_ID",
      "pix_qr_code": "BASE64_ZIPPED_PNG",
      "pix_code": "00020101021226600016BR.COM.PAGSEGURO013612BB85E0-6156-45D0-BD28-5E04456185FF5204899953039865406123.455802BR5925ELPL Tecnologia em Pagame6009Sao Paulo63047B99",
      "pix_amount": "123.45",
      "refresh_token": "MY_ACCESS_TOKEN",
      "totals": {
        "amount": 123.45,
        "original_amount": 123.45,
        "original_asset": "BRL",
        "customer_fees": 0,
        "customer_amount": 123.45,
        "asset": "BRL"
      },
      "customer_fees": {}
    }