List Withdrawals

Use this endpoint to list withdrawals with filters.

Available Environments

Production

https://api.gateway.com.br/core

Endpoint

Method: GET
Endpoint: /withdrawal
Authentication: Bearer token

Query Params

ℹ️ Dates in ISO

The startDate and endDate fields must be sent as an ISO date string with time.

Example:

2026-03-06T12:00:00.000Z

ℹ️ Snapshot pagination

The snapshot is not a pointer to the "next page": it is a fixed identifier of the pagination session, used together with page (which is still sent and incremented normally) to keep the results consistent even if new records are created while you navigate.

Take the snapshot value from the first response (sent without a snapshot on the first request) and resend that same value, unchanged, on the requests for the following pages, along with the same filters and the same perPage used originally. If any of those values changes while an old snapshot is resent, the API returns an error.

Name	Type	Required	Description	Validations
`snapshot`	string	No	Identifier of the pagination session (received in the `snapshot` field of the first response); resend it unchanged along with `page` on the following pages	Must match the same filters and the same `perPage` of the original request
`startDate`	string	No	Start date of the filter	Must be an ISO date string with time
`endDate`	string	No	End date of the filter	Must be an ISO date string with time
`status`	string[] (enum) - `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELED`, `REFUNDED`, `REJECTED`, `PENDING_COMPLIANCE`	No	List of statuses to filter by	Must be a non-empty array with no duplicates
`id`	string (UUID v4)	No	Withdrawal identifier	Must be a valid UUID v4
`pixKey`	string	No	PIX key of the withdrawal	Must be a valid PIX key (CPF, CNPJ, EMAIL, PHONE or EVP)
`endToEnd`	string	No	End-to-end identifier of the withdrawal	Must be between 8 and 255 characters
`endToEndRefund`	string	No	End-to-end identifier of the refund	Must be between 8 and 255 characters
`externalCode`	string	No	Your reference code	Must be between 8 and 255 characters
`minAmount`	number	No	Minimum withdrawal amount (cents)	Must be an integer in cents; minimum `10` (R$0.10) and maximum `10000000` (R$100,000.00)
`maxAmount`	number	No	Maximum withdrawal amount (cents)	Must be an integer in cents; minimum `10` (R$0.10) and maximum `10000000` (R$100,000.00)

Request Example

cURL
JavaScript

curl --request GET \
--url https://api.gateway.com.br/core/withdrawal?status=PENDING&status=PROCESSING&startDate=2026-03-06T00:00:00.000Z&endDate=2026-03-06T23:59:59.999Z \
--header 'Authorization: Bearer your-jwt-token'

const params = new URLSearchParams({
  startDate: '2026-03-06T00:00:00.000Z',
  endDate: '2026-03-06T23:59:59.999Z'
});
params.append('status', 'PENDING');
params.append('status', 'PROCESSING');

const response = await fetch(`https://api.gateway.com.br/core/withdrawal?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-jwt-token'
  }
});
const data = await response.json();

Success Response

Field	Type	Required	Description
`totalPages`	number	Yes	Total pages
`currentPage`	number	Yes	Current page
`perPage`	number	Yes	Items per page
`snapshot`	string	No	Identifier of the pagination session; resend it unchanged on the following pages
`data`	array	Yes	List of withdrawals

Fields of the item in `data`

Field	Type	Required	Description
`id`	string (UUID)	Yes	Unique identifier of the withdrawal
`acquirerCode`	string	No	Acquirer code
`acquirer`	string	Yes	Acquirer of the withdrawal
`amount`	number	Yes	Withdrawal amount (integer, in cents)
`method`	string (enum) - `PIX`	Yes	Withdrawal method
`webhookUrl`	string	No	Configured webhook URL
`externalCode`	string	No	Your reference code
`paymentReceipt`	object	No	Payment receipt (see Sub-Object `PaymentReceiptUrl`)
`refundReceipt`	object	No	Refund receipt (see Sub-Object `PaymentReceiptUrl`)
`createdAt`	string (ISO)	Yes	Creation date
`status`	string (enum) - `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELED`, `REFUNDED`, `REJECTED`, `PENDING_COMPLIANCE`	Yes	PENDING: Withdrawal created, awaiting processing PROCESSING: Withdrawal being processed PROCESSED: Withdrawal processed successfully FAILED: Processing error CANCELED: Withdrawal canceled REFUNDED: Withdrawal refunded REJECTED: Withdrawal rejected by the gateway PENDING_COMPLIANCE: Withdrawal awaiting compliance review
`statusHistory`	array	Yes	Status history (see Sub-Objects `StatusHistory`)
`updatedAt`	string (ISO)	Yes	Last update date
`amountWithdrawn`	number	No	Amount actually withdrawn
`processedDate`	string (ISO)	No	Processing date
`errorMessage`	string	No	Error message
`endToEnd`	string	No	End-to-end identifier of the withdrawal
`endToEndRefund`	string	No	End-to-end identifier of the refund
`refundDate`	string (ISO)	No	Refund date
`refundAmount`	number	No	Refund amount (integer, in cents)
`payer`	object	No	Payer data (see Sub-Objects `AccountHolder`)
`receiver`	object	No	Receiver data (see Sub-Objects `AccountHolder`)
`pixKey`	object	No	PIX key data (see Sub-Objects `PixKeyVo`)
`trackingKey`	string	No	SPEI clave de rastreo. It always comes back `null` on PIX withdrawals
`feeAmount`	number	No	Fee amount

Sub-Objects

StatusHistory (item)

Field	Type	Required	Description
`status`	string (enum) - `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELED`, `REFUNDED`, `REJECTED`, `PENDING_COMPLIANCE`	Yes	Withdrawal status
`date`	string (ISO)	Yes	Date of the status
`durationInMilliseconds`	number	Yes	Duration of the status in milliseconds

AccountHolder

Field	Type	Required	Description
`type`	string (enum) - `PF`, `PJ`	Yes	Holder type
`name`	string	Yes	Holder name
`document`	string	Yes	Holder document
`bankAccount`	object	Yes	Bank data (see Sub-Objects `BankAccount`)
`pix`	object	Yes	PIX key of the holder (see Sub-Objects `PixKeyVo`)

BankAccount

Field	Type	Required	Description
`type`	string	Yes	Account type
`digit`	string	Yes	Account check digit
`ispb`	string	Yes	ISPB of the bank

PixKeyVo

Field	Type	Required	Description
`key`	string	Yes	PIX key
`type`	string (enum) - `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`	Yes	PIX key type

PaymentReceiptUrl

Field	Type	Required	Description
`url`	string	Yes	URL of the receipt
`expirationDate`	string (ISO)	Yes	Expiration date of the receipt

Response Example

Masked data

Sensitive values may be masked with ***.

{
  "totalPages": 1,
  "currentPage": 1,
  "perPage": 15,
  "snapshot": "b3BhcXVlLXNuYXBzaG90LXRva2Vu",
  "data": [
    {
      "id": "553e8400-e29b-41d4-a716-436251480000",
      "acquirerCode": "ACQ-123",
      "acquirer": "ACQUIRER_EXEMPLO",
      "amount": 10000,
      "method": "PIX",
      "webhookUrl": "https://sua-api.com/webhooks/withdrawal",
      "externalCode": "SAQUE-123",
      "paymentReceipt": {
        "url": "https://files.exemplo.com.br/receipts/withdrawal-553e8400-e29b-41d4-a716-436251480000.pdf",
        "expirationDate": "2026-04-01T00:00:00.000Z"
      },
      "refundReceipt": {
        "url": "https://files.exemplo.com.br/receipts/withdrawal-refund-553e8400-e29b-41d4-a716-436251480000.pdf",
        "expirationDate": "2026-04-01T00:00:00.000Z"
      },
      "createdAt": "2026-03-06T12:49:04.681Z",
      "status": "REFUNDED",
      "statusHistory": [
        {
          "status": "PENDING",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 1000
        },
        {
          "status": "PROCESSING",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 10000
        },
        {
          "status": "PROCESSED",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 10000
        },
        {
          "status": "REFUNDED",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 5000
        }
      ],
      "updatedAt": "2026-03-06T12:49:04.681Z",
      "amountWithdrawn": 10000,
      "processedDate":  "2026-03-06T12:49:04.681Z",
      "errorMessage": "Falha ao registrar o estorno no PSP",
      "endToEnd": "0123456789",
      "endToEndRefund": "0123456789-REFUND",
      "refundDate": "2026-03-06T14:49:04.681Z",
      "refundAmount": 10000,
      "payer": {
        "type": "PF",
        "name": "Fulano de Tal",
        "document": "***456789**",
        "bankAccount": {
          "type": "CHECKING",
          "digit": "7",
          "ispb": "12345678"
        },
        "pix": {
          "key": "12345678910",
          "type": "CPF"
        }
      },
      "receiver": {
        "type": "PJ",
        "name": "Empresa Exemplo LTDA",
        "document": "12345678000199",
        "bankAccount": {
          "type": "CHECKING",
          "digit": "0",
          "ispb": "12345678"
        },
        "pix": {
          "key": "contato@exemplo.com",
          "type": "EMAIL"
        }
      },
      "pixKey": {
        "key": "12345678910",
        "type": "CPF"
      },
      "feeAmount": 150
    }
  ]
}

Possible Errors

Code	Description	Solution
401	Invalid credentials	Check your credentials
403	No permission/authorization	Contact support
422	Invalid or missing data	Check the format of the data
422	Validations	Contact support
500	Internal error	Contact support

Available Environments​

Endpoint​

Query Params​

Request Example​

Success Response​

Fields of the item in data​

Sub-Objects​

StatusHistory (item)​

AccountHolder​

BankAccount​

PixKeyVo​

PaymentReceiptUrl​

Response Example​

Possible Errors​