Skip to main content

Payments

This page describes the complete lifecycle of a Payment: its status flow, what each status means, the notifications you receive, the structure of the callback payload, and how to query updates.

Status Map​

This diagram illustrates the complete status flow for Payments. A webhook notification is automatically sent to the merchant's API for every single status change.

Status Description​

StatusDescription
CREATEDThe payment has been initiated and is awaiting processing.
PROCESSINGThe payment request has been accepted by the processor and is currently under processing.
PRE_AUTHORIZEDThe payment is pre-authorized and available for the merchant to capture.
PAIDThe payment has been authorized by the processor. Refer to the "received amount" field to verify the paid sum.
PARTIALLY_REFUNDEDPartial refunds have been issued, not covering the full payment amount.
REFUNDEDThe payment was refunded by the merchant to its full amount.
DECLINEDThe payment was not accepted. The "errors" field contains an error code and description detailing the reason for decline.
CANCELEDThe payment was voided due to reasons such as transaction expiration or cancellation of pre-authorized transactions.
ERRORAn unexpected error occurred during the payment process. The "errors" field contains an error code and description explaining the error's cause.
IN_ANALYSISThe transaction is currently under manual review.
DISPUTEThe payer has initiated a dispute over the transaction.
DISPUTE_REFUNDEDThe disputed payment has been refunded.
POST_REFUND_DISPUTEA dispute was raised post-refund.
DISPUTE_RECOVEREDThe payment was subject to a dispute, which has now been resolved in favor of the merchant.
DISPUTE_FINALThe payment was disputed and the decision to revert it is final.

Notification​

A webhook notification is automatically sent to your notification_url on every status change. The notification is a lightweight signal — after receiving it, query the Update Endpoint to fetch the current status and full transaction details.

The same Payment status flow applies regardless of how the payment was created. The callback always includes reference_id and payment_token, plus optional context fields depending on the payment's origin. Select how the payment was created to see what the callback carries:

Created directly through the Payments API. The callback carries the reference_id you set in the create-payment request and the payment_token.

Callback body
{
  "reference_id": "REFERENCE_ID",
  "payment_token": "PAYMENT_ID"
}

A single payment can combine these contexts (for example, a subscription charge created through a checkout), in which case the callback carries all the matching fields:

Callback body
{
  "reference_id": "REFERENCE_ID",
  "payment_token": "PAYMENT_ID",
  "subscription_id": "SUBSCRIPTION_ID",
  "subscription_reference_id": "SUBSCRIPTION_REFERENCE_ID",
  "checkout_id": "CHECKOUT_ID",
  "checkout_reference_id": "CHECKOUT_REFERENCE_ID"
}

After receiving the callback, query the Update Endpoint for full details.

Update Endpoint​

Merchants can access transaction information either via callback or on demand. We notify you by sending a request to the URL you provide; if a notification attempt fails, we retry starting 2 seconds after the failure for up to 6 hours, after which you can manually trigger a notification from your merchant dashboard. After receiving a callback, retrieve the current status and full details of a payment through one of the endpoints below.

The response contains the following fields:

  • paymentToken (string): The unique identifier of the payment transaction.
  • createdAt (string, yyyy-MM-dd'T'HH:mm:ss.SSS): The timestamp indicating the creation time of the transaction.
  • transactionStatus (string): The status of the payment transaction.
  • expirationDate (string, yyyy-MM-dd'T'HH:mm:ss.SSS): The maximum period defined for making a payment.
  • errorCode (string): Code for payment decline.
  • currency (string): The currency used for the transaction.
  • amount_received (number): The amount received for the transaction.
  • refunded_amount (number): The refunded amount for the transaction.
  • reference (string): The reference associated with the transaction.
  • method (string): The payment method used, e.g., PIX.
  • confirmation_date (string, yyyy-MM-dd'T'HH:mm:ss.SSS): The date and time when the payment was confirmed.
  • subscription_id (string): The subscription identifier associated with the transaction, when the payment was generated by a subscription.
  • customer_info (object): Information about the customer (customer_contact, identifier, identifier_type, payer_identifier, payer_identifier_type, payer_name).
  • cancellation_details (object): The description of the cancellation details, if any.
  • extra_data (object): Additional data related to the transaction.
  • refresh_token (string): The refresh token associated with the transaction.
AUTHORIZATIONAPI Key
KeyX-Auth-Token
ValueMY_ACCESS_TOKEN

By Payment Token​

Identify the transaction using its paymentToken.

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

Example Request​

200 - Success
    curl --location 'https://api-sandbox.letpay.io/payment/MY_PAYMENT_TOKEN' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN'

Example Response​

Header
  Content-Type: application/json
Body
    {
      "paymentToken": "2f1c0103-b6fe-4e99-864c-d20c68b97a85",
      "createdAt": "2024-01-16T20:03:46.618",
      "transactionStatus": "PAID",
      "currency": "BRL",
      "amount_received": 10,
      "refunded_amount": 0,
      "reference": "MY_REFERENCE_ID",
      "expiration_date": "2024-01-18T20:03:46.618",
      "method": "PIX",
      "confirmation_date": "2024-01-16T20:03:46.618",
      "subscription_id": "c0894e16-c772-476f-b617-a2375736e1ec",
      "customer_info": {
          "customer_contact": "[email protected]",
          "identifier": "00000000000",
          "identifier_type": "CPF",
          "payer_identifier": "12345678909",
          "payer_identifier_type": "CPF",
          "payer_name": "Alice Sonnentag"
      },
      "errorCode": "00.00.0000",
      "extra_data": {
        "my-conciliation-number": "xxxxxx"
      },
      "refresh_token": "MY_ACCESS_TOKEN"
    }

By Reference ID​

When the transaction ID is not available, use the reference_id to retrieve the corresponding payment details. The response returns a payments array.

GET https://api-sandbox.letpay.io/payment/reference/MY_REFERENCE_ID

Example Request​

200 - Success
    curl --location 'https://api-sandbox.letpay.io/payment/reference/MY_REFERENCE_ID' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN'

Example Response​

Header
  Content-Type: application/json
Body
    {
      "payments": [
        {
          "paymentToken": "bf1fe0df-8f22-4e86-a718-db9cad56e845",
          "createdAt": "2024-01-16T13:26:38.605",
          "transactionStatus": "PAID",
          "currency": "BRL",
          "amount_received": 10,
          "refunded_amount": 0,
          "reference": "MY_REFERENCE_ID",
          "expirationDate": "2024-01-18T13:26:38.000",
          "method": "PIX",
          "confirmation_date": "2024-01-16T20:03:46.618",
          "subscription_id": "c0894e16-c772-476f-b617-a2375736e1ec",
          "customer_info": {
              "customer_contact": "[email protected]",
              "identifier": "00000000000",
              "identifier_type": "CPF",
              "payer_identifier": "12345678909",
              "payer_identifier_type": "CPF",
              "payer_name": "Alice Sonnentag"
          },
          "extra_data": {
            "my-conciliation-number": "xxxxxx"
          }
        }
      ],
      "refresh_token": "MY_ACCESS_TOKEN"
    }