Saques (Cashout)

Endpoints para solicitar cashouts (saques) via Pix e consultar seu status.

Método	Endpoint	Descrição
POST	/api/withdrawals	Solicita um cashout Pix
GET	/api/withdrawals	Consulta cashouts (filtros: magic_id, status, external_ref, end_to_end, limit, resend)

Criar saque

POST /api/withdrawals

Headers obrigatórios: Content-Type, x-api-key, x-token, idempotency-key. Header opcional: x-timezone.

Corpo da requisição

Campo	Tipo	Descrição
amount	number	Valor do saque (em BRL)
description	string	Descrição do saque (opcional)
requester.name	string	Nome do recebedor
requester.key	string	Chave Pix de destino
requester.key_type	string	Tipo da chave: cpf, cnpj, email, phone ou evp
transfer_method	string	Método de transferência — Pix
external_ref	string	Sua referência externa (opcional)

O formato da key deve corresponder ao key_type — veja Formatos de Chave Pix.

Exemplos por tipo de chave

CPF

POST /api/withdrawals — key_type: cpf

curl --request POST \
  --url https://api.simpixpagamentos.com/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 3.00,
    "description": "Withdrawing",
    "requester": {
      "name": "John Doe",
      "key": "95876150096",
      "key_type": "cpf"
    },
    "transfer_method": "Pix",
    "external_ref": "Zc1ULDLzSYjMpolha11g3"
  }'

CNPJ

POST /api/withdrawals — key_type: cnpj

curl --request POST \
  --url https://api.simpixpagamentos.com/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 1500.00,
    "description": "Supplier payment",
    "requester": {
      "name": "John Doe",
      "key": "33400689000109",
      "key_type": "cnpj"
    },
    "transfer_method": "Pix",
    "external_ref": "supplier_payment_001"
  }'

E-mail

POST /api/withdrawals — key_type: email

curl --request POST \
  --url https://api.simpixpagamentos.com/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 250.00,
    "description": "Refund",
    "requester": {
      "name": "John Doe",
      "key": "finance@company.com",
      "key_type": "email"
    },
    "transfer_method": "Pix"
  }'

Telefone

POST /api/withdrawals — key_type: phone

curl --request POST \
  --url https://api.simpixpagamentos.com/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 100.00,
    "requester": {
      "name": "John Doe",
      "key": "+5511999999999",
      "key_type": "phone"
    },
    "transfer_method": "Pix"
  }'

EVP (aleatória)

POST /api/withdrawals — key_type: evp

curl --request POST \
  --url https://api.simpixpagamentos.com/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 500.00,
    "requester": {
      "name": "John Doe",
      "key": "17ce9060-b29d-4ab5-89cd-20550ce6e7ac",
      "key_type": "evp"
    },
    "transfer_method": "Pix"
  }'

Resposta

O saque nasce com status CREATED e informa a fee cobrada:

201 — Withdrawal created

{
  "code": 201,
  "content": {
    "magic_id": "wth_03UdoKvLNLHg",
    "fee": 0.15,
    "amount": 3.00,
    "currency": "BRL",
    "status": "CREATED",
    "transfer_method": "Pix",
    "external_ref": "Zc1ULDLzSYjMpolha11g3",
    "created_at": "2025-02-19T17:15:25.688Z",
    "updated_at": "2025-02-19T17:15:26.703Z"
  },
  "message": "Withdrawal created",
  "timestamp": "2025-02-19T17:15:26.703Z"
}

Nota

Consulte todos os status possíveis em Status de Saque.

Consultar saques

GET /api/withdrawals

Parâmetros de query disponíveis:

Parâmetro	Descrição
magic_id	Identificador do saque na SimPix
status	Filtra por status (ex.: CREATED)
external_ref	Filtra pela sua referência externa
end_to_end	Filtra pelo identificador end-to-end do Pix
limit	Quantidade máxima de resultados
resend	true para reenviar o webhook do saque

Listar saques

GET /api/withdrawals — Listar

curl --request GET \
  --url 'https://api.simpixpagamentos.com/api/withdrawals?limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Consultar por magic_id

GET /api/withdrawals — Por magic_id

curl --request GET \
  --url 'https://api.simpixpagamentos.com/api/withdrawals?magic_id=9Wlp_2kGy4t9' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Consultar com múltiplos filtros

GET /api/withdrawals — Múltiplos filtros

curl --request GET \
  --url 'https://api.simpixpagamentos.com/api/withdrawals?magic_id=9Wlp_2kGy4t9&status=CREATED&external_ref=Zc1ULDLzSYjMpolha11g3&end_to_end=E607894312025071873189DAHJSKH12&limit=20' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Reenviar webhook (resend=true)

GET /api/withdrawals — Com reenvio de webhook

curl --request GET \
  --url 'https://api.simpixpagamentos.com/api/withdrawals?magic_id=9Wlp_2kGy4t9&resend=true' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'