Skip to main content

Create Payment Order

  https://api-sandbox.letpay.io/payment

Create Payment Order​

Streamlining Payment Orders with Pre-Submission Preparation

This feature facilitates the preparation of a payment order prior to its submission for processing. It proves particularly beneficial in scenarios requiring preliminary information retrieval.

For instance, when the order currency differs from the payment currency, it allows for the acquisition of currency conversion rates.

Additionally, it enables the calculation of installment amounts and the preview of applicable fees that the customer will incur.

Request Body Parameters​

  • amount (required/string): Total amount of the payment with a maximum of two decimal places and must not be less than BRL 1.00.
  • asset (required/string): Reference code for the sale's asset.
  • reference_id (required/string/max 45 chars): External code created by the merchant to reference this payment.
  • contract_id (required/string): Merchant's contract ID.
  • person_firstname (required/string): First name of the person.
  • person_surname (required/string): Surname of the person.
  • person_taxid (required/string): Unique identifier for the person in the country tax system.
  • person_email (required/string): Person’s email provided to the merchant.
  • person_birth (optional/date/YYYY-MM-DD): Date of birth.
  • address_main (required/string): Main information of the address (e.g. street or Avenue).
  • address_number (required/int): Number for this address.
  • address_additional (optional/string): Additional information for this address (e.g. department).
  • address_locality (required/string): Billing address locality (e.g. neighborhood).
  • address_city (required/string): Billing address city.
  • address_state (required/string): Billing address state code.
  • address_country (required/string): Country code as ISO 3166-1 alpha-2 code.
  • address_zipcode (required/string): Billing address zip code.
  • address_phone_area (optional/int): Number of phone area code.
  • address_phone_country (optional/int): Number of country phone code.
  • address_phone (optional/string): Billing address telephone.
  • notification_url (optional/string): URL to post callbacks to this payment.
  • disable_address (optional/boolean): true to turn off required address fields. Default: false.
  • extra_data (optional/JSON): Any data pertinent to the merchant.
  • soft_descriptor (optional/string): Soft descriptor to use at transaction.
  • ip_address (optional/string): Remote IP Address(IPv4/IPv6).
  • payment_currency (required/string): Currency code in ISO-4217.
  • payment_country (required/string): Country code in ISO 3166-2.

Response​

  • payment_token (string): Unique payment identification for this payment.
  • refresh_token (string): Updated access token for future calls.
  • methods (array): Valid payment methods.
  • installments (array): Set of installments optional amounts with taxes.
  • totals (object): The 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 fee assigned to customer.
    • customer_amount (float): Total amount for customer (amount + customer_fees).

customer_fees (object): List of incident customer fees and respective values.

AUTHORIZATIONAPI Key
KeyX-Auth-Token
ValueMY_ACCESS_TOKEN

Body Raw(json)​

json
{
    "amount": 123.45,
    "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",
    "disable_address": false,
    "notification_url": "https://my.notification.url/callback/",
    "soft_descriptor": "SOFT_DESCRIPTOR",
    "ip_address": "0.0.0.0",
    "payment_country": "BR",
    "payment_currency": "BRL",
    "extra_data": {
        "my-conciliation-number": "xxxxxx"
    }
}

Example Request​

Example Request​

200 - Success
    curl --location 'https://api-sandbox.letpay.io/payment' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN' \
    --data-raw '{
        "amount": 123.45,
        "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.notification.url/callback/",
        "soft_descriptor": "SOFT_DESCRIPTOR",
        "ip_address": "0.0.0.0",
        "payment_country": "BR",
        "payment_currency": "BRL",
        "extra_data": {
            "my-conciliation-number": "xxxxxx"
        }
    }'

Example Response​

Header
  Content-Type: application/json
Body
    {
      "installments": [
        {
          "installments": 1,
          "amount": 123.45
        },
        {
          "installments": 2,
          "amount": 64.51
        },
        {
          "installments": 3,
          "amount": 43.64
        },
        {
          "installments": 4,
          "amount": 33.2
        },
        {
          "installments": 5,
          "amount": 26.95
        },
        {
          "installments": 6,
          "amount": 22.78
        },
        {
          "installments": 7,
          "amount": 19.81
        },
        {
          "installments": 8,
          "amount": 17.58
        },
        {
          "installments": 9,
          "amount": 15.85
        },
        {
          "installments": 10,
          "amount": 14.46
        },
        {
          "installments": 11,
          "amount": 13.33
        },
        {
          "installments": 12,
          "amount": 12.39
        }
      ],
      "methods": [
        "BOLETO",
        "PIX",
        "CREDITCARD"
      ],
      "payment": {
        "payment_token": "021b6048-81e2-49ad-b0e4-d9729a0efe17"
      },
      "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"
    }