Respawn PayDocs

Request Withdrawal

Requests a withdrawal from the company's available balance. If the request includes a PIX key (pixKey), it is used first.

POST/api/Withdraw/request

Headers

HeaderValueStatus
Content-Typeapplication/jsonRequired
Acceptapplication/jsonRecommended
X-Client-Id<client_id>Required
X-API-Key<api_key>Required
Idempotency-Key<unique withdrawal key, e.g. wd_<unique>>Required
X-Operation-Token<token with scope cashout:create>Optional

The header X-Operation-Token is optional, but recommended. When sent, it must be valid (generated at POST /api/v1/operation-auth/token with scope cashout:create), otherwise the API returns 401. See the section Authentication for more details.

The header Idempotency-Key is required (without it the API returns 400). Repeating the same key does not create another withdrawal: the API returns the order already created. Also use the key as your withdrawal reference, since it comes back in the field idempotencyKey and can be used in Withdrawal Lookup.

Note

If pixKey is omitted, the system automatically uses the PIX key registered on the company's bank account (BankAccount).

Request Body

Body
{
  "amount": 2500,
  "currency": "BRL",
  "pixKey": "50651470862",
  "pixKeyType": "CPF",
  "description": "Test withdrawal",
  "method": "pix",
  "paymentFlow": "INSTANT",
  "metadata": { "origem": "n8n", "pedidoId": 123 }
}

Parameters

amount
Requirednumber

Amount in cents (2500 = R$ 25.00). Minimum 1 and maximum 100,000,000 (R$ 1,000,000.00). The balance must cover the amount plus your withdrawal fee (the fee is set per company and shown in your dashboard)

currency
string

Currency (optional, BRL)

pixKey
string

Destination PIX key (optional, max. 140 characters)

pixKeyType
string

Key type: CPF, CNPJ, EMAIL, PHONE, EVP

creditorDocument
string

Beneficiary document (optional, max. 20). If omitted, uses the company CPF/CNPJ

holderName
string

Beneficiary name (optional, max. 255)

description
string

Withdrawal description (optional, max. 140 characters)

method
string

Withdrawal method (optional, max. 30). pix (default), or bank_transfer when enabled for your account. ted and crypto are reserved

paymentFlow
string

Provider flow (optional): INSTANT (default) or APPROVAL_REQUIRED. It is not the withdrawal method

metadata
object

Extra data for reference. Comes back in the withdrawal webhook as JSON text, not as an object

method and paymentFlow

method says how the money is sent (PIX, bank transfer) and paymentFlow says how the provider processes it. Older integrations that send the method in paymentFlow (for example "paymentFlow": "pix") keep working: the value is read as the method and the flow becomes INSTANT. New integrations should send method.

Response

Important Rule

The response only indicates whether the request was created or failed to be created. There is no pending, awaiting or processing in the creation response. Those statuses belong to tracking via webhook, provider or PIX settlement.

Success

HTTP 201Created
Response 201
{
  "success": true,
  "status": "success",
  "message": "Pedido de saque criado com sucesso.",
  "id": 12345,
  "idempotencyKey": "wd_test_pix_custom",
  "value": 25.00,
  "pixKey": "50651470862",
  "pixKeyType": "CPF",
  "creditorDocument": "00000000000191",
  "description": "Withdrawal R$25",
  "currency": "BRL",
  "createdAt": "2026-06-14T16:50:00.123456+00:00"
}

Success Fields

success
boolean

Always true when the request was created.

status
string

Always success when the request was created.

message
string

Creation confirmation message.

id
number

Internal ID of the withdrawal request.

idempotencyKey
string

Idempotency key sent in the Idempotency-Key header.

value
number

Net withdrawal amount in reais.

pixKey
string

PIX key used as destination.

pixKeyType
string

PIX key type: CPF, CNPJ, EMAIL, PHONE or EVP.

creditorDocument
string

Beneficiary document.

description
string

Description sent in the request.

currency
string

Withdrawal currency. Currently BRL.

createdAt
string

Request creation date/time.

Failure

When the API cannot create the withdrawal request, it returns an HTTP error. In those cases, the request must not be considered created.

HTTPResultExample cause
400 Bad RequestFailed to createMissing body, amount out of range, missing Idempotency-Key, insufficient balance, no PIX key available, invalid PIX key type.
401 UnauthorizedFailed to createInvalid operation token.
403 ForbiddenFailed to createInvalid credentials, company not allowed or IP outside the whitelist.
409 ConflictFailed to createIdempotency conflict (rare). Repeating the same Idempotency-Key normally returns the withdrawal that was already created, even if the body changed.
500 Internal Server ErrorFailed to createInternal error while requesting withdrawal. The body carries a correlationId; send it to support.

Error Examples

Missing or empty body (standard ASP.NET validation format)

400
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "": ["A non-empty request body is required."], "request": ["The request field is required."] },
  "traceId": "00-4999c7a557553e991bb2b35dc5552d21-e304a726625766fb-00"
}

Amount out of range (1 to 100,000,000 cents)

400
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "Amount": ["Amount deve ser entre 1 e 100.000.000 centavos (R$1.000.000,00)."] },
  "traceId": "00-6462ea6255fa6cc54684bbac2ce00e14-938b693910e4aeec-00"
}

Missing Idempotency-Key

400
{
  "message": "Header Idempotency-Key é obrigatório."
}

Insufficient balance

400
{
  "message": "Saldo insuficiente. Disponível: 999.30. Necessário: 1000000.02 (valor 999999.99 + taxa 0.03)."
}

No PIX key in the request and none registered on the company account

400
{
  "message": "Chave PIX não encontrada. Cadastre sua conta bancária ou envie a PixKey no request."
}

Invalid pixKeyType

400
{
  "message": "PixKeyType inválido: 'FOO'. Use: CPF, CNPJ, EMAIL, PHONE, EVP."
}

Insufficient balance

400
{
  "message": "Saldo insuficiente. Disponível: 999.30. Necessário: 1000000.02 (valor 999999.99 + taxa 0.03)."
}

No PIX key in the request and none registered on the company account

400
{
  "message": "Chave PIX não encontrada. Cadastre sua conta bancária ou envie a PixKey no request."
}

Invalid pixKeyType

400
{
  "message": "PixKeyType inválido: 'FOO'. Use: CPF, CNPJ, EMAIL, PHONE, EVP."
}

Invalid operation token

401
{
  "title": "Token de operação inválido.",
  "detail": "Token inválido ou expirado.",
  "header": "X-Operation-Token"
}

Unauthorized IP

403
{
  "title": "IP não autorizado.",
  "detail": "O IP 177.123.45.67 não está na whitelist desta empresa."
}

Internal error

500
{
  "message": "Erro ao solicitar saque.",
  "correlationId": "..."
}

How to Integrate

Use only the HTTP status and the status field of the creation response.

Integration rule
HTTP 201 + status "success" = withdrawal request created
HTTP 400/401/403/409/500 = withdrawal request not created

Do not wait for a second HTTP response to the same request. If the withdrawal changes state later, that update belongs to the webhook or lookup flow.

cURL Example

cURL
# 1. First, generate the operation token (optional step)
TOKEN=$(curl -s -X POST https://api.respawnpay.com/api/v1/operation-auth/token \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -d '{"scopes": ["cashout:create"]}' | jq -r '.token')
# 2. Request the withdrawal with the token
curl -X POST 'https://api.respawnpay.com/api/Withdraw/request' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Client-Id: <CLIENT_ID>' \
  -H 'X-API-Key: <API_KEY>' \
  -H "X-Operation-Token: $TOKEN" \
  -H "Idempotency-Key: wd_$(date +%s)_$RANDOM" \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "pixKey": "50651470862",
    "pixKeyType": "CPF",
    "description": "Withdrawal R$10",
    "metadata": { "origem": "n8n", "pedidoId": 123 }
  }'