Skip to main content
API docs by Redocly

API Pix (1.0)

Download OpenAPI specification:Download

Swagger

Environments

Staging Environment: https://api.sdb.lbpay.com.br

Production Environment: Provided once you complete the testing

This document provides the technical specifications for integrating with our PIX API, designed for iGaming platforms. Follow the guidelines below to ensure a successful implementation.

Authentication

We use the OAuth 2.0 standard with Bearer Tokens. You must request an access token by sending your credentials to the authentication endpoint.

Replace the client_id and client_secret 

curl --request POST \
  --url 'https://api.sdb.lbpay.com.br/v1/oauth2/token' \
  --header 'accept: application/json' \
  --header 'content-type: multipart/form-data' \
  --form client_id=YOUR_CLIENT_ID \
  --form grant_type=client_credentials \
  --form client_secret=YOUR_CLIENT_SECRET

Terminology

  • PIX Processor: London Bridge, acting as the Banking-as-a-Service (BaaS) provider responsible for processing PIX transactions.
  • Gaming Operator: The iGaming platform integrating with this API.
  • Deposit (Pix-In): When a player initiates a deposit request, an invoice is generated as a PIX QR Code or copy-and-paste payload. The player pays this invoice to credit their gaming wallet.
  • Withdrawal (Pix-Out): When a player requests a withdrawal, a PIX transfer (cash-out) is executed to the player’s bank account.
  • Refund: Returning the funds of a previously completed deposit back to the player.
  • Internal Transfer: Instantaneous transfers between gaming wallets.

API Controllers

Note: All API requests must be prefixed with /v1 in the URL path.
Controller Description
Pix-In Core endpoints for creating and retrieving player deposit transactions.
Pix-Out Core endpoints for initiating and querying player withdrawal transactions.
Pix Refund Endpoints used to return funds from previously completed deposits.
Internal Transfer Endpoints that manage wallet‑to‑wallet transfers within the operator’s environment.
Webhook Endpoints used to configure callback URLs and receive asynchronous notifications from the platform.
Balance Endpoints for querying account balances, including real-time and closing-day balances.

Webhook Notifications

Operators must implement a webhook endpoint capable of receiving real-time notifications from our platform. Whenever a transaction changes status (e.g., a deposit is confirmed), a webhook event is sent to the URL configured by the operator.

Webhook configuration and management can be handled through the Webhook endpoints available in this API.

Our notification system includes automatic retry logic. However, to ensure full reconciliation of events, we strongly recommend maintaining a fallback polling mechanism to retrieve any undelivered status updates in the event your service becomes temporarily unavailable.

Customer Journey for Deposits

1. The player logs into the gaming operator’s platform and selects Pix as the deposit method. 2. The player chooses a predefined amount or enters a custom deposit value. 3. The operator generates a Pix charge (QR Code and Copy-and-Paste payload) using the POST /v1/pix/deposit/immediate-charge endpoint. 4. The player scans the QR Code or pastes the payload into their banking app to complete the payment. 5. Our platform processes the transaction and sends a real-time webhook notification to the operator with the final status. 6. Upon receiving the notification, the operator immediately credits the player’s gaming wallet.

Customer Journey for Withdrawals

1. The player submits a withdrawal request from their gaming wallet. 2. The player provides the Pix key associated with their bank account (CPF, email, phone number, or random key). 3. After validating the player’s balance and compliance rules, the operator sends a withdrawal request through the POST /v1/pix/withdraw endpoint, including the Pix key and the requested amount. 4. Our API processes the Pix cash-out and transfers the funds to the player’s bank account within seconds. 5. A real-time webhook notification is sent to the operator confirming the successful settlement of the withdrawal.

Pix-In

Create immediate charge (Pix Deposit)

Endpoint to create an immediate charge for iGaming. The txId must be generated by the PSP.

Request Body schema: application/json
required

Pix Deposit data

amount
required
integer

Amount in cents, must be positive

description
string <= 140 characters

Optional free-text description of the deposit, up to 140 characters

object

Expected payer information used to validate the incoming payment

expiresIn
required
integer

Expiration in seconds

externalId
required
string <= 100 characters

External ID, max 100 characters

object

Optional key-value metadata, up to 50 entries, keys up to 50 characters and values up to 200 characters

pixKey
required
string <= 77 characters

Pix key of the destination account, up to 77 characters

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "description": "string",
  • "expectedPayer": {
    },
  • "expiresIn": 86400,
  • "externalId": "string",
  • "metadata": {
    },
  • "pixKey": "string"
}

Response samples

Content type
application/json
{
  • "amount": 0,
  • "brCode": "string",
  • "chargeId": "string",
  • "createdAt": "string",
  • "description": "string",
  • "expectedPayer": {
    },
  • "expiresAt": "string",
  • "externalId": "string",
  • "pixKey": "string",
  • "status": "PENDING"
}

Query immediate charge (Pix Deposit)

Endpoint to query a specific immediate charge by its ChargeID.

path Parameters
chargeId
required
string

deposit chargeId (UUIDv4)

Responses

Response samples

Content type
application/json
{
  • "amount": 0,
  • "brCode": "string",
  • "chargeId": "string",
  • "createdAt": "string",
  • "debtor": {
    },
  • "description": "string",
  • "expectedPayer": {
    },
  • "expiresAt": "string",
  • "externalId": "string",
  • "metadata": {
    },
  • "paidAt": "string",
  • "pixKey": "string",
  • "pixTransaction": {
    },
  • "status": "PENDING"
}

Pix-Out

Initiate withdrawal by bank account

Initiates a PIX transfer (cash-out) to the player's bank account (ISPB + account details).

Request Body schema: application/json
required

Withdrawal data

amount
required
integer

Amount in cents, must be a positive number

required
object

Destination bank account for the withdrawal

description
string <= 140 characters

Optional free-text description of the withdrawal, up to 140 characters

externalId
required
string [ 1 .. 100 ] characters

Client-provided identifier used for idempotency, up to 100 characters

object

Optional key-value metadata, up to 50 entries, keys up to 50 characters and values up to 200 characters

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "creditor": {
    },
  • "description": "string",
  • "externalId": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "amount": 0,
  • "createdAt": "string",
  • "externalId": "string",
  • "status": "INITIATED",
  • "transactionId": "string"
}

Initiate withdrawal by PIX key

Initiates a PIX transfer (cash-out) to the player's registered PIX key.

Request Body schema: application/json
required

Withdrawal data

amount
required
integer

Amount in cents, must be an positivi number

description
string <= 140 characters

Optional free-text description of the withdrawal, up to 140 characters

required
object

Expected creditor information used to validate the destination

externalId
required
string [ 1 .. 100 ] characters

Client-provided identifier used for idempotency, up to 100 characters

object

Optional key-value metadata, up to 50 entries, keys up to 50 characters and values up to 200 characters

pixKey
required
string <= 77 characters

Pix key of the destination account, up to 77 characters

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "description": "string",
  • "expectedCreditor": {
    },
  • "externalId": "string",
  • "metadata": {
    },
  • "pixKey": "string"
}

Response samples

Content type
application/json
{
  • "amount": 0,
  • "createdAt": "string",
  • "externalId": "string",
  • "status": "INITIATED",
  • "transactionId": "string"
}

Get withdrawal by ExternalID

Retrieves the details of a specific withdrawal transaction by its ID.

path Parameters
externalId
required
string

Withdraw externalId (up to 100 characters)

Responses

Response samples

Content type
application/json
{
  • "amount": 0,
  • "createdAt": "string",
  • "creditor": {
    },
  • "endToEndId": "string",
  • "errorCode": "ACCOUNT_MISMATCH",
  • "errorDescription": "string",
  • "expectedCreditor": {
    },
  • "externalId": "string",
  • "initiationType": "PIX_KEY",
  • "metadata": {
    },
  • "settlementDateTime": "string",
  • "status": "INITIATED",
  • "transactionId": "string",
  • "updatedAt": "string"
}

Pix Refund

Create refund

Initiates a PIX refund (reversal) for a received transaction identified by its original End-to-end ID. The {id} is a customer-defined identifier used for idempotency and to distinguish partial refunds on the same transaction.

path Parameters
endToEndId
required
string

Original End-to-end ID of the PIX transaction (32 alphanumeric characters)

Request Body schema: application/json
required

Refund data

amount
required
integer

Refund amount in cents, must be greater than zero and not exceed the original transaction amount

description
string <= 140 characters

Free-text reason for the refund, up to 140 characters

endToEndId
required
string

Original End-to-end ID of the PIX transaction being refunded, 32 alphanumeric characters

externalId
required
string [ 1 .. 100 ] characters

Customer-defined identifier for idempotency and to distinguish partial refunds, 1 to 100 characters with no control characters. Stored and compared exactly as sent (case-sensitive)

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "description": "string",
  • "endToEndId": "string",
  • "externalId": "string"
}

Response samples

Content type
application/json
{
  • "amount": 0,
  • "canBeReversedUntil": "string",
  • "createdAt": "string",
  • "creditor": {
    },
  • "errorCode": "string",
  • "errorDescription": "string",
  • "externalId": "string",
  • "leftAmount": 0,
  • "originalAmount": 0,
  • "originalEndToEndId": "string",
  • "refundEndToEndId": "string",
  • "settlementDateTime": "string",
  • "status": "PROCESSING",
  • "totalReversedAmount": 0,
  • "updatedAt": "string"
}

Get refund

Retrieves the details of a specific PIX refund identified by the original transaction End-to-end ID and the customer-defined refund ID.

path Parameters
endToEndId
required
string

Original End-to-end ID of the PIX transaction (32 alphanumeric characters)

externalId
required
string

Customer-defined refund identifier (1-100 characters), case-sensitive and matched exactly as sent on creation. Must be percent-encoded when it contains URL-reserved characters (e.g. '/' as %2F)

Responses

Response samples

Content type
application/json
{
  • "amount": 0,
  • "canBeReversedUntil": "string",
  • "createdAt": "string",
  • "creditor": {
    },
  • "errorCode": "string",
  • "errorDescription": "string",
  • "externalId": "string",
  • "leftAmount": 0,
  • "originalAmount": 0,
  • "originalEndToEndId": "string",
  • "refundEndToEndId": "string",
  • "settlementDateTime": "string",
  • "status": "PROCESSING",
  • "totalReversedAmount": 0,
  • "updatedAt": "string"
}

Pix Automático

Receiver-side (PSP recebedor) API for Pix Automático — Journey 3: recurrence creation with a composite QR, first payment, payer authorization, scheduled charges, settlement and refunds. Events are delivered to the account webhook registered with PUT /v1/webhook (see the Webhook tag).

In the LB Pay product the receiver must be a CNPJ; the payer may be a CPF or a CNPJ.

Conventions

  • Monetary values are integers in centavos (BRL cents). 1000 = R$ 10,00.
  • Request and response bodies use camelCase.
  • Dates are YYYY-MM-DD; timestamps are ISO 8601.
  • Every mutating request carries its own externalId in the body (max 255 chars). Re-sending the same externalId with the same body returns the stored response; the same externalId with a different body returns 409 IDEMPOTENCY_ERROR. Idempotency records are kept for 48 hours.
  • Responses include x-request-id and x-correlation-id headers for traceability.

Errors

Business errors return:

{ "error": { "type": "pixAutomaticError", "code": "AMOUNT_OUT_OF_RANGE", "message": "...", "retryable": false } }

Validation and transport errors return type: invalidRequestError with code: HTTP_<status>. Unexpected failures return type: apiError, code: INTERNAL_ERROR (HTTP 500). See the Errors guide for the full catalog.

Create recurrence

Creates a Journey 3 recurrence and its composite QR (textContent, EMV payload). The response also carries recUrlAccessToken, the token embedded in the QR that the payer PSP resolves via GET /rec/{accessToken}.

Business preconditions: valid receiver CNPJ, payer CNPJ (LB Pay policy), amount between R$ 1,00 and R$ 1.000.000,00, expiration between 60 seconds and 30 calendar days, firstPaymentDate at least 2 calendar days after expiration, and no pending or payer-rejected journey for the same payer in the last 30 days.

Posting the same externalId again for the same wallet returns the existing recurrence.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Request body

receiverCnpj
required
string

Receiver CNPJ: 14 characters, numeric or alphanumeric (12 characters 0-9/A-Z plus 2 numeric check digits). Punctuation is accepted and stripped; letters are upper-cased.

pixKey
required
string [ 1 .. 200 ] characters

Receiver Pix key that receives the charges.

externalId
required
string [ 1 .. 100 ] characters

Your identifier, unique per wallet. Re-posting the same value returns the existing recurrence.

expiresIn
required
integer [ 60 .. 2592000 ]

Seconds until the payer journey expires (60 s to 30 calendar days).

amount
integer [ 100 .. 100000000 ]

Fixed charge amount in centavos (R$ 1,00 to R$ 1.000.000,00). Omit for a variable-amount recurrence. Mutually exclusive with minimumAmount (AMOUNT_MODEL_CONFLICT).

object

Free-form string map echoed back on the resource.

required
object (pixautomatic.RecurrenceDetails)
required
object (pixautomatic.ExpectedPayer)
minimumAmount
integer [ 1 .. 100000000 ]

Variable model floor (BACEN valorMinimoRecebedor): the payer may only set their own maximum at or above this value. Does not constrain charge amounts. Mutually exclusive with amount.

firstPaymentAmount
integer [ 100 .. 100000000 ]

Amount of the immediate first Pix in the composite QR. Required for variable recurrences (FIRST_PAYMENT_AMOUNT_REQUIRED); forbidden for fixed ones (FIRST_PAYMENT_AMOUNT_NOT_ALLOWED), which charge amount.

Responses

Request samples

Content type
application/json
{
  • "receiverCnpj": "11.222.333/0001-81",
  • "pixKey": "financeiro@suaempresa.com.br",
  • "externalId": "contrato-plano-premium-0042",
  • "expiresIn": 259200,
  • "amount": 14990,
  • "metadata": {
    },
  • "recurrenceDetails": {
    },
  • "expectedPayer": {
    }
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.recurrence",
  • "id": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "receiverCnpj": "11222333000181",
  • "receiverPixKey": "financeiro@suaempresa.com.br",
  • "externalId": "contrato-plano-premium-0042",
  • "contract": {
    },
  • "expectedPayer": {
    },
  • "frequency": "MONTHLY",
  • "firstPaymentDate": "2026-09-01",
  • "lastPaymentDate": "2027-08-01",
  • "totalCharges": 12,
  • "amount": 14990,
  • "allowPostDuePayment": true,
  • "descriptionToPayer": "Assinatura Plano Premium",
  • "journeyType": "JOURNEY_3",
  • "status": "AUTHORIZED",
  • "statusDetailed": "VALIDATION_SUCCEEDED",
  • "firstPaymentStatus": "SETTLED",
  • "firstPaymentEndToEndId": "E52833288202608271430a1b2c3d4e5f",
  • "municipalityCode": "3550308",
  • "expiresAt": "2026-08-27T23:59:59.000Z",
  • "recUrlAccessToken": "3f9a1c2d4e5f60718293a4b5c6d7e8f9",
  • "textContent": "00020101021226990014br.gov.bcb.pix2577...",
  • "metadata": {
    },
  • "cancellationReason": null,
  • "version": 3,
  • "createdAt": "2026-08-25T14:00:00.000Z",
  • "updatedAt": "2026-08-27T14:32:10.000Z",
  • "authorizedAt": "2026-08-27T14:32:10.000Z",
  • "cancelledAt": null,
  • "completedAt": null,
  • "amountType": "FIXED",
  • "firstPaymentAmount": 14990
}

List recurrences

Cursor-paginated list of the wallet’s recurrences.

Authorizations:
ApiKeyAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Page size (1-100).

cursor
string

Opaque cursor from nextCursor.

status
string

Filter by summary status.

payerTaxId
string

Filter by payer CNPJ (punctuation ignored).

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "hasMore": false,
  • "nextCursor": null
}

Get recurrence

Returns a recurrence owned by the authenticated wallet.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Recurrence id, format RR + 8-digit ISPB + YYYYMMDD + 11 hex chars (29 chars).

Responses

Response samples

Content type
application/json
{
  • "object": "pix_automatic.recurrence",
  • "id": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "receiverCnpj": "11222333000181",
  • "receiverPixKey": "financeiro@suaempresa.com.br",
  • "externalId": "contrato-plano-premium-0042",
  • "contract": {
    },
  • "expectedPayer": {
    },
  • "frequency": "MONTHLY",
  • "firstPaymentDate": "2026-09-01",
  • "lastPaymentDate": "2027-08-01",
  • "totalCharges": 12,
  • "amount": 14990,
  • "allowPostDuePayment": true,
  • "descriptionToPayer": "Assinatura Plano Premium",
  • "journeyType": "JOURNEY_3",
  • "status": "AUTHORIZED",
  • "statusDetailed": "VALIDATION_SUCCEEDED",
  • "firstPaymentStatus": "SETTLED",
  • "firstPaymentEndToEndId": "E52833288202608271430a1b2c3d4e5f",
  • "municipalityCode": "3550308",
  • "expiresAt": "2026-08-27T23:59:59.000Z",
  • "recUrlAccessToken": "3f9a1c2d4e5f60718293a4b5c6d7e8f9",
  • "textContent": "00020101021226990014br.gov.bcb.pix2577...",
  • "metadata": {
    },
  • "cancellationReason": null,
  • "version": 3,
  • "createdAt": "2026-08-25T14:00:00.000Z",
  • "updatedAt": "2026-08-27T14:32:10.000Z",
  • "authorizedAt": "2026-08-27T14:32:10.000Z",
  • "cancelledAt": null,
  • "completedAt": null,
  • "amountType": "FIXED",
  • "firstPaymentAmount": 14990
}

Cancel recurrence

Cancels a recurrence. All open schedules are cancelled together; if the recurrence was AUTHORIZED, a pain.011 cancellation is sent to the payer PSP.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Recurrence id, format RR + 8-digit ISPB + YYYYMMDD + 11 hex chars (29 chars).

Request Body schema: application/json
required

Request body

externalId
required
string [ 1 .. 255 ] characters

Your idempotency identifier for this command. Re-sending the same value with the same body replays the stored response; a different body returns 409 IDEMPOTENCY_ERROR.

reason
required
string
Enum: "ACCOUNT_CLOSED" "RECEIVER_COMPANY_CLOSED" "RECEIVER_REQUEST_ERROR" "FRAUD_SUSPECTED" "DUPLICATE_AUTHORIZATION" "RECEIVER_REQUESTED" "PAIN_009_TIMEOUT"

Receiver-side cancellation reason. PAYER_REQUESTED is reserved for payer-initiated cancellations and cannot be sent here.

observation
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "externalId": "req-cancel-001",
  • "reason": "RECEIVER_REQUESTED",
  • "observation": "Cliente encerrou o plano."
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.recurrence",
  • "id": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "receiverCnpj": "11222333000181",
  • "receiverPixKey": "financeiro@suaempresa.com.br",
  • "externalId": "contrato-plano-premium-0042",
  • "contract": {
    },
  • "expectedPayer": {
    },
  • "frequency": "MONTHLY",
  • "firstPaymentDate": "2026-09-01",
  • "lastPaymentDate": "2027-08-01",
  • "totalCharges": 12,
  • "amount": 14990,
  • "allowPostDuePayment": true,
  • "descriptionToPayer": "Assinatura Plano Premium",
  • "journeyType": "JOURNEY_3",
  • "status": "AUTHORIZED",
  • "statusDetailed": "VALIDATION_SUCCEEDED",
  • "firstPaymentStatus": "SETTLED",
  • "firstPaymentEndToEndId": "E52833288202608271430a1b2c3d4e5f",
  • "municipalityCode": "3550308",
  • "expiresAt": "2026-08-27T23:59:59.000Z",
  • "recUrlAccessToken": "3f9a1c2d4e5f60718293a4b5c6d7e8f9",
  • "textContent": "00020101021226990014br.gov.bcb.pix2577...",
  • "metadata": {
    },
  • "cancellationReason": null,
  • "version": 3,
  • "createdAt": "2026-08-25T14:00:00.000Z",
  • "updatedAt": "2026-08-27T14:32:10.000Z",
  • "authorizedAt": "2026-08-27T14:32:10.000Z",
  • "cancelledAt": null,
  • "completedAt": null,
  • "amountType": "FIXED",
  • "firstPaymentAmount": 14990
}

Get schedule

Returns a scheduled charge owned by the authenticated wallet, including the attempts[] trail of SPI dispatches.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Schedule id, format pixsched_ + 32 hex chars.

Responses

Response samples

Content type
application/json
{
  • "object": "pix_automatic.schedule",
  • "id": "pixsched_7c2e4a6b8d0f1a3c5e7092b4d6f8a1c3",
  • "recurrenceId": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "cycleNumber": 2,
  • "txid": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a190",
  • "amount": 14990,
  • "originalDueDate": "2026-10-01",
  • "dueDate": "2026-10-01",
  • "purpose": "AGND",
  • "status": "SUCCESS",
  • "statusDetailed": "SETTLED",
  • "paymentInformationId": "P7c2e4a6b8d0f1a3c5e7092b4d",
  • "regulatoryMessageId": "M52833288a1b2c3d4e5f60718293a4b5",
  • "endToEndId": "E52833288202610010800f1e2d3c4b5a",
  • "reconciliationId": "7c2e4a6b8d0f1a3c5e7092b4d6",
  • "rejectionCode": null,
  • "rejectionReason": null,
  • "retryOfScheduleId": null,
  • "attemptCount": 1,
  • "nextAttemptAt": null,
  • "metadata": {
    },
  • "attempts": [
    ],
  • "createdAt": "2026-09-24T12:00:00.000Z",
  • "updatedAt": "2026-10-01T08:00:05.000Z",
  • "settledAt": "2026-10-01T08:00:05.000Z",
  • "cancelledAt": null
}

Cancel schedule

Cancels a scheduled charge. Allowed only while the schedule is CREATED, PENDING or SCHEDULED, and only until 22:00 (America/Sao_Paulo) of the day before dueDate. When the instruction had already been sent to the payer PSP, a camt.055 cancellation is emitted.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Schedule id, format pixsched_ + 32 hex chars.

Request Body schema: application/json
required

Request body

externalId
required
string [ 1 .. 255 ] characters

Your idempotency identifier for this command. Re-sending the same value with the same body replays the stored response; a different body returns 409 IDEMPOTENCY_ERROR.

reason
required
string [ 1 .. 500 ] characters

Free-text reason.

Responses

Request samples

Content type
application/json
{
  • "externalId": "req-sched-cancel-001",
  • "reason": "Renegociação da fatura do ciclo com o pagador."
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.schedule",
  • "id": "pixsched_7c2e4a6b8d0f1a3c5e7092b4d6f8a1c3",
  • "recurrenceId": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "cycleNumber": 2,
  • "txid": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a190",
  • "amount": 14990,
  • "originalDueDate": "2026-10-01",
  • "dueDate": "2026-10-01",
  • "purpose": "AGND",
  • "status": "SUCCESS",
  • "statusDetailed": "SETTLED",
  • "paymentInformationId": "P7c2e4a6b8d0f1a3c5e7092b4d",
  • "regulatoryMessageId": "M52833288a1b2c3d4e5f60718293a4b5",
  • "endToEndId": "E52833288202610010800f1e2d3c4b5a",
  • "reconciliationId": "7c2e4a6b8d0f1a3c5e7092b4d6",
  • "rejectionCode": null,
  • "rejectionReason": null,
  • "retryOfScheduleId": null,
  • "attemptCount": 1,
  • "nextAttemptAt": null,
  • "metadata": {
    },
  • "attempts": [
    ],
  • "createdAt": "2026-09-24T12:00:00.000Z",
  • "updatedAt": "2026-10-01T08:00:05.000Z",
  • "settledAt": "2026-10-01T08:00:05.000Z",
  • "cancelledAt": null
}

Resolve recurrence location (public)

Resolves the location Rec embedded in the composite QR. Called by the payer's PSP/app — not by the receiver integration. No authentication.

path Parameters
accessToken
required
string^[0-9a-f]{32}$

32-hex token from recUrlAccessToken.

Responses

Response samples

Content type
application/json
{
  • "recurrenceId": "RR52833288202608103f9a1c2d4e5",
  • "receiverPixKey": "financeiro@suaempresa.com.br",
  • "receiverCnpj": "11222333000181",
  • "amount": 14990,
  • "frequency": "MONTHLY",
  • "firstPaymentDate": "2026-09-01",
  • "lastPaymentDate": "2027-08-01",
  • "contract": {
    },
  • "expectedPayer": {
    },
  • "status": "PENDING",
  • "statusDetailed": "AWAITING_FIRST_PAYMENT",
  • "expirationDate": "2026-08-27T23:59:59.000Z",
  • "amountType": "FIXED"
}

List schedules

Cursor-paginated list of the wallet’s scheduled charges.

Authorizations:
ApiKeyAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Page size (1-100).

cursor
string

Opaque cursor from nextCursor.

status
string

Filter by summary status.

recurrenceId
string

Filter by recurrence id.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "hasMore": false,
  • "nextCursor": null
}

Create cycle charge (schedule)

Creates the scheduled charge (agendamento, purpose AGND) for a cycle of an authorized recurrence. Equivalent to the BACEN CobR creation. One charge per cycle; the due date must be between 2 and 10 calendar days ahead (Brasília calendar).

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Recurrence id.

Request Body schema: application/json
required

Request body

externalId
required
string [ 1 .. 255 ] characters

Your idempotency identifier for this charge. Re-sending the same value with the same body replays the stored response; a different body returns 409 IDEMPOTENCY_ERROR.

cycleNumber
required
integer >= 2

Cycle to charge. Cycle 1 is the first payment; scheduled charges start at 2. Must not exceed totalCharges.

amount
required
integer >= 100

Centavos; must equal the recurrence amount (fixed-amount phase).

dueDate
required
string^\d{4}-\d{2}-\d{2}$

Settlement date. Must be between 2 and 10 calendar days from today (Brasília), inside the recurrence window and the cycle window. Non-business days are shifted forward (originalDueDate keeps the requested date).

object

Responses

Request samples

Content type
application/json
{
  • "externalId": "req-sched-001",
  • "cycleNumber": 2,
  • "amount": 14990,
  • "dueDate": "2026-10-01",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.schedule",
  • "id": "pixsched_7c2e4a6b8d0f1a3c5e7092b4d6f8a1c3",
  • "recurrenceId": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "cycleNumber": 2,
  • "txid": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a190",
  • "amount": 14990,
  • "originalDueDate": "2026-10-01",
  • "dueDate": "2026-10-01",
  • "purpose": "AGND",
  • "status": "SUCCESS",
  • "statusDetailed": "SETTLED",
  • "paymentInformationId": "P7c2e4a6b8d0f1a3c5e7092b4d",
  • "regulatoryMessageId": "M52833288a1b2c3d4e5f60718293a4b5",
  • "endToEndId": "E52833288202610010800f1e2d3c4b5a",
  • "reconciliationId": "7c2e4a6b8d0f1a3c5e7092b4d6",
  • "rejectionCode": null,
  • "rejectionReason": null,
  • "retryOfScheduleId": null,
  • "attemptCount": 1,
  • "nextAttemptAt": null,
  • "metadata": {
    },
  • "attempts": [
    ],
  • "createdAt": "2026-09-24T12:00:00.000Z",
  • "updatedAt": "2026-10-01T08:00:05.000Z",
  • "settledAt": "2026-10-01T08:00:05.000Z",
  • "cancelledAt": null
}

Create post-due retry

Commands a post-due retry (NTAG) for a failed charge — equivalent to the BACEN POST /cobr/{txid}/retentativa/{data}. Requires allowPostDuePayment=true on the recurrence. Up to 3 distinct dates within 7 calendar days of the original due date, same amount, commanded by 23:59 of the previous day.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Schedule id of the failed charge.

Request Body schema: application/json
required

Request body

externalId
required
string [ 1 .. 255 ] characters

Your idempotency identifier for this retry. Re-sending the same value with the same body replays the stored response; a different body returns 409 IDEMPOTENCY_ERROR.

retryDate
required
string^\d{4}-\d{2}-\d{2}$

1 to 7 calendar days after the original due date; at most 3 distinct retry dates; cannot reach the next cycle; must be commanded by 23:59 (America/Sao_Paulo) of the previous day.

Responses

Request samples

Content type
application/json
{
  • "externalId": "req-retry-001",
  • "retryDate": "2026-10-03"
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.schedule",
  • "id": "pixsched_7c2e4a6b8d0f1a3c5e7092b4d6f8a1c3",
  • "recurrenceId": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "cycleNumber": 2,
  • "txid": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a190",
  • "amount": 14990,
  • "originalDueDate": "2026-10-01",
  • "dueDate": "2026-10-01",
  • "purpose": "AGND",
  • "status": "SUCCESS",
  • "statusDetailed": "SETTLED",
  • "paymentInformationId": "P7c2e4a6b8d0f1a3c5e7092b4d",
  • "regulatoryMessageId": "M52833288a1b2c3d4e5f60718293a4b5",
  • "endToEndId": "E52833288202610010800f1e2d3c4b5a",
  • "reconciliationId": "7c2e4a6b8d0f1a3c5e7092b4d6",
  • "rejectionCode": null,
  • "rejectionReason": null,
  • "retryOfScheduleId": null,
  • "attemptCount": 1,
  • "nextAttemptAt": null,
  • "metadata": {
    },
  • "attempts": [
    ],
  • "createdAt": "2026-09-24T12:00:00.000Z",
  • "updatedAt": "2026-10-01T08:00:05.000Z",
  • "settledAt": "2026-10-01T08:00:05.000Z",
  • "cancelledAt": null
}

Simulate: first payment settled

Simulates the payer paying the composite QR: the first Pix settles (payer = expectedPayer, amount = the recurrence amount). The recurrence moves to statusDetailed=FIRST_PAYMENT_SUCCESS.

Sandbox only — in production these routes return 404. Optional overrides simulate a divergent payer or amount.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json

Optional overrides

payerTaxId
string

Override to simulate a divergent payer — surfaces EXPECTED_PAYER_MISMATCH (422).

payerName
string

Accepted for parity; payer validation is by tax id (as in the real pacs.008 handler).

amount
integer

Override to simulate a divergent amount — surfaces FIRST_PAYMENT_AMOUNT_MISMATCH (422).

Responses

Request samples

Content type
application/json
{
  • "payerTaxId": "00111222000133"
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.recurrence",
  • "id": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "receiverCnpj": "11222333000181",
  • "receiverPixKey": "financeiro@suaempresa.com.br",
  • "externalId": "contrato-plano-premium-0042",
  • "contract": {
    },
  • "expectedPayer": {
    },
  • "frequency": "MONTHLY",
  • "firstPaymentDate": "2026-09-01",
  • "lastPaymentDate": "2027-08-01",
  • "totalCharges": 12,
  • "amount": 14990,
  • "allowPostDuePayment": true,
  • "descriptionToPayer": "Assinatura Plano Premium",
  • "journeyType": "JOURNEY_3",
  • "status": "AUTHORIZED",
  • "statusDetailed": "VALIDATION_SUCCEEDED",
  • "firstPaymentStatus": "SETTLED",
  • "firstPaymentEndToEndId": "E52833288202608271430a1b2c3d4e5f",
  • "municipalityCode": "3550308",
  • "expiresAt": "2026-08-27T23:59:59.000Z",
  • "recUrlAccessToken": "3f9a1c2d4e5f60718293a4b5c6d7e8f9",
  • "textContent": "00020101021226990014br.gov.bcb.pix2577...",
  • "metadata": {
    },
  • "cancellationReason": null,
  • "version": 3,
  • "createdAt": "2026-08-25T14:00:00.000Z",
  • "updatedAt": "2026-08-27T14:32:10.000Z",
  • "authorizedAt": "2026-08-27T14:32:10.000Z",
  • "cancelledAt": null,
  • "completedAt": null,
  • "amountType": "FIXED",
  • "firstPaymentAmount": 14990
}

Simulate: payer PSP authorization

Simulates the payer PSP authorization result (pain.012). APPROVED moves the recurrence to AUTHORIZED/VALIDATION_SUCCEEDED (requires the first payment settled); REJECTED fails it.

Sandbox only — in production these routes return 404.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required

Request body

outcome
required
string
Enum: "APPROVED" "REJECTED"
reason
string

Optional rejection reason echoed on the recurrence.

Responses

Request samples

Content type
application/json
{
  • "outcome": "APPROVED"
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.recurrence",
  • "id": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "receiverCnpj": "11222333000181",
  • "receiverPixKey": "financeiro@suaempresa.com.br",
  • "externalId": "contrato-plano-premium-0042",
  • "contract": {
    },
  • "expectedPayer": {
    },
  • "frequency": "MONTHLY",
  • "firstPaymentDate": "2026-09-01",
  • "lastPaymentDate": "2027-08-01",
  • "totalCharges": 12,
  • "amount": 14990,
  • "allowPostDuePayment": true,
  • "descriptionToPayer": "Assinatura Plano Premium",
  • "journeyType": "JOURNEY_3",
  • "status": "AUTHORIZED",
  • "statusDetailed": "VALIDATION_SUCCEEDED",
  • "firstPaymentStatus": "SETTLED",
  • "firstPaymentEndToEndId": "E52833288202608271430a1b2c3d4e5f",
  • "municipalityCode": "3550308",
  • "expiresAt": "2026-08-27T23:59:59.000Z",
  • "recUrlAccessToken": "3f9a1c2d4e5f60718293a4b5c6d7e8f9",
  • "textContent": "00020101021226990014br.gov.bcb.pix2577...",
  • "metadata": {
    },
  • "cancellationReason": null,
  • "version": 3,
  • "createdAt": "2026-08-25T14:00:00.000Z",
  • "updatedAt": "2026-08-27T14:32:10.000Z",
  • "authorizedAt": "2026-08-27T14:32:10.000Z",
  • "cancelledAt": null,
  • "completedAt": null,
  • "amountType": "FIXED",
  • "firstPaymentAmount": 14990
}

Simulate: payer cancels the recurrence

Simulates the payer cancelling in their banking app (pain.011): the recurrence becomes CANCELLED with cancellationReason=PAYER_REQUESTED and open schedules are cancelled.

Sandbox only — in production these routes return 404.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "object": "pix_automatic.recurrence",
  • "id": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "receiverCnpj": "11222333000181",
  • "receiverPixKey": "financeiro@suaempresa.com.br",
  • "externalId": "contrato-plano-premium-0042",
  • "contract": {
    },
  • "expectedPayer": {
    },
  • "frequency": "MONTHLY",
  • "firstPaymentDate": "2026-09-01",
  • "lastPaymentDate": "2027-08-01",
  • "totalCharges": 12,
  • "amount": 14990,
  • "allowPostDuePayment": true,
  • "descriptionToPayer": "Assinatura Plano Premium",
  • "journeyType": "JOURNEY_3",
  • "status": "AUTHORIZED",
  • "statusDetailed": "VALIDATION_SUCCEEDED",
  • "firstPaymentStatus": "SETTLED",
  • "firstPaymentEndToEndId": "E52833288202608271430a1b2c3d4e5f",
  • "municipalityCode": "3550308",
  • "expiresAt": "2026-08-27T23:59:59.000Z",
  • "recUrlAccessToken": "3f9a1c2d4e5f60718293a4b5c6d7e8f9",
  • "textContent": "00020101021226990014br.gov.bcb.pix2577...",
  • "metadata": {
    },
  • "cancellationReason": null,
  • "version": 3,
  • "createdAt": "2026-08-25T14:00:00.000Z",
  • "updatedAt": "2026-08-27T14:32:10.000Z",
  • "authorizedAt": "2026-08-27T14:32:10.000Z",
  • "cancelledAt": null,
  • "completedAt": null,
  • "amountType": "FIXED",
  • "firstPaymentAmount": 14990
}

Simulate: payer PSP response to a charge

Simulates the payer PSP response to the charge instruction (pain.014). The simulator dispatches the pending instruction automatically, so you can call it right after creating the schedule.

Sandbox only — in production these routes return 404.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required

Request body

outcome
required
string
Enum: "ACCEPTED" "REJECTED"
rejectionCode
string

Scheme code to simulate (e.g. AC05, AM09). Defaults to AC06 when omitted on rejection.

rejectionReason
string

Responses

Request samples

Content type
application/json
{
  • "outcome": "REJECTED",
  • "rejectionCode": "AC05"
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.schedule",
  • "id": "pixsched_7c2e4a6b8d0f1a3c5e7092b4d6f8a1c3",
  • "recurrenceId": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "cycleNumber": 2,
  • "txid": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a190",
  • "amount": 14990,
  • "originalDueDate": "2026-10-01",
  • "dueDate": "2026-10-01",
  • "purpose": "AGND",
  • "status": "SUCCESS",
  • "statusDetailed": "SETTLED",
  • "paymentInformationId": "P7c2e4a6b8d0f1a3c5e7092b4d",
  • "regulatoryMessageId": "M52833288a1b2c3d4e5f60718293a4b5",
  • "endToEndId": "E52833288202610010800f1e2d3c4b5a",
  • "reconciliationId": "7c2e4a6b8d0f1a3c5e7092b4d6",
  • "rejectionCode": null,
  • "rejectionReason": null,
  • "retryOfScheduleId": null,
  • "attemptCount": 1,
  • "nextAttemptAt": null,
  • "metadata": {
    },
  • "attempts": [
    ],
  • "createdAt": "2026-09-24T12:00:00.000Z",
  • "updatedAt": "2026-10-01T08:00:05.000Z",
  • "settledAt": "2026-10-01T08:00:05.000Z",
  • "cancelledAt": null
}

Simulate: charge settlement

Simulates the settlement outcome on the due date (pacs.008). SETTLED completes the cycle (status=SUCCESS, endToEndId set); REJECTED fails it with the given scheme code.

Sandbox only — in production these routes return 404.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required

Request body

outcome
required
string
Enum: "SETTLED" "REJECTED"
rejectionCode
string

Scheme code to simulate. Defaults to AC06 when omitted on rejection.

rejectionReason
string

Responses

Request samples

Content type
application/json
{
  • "outcome": "SETTLED"
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.schedule",
  • "id": "pixsched_7c2e4a6b8d0f1a3c5e7092b4d6f8a1c3",
  • "recurrenceId": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "cycleNumber": 2,
  • "txid": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a190",
  • "amount": 14990,
  • "originalDueDate": "2026-10-01",
  • "dueDate": "2026-10-01",
  • "purpose": "AGND",
  • "status": "SUCCESS",
  • "statusDetailed": "SETTLED",
  • "paymentInformationId": "P7c2e4a6b8d0f1a3c5e7092b4d",
  • "regulatoryMessageId": "M52833288a1b2c3d4e5f60718293a4b5",
  • "endToEndId": "E52833288202610010800f1e2d3c4b5a",
  • "reconciliationId": "7c2e4a6b8d0f1a3c5e7092b4d6",
  • "rejectionCode": null,
  • "rejectionReason": null,
  • "retryOfScheduleId": null,
  • "attemptCount": 1,
  • "nextAttemptAt": null,
  • "metadata": {
    },
  • "attempts": [
    ],
  • "createdAt": "2026-09-24T12:00:00.000Z",
  • "updatedAt": "2026-10-01T08:00:05.000Z",
  • "settledAt": "2026-10-01T08:00:05.000Z",
  • "cancelledAt": null
}

Simulate: journey expiration

Expires a PENDING recurrence as the expiration worker would (payer never completed the journey): status=EXPIRED, event pixAutomaticRecurrenceExpired.

Sandbox only — in production these routes return 404 (and the service refuses to boot with the simulator enabled).

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "object": "pix_automatic.recurrence",
  • "id": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "receiverCnpj": "11222333000181",
  • "receiverPixKey": "financeiro@suaempresa.com.br",
  • "externalId": "contrato-plano-premium-0042",
  • "contract": {
    },
  • "expectedPayer": {
    },
  • "frequency": "MONTHLY",
  • "firstPaymentDate": "2026-09-01",
  • "lastPaymentDate": "2027-08-01",
  • "totalCharges": 12,
  • "amount": 14990,
  • "allowPostDuePayment": true,
  • "descriptionToPayer": "Assinatura Plano Premium",
  • "journeyType": "JOURNEY_3",
  • "status": "AUTHORIZED",
  • "statusDetailed": "VALIDATION_SUCCEEDED",
  • "firstPaymentStatus": "SETTLED",
  • "firstPaymentEndToEndId": "E52833288202608271430a1b2c3d4e5f",
  • "municipalityCode": "3550308",
  • "expiresAt": "2026-08-27T23:59:59.000Z",
  • "recUrlAccessToken": "3f9a1c2d4e5f60718293a4b5c6d7e8f9",
  • "textContent": "00020101021226990014br.gov.bcb.pix2577...",
  • "metadata": {
    },
  • "cancellationReason": null,
  • "version": 3,
  • "createdAt": "2026-08-25T14:00:00.000Z",
  • "updatedAt": "2026-08-27T14:32:10.000Z",
  • "authorizedAt": "2026-08-27T14:32:10.000Z",
  • "cancelledAt": null,
  • "completedAt": null,
  • "amountType": "FIXED",
  • "firstPaymentAmount": 14990
}

Simulate: payer PSP cancels the charge (camt.055)

Simulates the payer PSP cancelling the charge instruction. FAIL also auto-creates the same-day RIFL reissue, returned as riflSchedule.

Sandbox only — in production these routes return 404 (and the service refuses to boot with the simulator enabled).

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required

Request body

reason
required
string
Enum: "CCLD" "FAIL"

CCLD = plain cancellation; FAIL = cancellation that auto-creates a same-day RIFL reissue.

Responses

Request samples

Content type
application/json
{
  • "reason": "FAIL"
}

Response samples

Content type
application/json
{
  • "schedule": {
    },
  • "riflSchedule": {
    }
}

Simulate: payer PSP response timeout

Applies the terminal timeout the worker applies when pain.014 never arrives: status=FAILED, rejectionCode=PAYER_RESPONSE_TIMEOUT.

Sandbox only — in production these routes return 404 (and the service refuses to boot with the simulator enabled).

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "object": "pix_automatic.schedule",
  • "id": "pixsched_7c2e4a6b8d0f1a3c5e7092b4d6f8a1c3",
  • "recurrenceId": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "cycleNumber": 2,
  • "txid": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a190",
  • "amount": 14990,
  • "originalDueDate": "2026-10-01",
  • "dueDate": "2026-10-01",
  • "purpose": "AGND",
  • "status": "SUCCESS",
  • "statusDetailed": "SETTLED",
  • "paymentInformationId": "P7c2e4a6b8d0f1a3c5e7092b4d",
  • "regulatoryMessageId": "M52833288a1b2c3d4e5f60718293a4b5",
  • "endToEndId": "E52833288202610010800f1e2d3c4b5a",
  • "reconciliationId": "7c2e4a6b8d0f1a3c5e7092b4d6",
  • "rejectionCode": null,
  • "rejectionReason": null,
  • "retryOfScheduleId": null,
  • "attemptCount": 1,
  • "nextAttemptAt": null,
  • "metadata": {
    },
  • "attempts": [
    ],
  • "createdAt": "2026-09-24T12:00:00.000Z",
  • "updatedAt": "2026-10-01T08:00:05.000Z",
  • "settledAt": "2026-10-01T08:00:05.000Z",
  • "cancelledAt": null
}

Simulate: DICT refund request (REFU)

Synthesizes an OPEN DICT special-refund request (refundReason=PIX_AUTOMATICO) for a settled schedule and processes it through the real refund flow (status=SENT). Follow with POST .../refunds/{id}/result.

Sandbox only — in production these routes return 404 (and the service refuses to boot with the simulator enabled).

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required

Request body

amount
integer

Partial refund amount in centavos; defaults to the full settled amount.

Responses

Request samples

Content type
application/json
{
  • "amount": 14990
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.refund",
  • "id": "pixrefund_4e5f60718293a4b5c6d7e8f9a1b2c3d4",
  • "recurrenceId": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "targetType": "SCHEDULE",
  • "targetId": "pixsched_7c2e4a6b8d0f1a3c5e7092b4d6f8a1c3",
  • "amount": 14990,
  • "status": "SETTLED",
  • "originalEndToEndId": "E52833288202610010800f1e2d3c4b5a",
  • "refundTransactionId": "E52833288202610021100a9b8c7d6e5f",
  • "returnedAmount": 14990,
  • "failureReason": null,
  • "createdAt": "2026-10-02T10:00:00.000Z",
  • "updatedAt": "2026-10-02T11:00:05.000Z",
  • "settledAt": "2026-10-02T11:00:05.000Z"
}

Simulate: refund settlement result

Applies the REFU settlement outcome: SETTLED completes the refund; FAILED rejects it.

Sandbox only — in production these routes return 404 (and the service refuses to boot with the simulator enabled).

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required

Request body

outcome
required
string
Enum: "SETTLED" "FAILED"
returnedAmount
integer

Responses

Request samples

Content type
application/json
{
  • "outcome": "SETTLED"
}

Response samples

Content type
application/json
{
  • "object": "pix_automatic.refund",
  • "id": "pixrefund_4e5f60718293a4b5c6d7e8f9a1b2c3d4",
  • "recurrenceId": "RR52833288202608103f9a1c2d4e5",
  • "walletId": "wlt_9f8e7d6c5b4a",
  • "targetType": "SCHEDULE",
  • "targetId": "pixsched_7c2e4a6b8d0f1a3c5e7092b4d6f8a1c3",
  • "amount": 14990,
  • "status": "SETTLED",
  • "originalEndToEndId": "E52833288202610010800f1e2d3c4b5a",
  • "refundTransactionId": "E52833288202610021100a9b8c7d6e5f",
  • "returnedAmount": 14990,
  • "failureReason": null,
  • "createdAt": "2026-10-02T10:00:00.000Z",
  • "updatedAt": "2026-10-02T11:00:05.000Z",
  • "settledAt": "2026-10-02T11:00:05.000Z"
}

Simulate: first-payment refund

Refunds the settled first payment end to end. A PENDING recurrence becomes FAILED; an AUTHORIZED one is cancelled with cancellationReason=FRAUD_SUSPECTED and its open schedules cancelled.

Sandbox only — in production these routes return 404 (and the service refuses to boot with the simulator enabled).

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "refund": {
    },
  • "recurrence": {
    }
}

Internal Transfer

Initiate transfer

Initiates an internal funds transfer between accounts under the same ownership.

Request Body schema: application/json
required

Transfer data

amount
required
integer
description
string
externalId
required
string [ 1 .. 100 ] characters
toAccountNumber
required
string

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "description": "string",
  • "externalId": "string",
  • "toAccountNumber": "string"
}

Response samples

Content type
application/json
{
  • "amount": 0,
  • "externalId": "string",
  • "requestedAt": "string",
  • "status": "PENDING",
  • "transactionId": "string"
}

Get transfer by ID

Retrieves the details of a specific internal transfer by its external ID.

path Parameters
externalId
required
string

Customer-defined identifier submitted (1-100 characters). Must be percent-encoded when it contains URL-reserved characters (e.g. '/' as %2F)

Responses

Response samples

Content type
application/json
{
  • "amount": 0,
  • "createdAt": "string",
  • "creditor": {
    },
  • "errorCode": "string",
  • "errorDescription": "string",
  • "externalId": "string",
  • "status": "PENDING",
  • "transactionId": "string",
  • "updatedAt": "string"
}

Webhook

Account-level webhook registration: URL, authentication (Basic or Bearer) and optional event filter. Pix Automático events (pixAutomatic…) are delivered through this same registration; no separate configuration is needed. See the Webhooks guide for the catalogue and the envelope.

Configure webhook

Endpoint to create/update account-level webhook configuration.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

webhook data

accountNumber
string
object (dtos.WebhookAuthDTO)
authenticationType
integer <int32>
Enum: 0 1

Authentication type: 0 = Basic authentication 1 = Bearer authentication

events
Array of strings

Possible events: pixChargePaid pixChargeRejected pixChargeExpired pixWithdrawSuccess pixWithdrawFailed pixRefundSuccess pixRefundFailed

type
integer <int32>
Enum: 0 1 2

Webhook type: 0 Pix In webhook 1 Pix Out webhook 2 Pix Refund webhook

url
required
string
webhookPassword
string
webhookUserName
string

Responses

Request samples

Content type
application/json
{
  • "accountNumber": "00012345",
  • "authentication": {
    },
  • "authenticationType": 1,
  • "events": [
    ],
  • "type": 0,
  • "url": "https://operator.example.com/webhooks/pix",
  • "webhookPassword": "webhook-password",
  • "webhookUserName": "webhook-user"
}

Response samples

Content type
application/json
{
  • "active": true,
  • "authentication": {
    },
  • "createdAt": "2026-04-07T11:30:00Z",
  • "id": "wh_7f2b8a9e",
  • "updatedAt": "2026-04-07T11:35:00Z",
  • "validated": true,
  • "webhookEvents": [
    ],
  • "webhookUrl": "https://operator.example.com/webhooks/pix"
}

List webhooks

Endpoint to list account webhooks

Authorizations:
ApiKeyAuth
query Parameters
start_date
string
Example: start_date="2026-01-01T00:00:00Z"

Start date (RFC3339). Defaults to 30 days ago.

end_date
string
Example: end_date="2026-04-14T23:59:59Z"

End date (RFC3339). Defaults to now.

Responses

Response samples

Content type
application/json
{
  • "parameters": {
    },
  • "webhooks": [
    ]
}

Delete webhook

Endpoint to delete an account webhook by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Webhook ID

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "detail": "string",
  • "message": "string",
  • "status": 0,
  • "title": "string",
  • "type": "string"
}

Balance

Get closing day balance

Retrieve the closing balance for an account on a specific reference date. All timestamps are returned in BRT (UTC-3)

Authorizations:
None
query Parameters
dateRef
required
string
Example: dateRef="2026-03-20"

Reference date (YYYY-MM-DD format)

Responses

Response samples

Content type
application/json
{
  • "accountNumber": "123456",
  • "availableBalance": 1000000,
  • "currency": "BRL",
  • "dateRef": "2026-03-20T23:59:59-03:00",
  • "lastUpdated": "2026-03-20T21:00:00-03:00",
  • "pendingBalance": 500000,
  • "totalBalance": 1500000
}

Get realtime account balance

Retrieve the real-time balance for an account directly from the ledger. All timestamps are returned in BRT (UTC-3)

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "accountNumber": "123456",
  • "availableBalance": 1450000,
  • "currency": "BRL",
  • "lastUpdated": "2026-03-21T11:30:00-03:00",
  • "pendingBalance": 50000,
  • "totalBalance": 1500000
}

Mock

Simulate QR Code payment (non-production environments only)

Creates a mock PIX-IN payment for an existing charge in non-production environments.

Required: chargeId, receiverCnpj. Optional: amount, payer (with taxId, name, bankAccounts). Missing payer fields are recovered from the charge when available.

Request Body schema: application/json
required

Simulated payment data

amount
number

Amount in cents. Optional. When omitted, the amount stored in the charge is used.

chargeId
required
string

Charge identifier. Required.

object

Optional payer data. Missing fields are recovered from the charge when available.

receiverCnpj
required
string

Receiver CNPJ. Required.

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "chargeId": "string",
  • "payer": {
    },
  • "receiverCnpj": "string"
}

Response samples

Content type
application/json
{ }

Statement

Extrato Detalhado (spec produto)

Retorna lancamentos liquidados de uma conta com filtros avancados.

Authorizations:
None
query Parameters
initDate
string

Data inicio (RFC3339 ou YYYY-MM-DD). Date-only vira 00:00 BRT do dia.

endDate
string

Data fim (RFC3339 ou YYYY-MM-DD). Date-only vira 23:59:59.999... BRT do dia.

endToEndId
string

Filtro por E2E_ID

productTransactionId
string

Filtro por UUID da transacao

counterPartyCpf
string

Filtro por CPF/CNPJ da contraparte

transactionType
string

credit | debit

method
string

pix | tarifa | judicialMovement

page
integer

Numero da pagina (default 0)

pageSize
integer

Itens por pagina (default 20, max 100)

Responses

Response samples

Content type
application/json
{
  • "page": 0,
  • "pageSize": 0,
  • "totalItems": 0,
  • "totalPages": 0,
  • "transactions": [
    ]
}

Get consolidated account statement

Retrieve a paginated daily consolidated summary filtered by date range

Authorizations:
None
query Parameters
startDate
required
string

Start date (DateOnly format, e.g. 2024-01-01)

endDate
required
string

End date (DateOnly format, e.g. 2024-01-31)

page
integer >= 1

Page number (default: 1)

limit
integer [ 1 .. 100 ]

Items per page (default: 10, max: 100)

Responses

Response samples

Content type
application/json
{
  • "accountNumber": "string",
  • "currency": "string",
  • "page": 0,
  • "pageSize": 0,
  • "summaries": [
    ],
  • "totalRecords": 0
}