Pular para o conteúdo principal
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

accountNumber
required
string
amount
required
integer
description
string <= 140 characters
endToEndId
required
string
externalId
required
string [ 1 .. 36 ] characters

Responses

Request samples

Content type
application/json
{
  • "accountNumber": "string",
  • "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 (UUIDv4)

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"
}

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
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

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

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

Setup withdrawal mock (non-production environments only)

Centralizes the mock setup required to test PIX withdrawal flows in non-production environments.

The endpoint performs the following steps in sequence:

  • Creates a PIX key entry in simulator-dict
  • Triggers the key consultation mock in simulator-dict
  • Triggers the withdrawal identifier mock in simulator-spi
Request Body schema: application/json
required

Withdrawal mock setup data

required
object (handlers.SetupWithdrawalMockAccount)
autoSettle
boolean
key
required
string
keyType
required
string
Enum: "CPF" "CNPJ" "EMAIL" "PHONE" "EVP"
required
object (handlers.SetupWithdrawalMockOwner)
reason
string
requestId
string
result
string

Responses

Request samples

Content type
application/json
{
  • "account": {
    },
  • "autoSettle": true,
  • "key": "string",
  • "keyType": "CPF",
  • "owner": {
    },
  • "reason": "string",
  • "requestId": "string",
  • "result": "string"
}

Response samples

Content type
application/json
{
  • "key": "string",
  • "requestId": "string",
  • "steps": [
    ],
  • "taxIdNumber": "string"
}

Simulate QR Code payment (non-production environments only)

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

Required: chargeId. Optional: amount, receiverCnpj, 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
string

Receiver CNPJ. Optional. When omitted, the API attempts to recover it from the receiver account.

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
}