Como solicitar saques e transferir valores para sua conta
Saques transferem valores da sua carteira disponível para uma conta bancária ou chave PIX.
Antes de solicitar um saque, consulte quais métodos estão habilitados:
curl -X GET https://api-acquirer.pagsmile.com.br/v1/withdrawals/methods \
-H "Authorization: Basic {credentials}"{
"data": [
{ "type": "pix", "enabled": true },
{ "type": "ted", "enabled": true }
]
}Consulte a taxa antes de solicitar:
curl -X GET "https://api-acquirer.pagsmile.com.br/v1/withdrawals/fee?amount=100000" \
-H "Authorization: Basic {credentials}"{
"data": {
"fee": 350,
"fee_type": "fixed"
}
}Merchants podem solicitar saques em nome de seus submerchants passando o campo opcional submerchant_id. A carteira (wallet_id) deve pertencer ao submerchant informado.
curl -X POST https://api-acquirer.pagsmile.com.br/v1/withdrawals \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: saque-sub-001" \
-d '{
"type": "pix",
"wallet_id": "carteira-do-submerchant-uuid",
"submerchant_id": "submerchant-uuid",
"amount": 50000,
"pix_key": "12345678901",
"pix_key_type": "cpf"
}'Para filtrar saques e resumo por submerchant, passe submerchant_id como query param:
curl -X GET "https://api-acquirer.pagsmile.com.br/v1/withdrawals?submerchant_id={uuid}" \
-H "Authorization: Basic {credentials}"
curl -X GET "https://api-acquirer.pagsmile.com.br/v1/withdrawals/summary?submerchant_id={uuid}" \
-H "Authorization: Basic {credentials}"curl -X POST https://api-acquirer.pagsmile.com.br/v1/withdrawals \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: saque-2026-02-11-001" \
-d '{
"type": "pix",
"wallet_id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 100000,
"pix_key": "12345678901",
"pix_key_type": "cpf"
}'const response = await fetch('https://api-acquirer.pagsmile.com.br/v1/withdrawals', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'saque-2026-02-11-001',
},
body: JSON.stringify({
type: 'pix',
wallet_id: '550e8400-e29b-41d4-a716-446655440000',
amount: 100000,
pix_key: '12345678901',
pix_key_type: 'cpf',
}),
});Quando a chave PIX não é do tipo cpf ou cnpj (ou seja, email, phone ou random), é obrigatório enviar o documento do titular nos campos holder_document_type e holder_document_number. A API retornará erro HOLDER_DOCUMENT_REQUIRED caso esses campos não sejam enviados.
curl -X POST https://api-acquirer.pagsmile.com.br/v1/withdrawals \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: saque-2026-02-11-004" \
-d '{
"type": "pix",
"wallet_id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 100000,
"pix_key": "[email protected]",
"pix_key_type": "email",
"holder_document_type": "cpf",
"holder_document_number": "12345678901"
}'| Campo | Tipo | Descrição |
|---|---|---|
holder_document_type | cpf | cnpj | Tipo do documento do titular da chave PIX |
holder_document_number | string (11-14 dígitos) | Número do documento (apenas dígitos) |
Saques via API para chaves do tipo email, phone e random serão rejeitados com erro HOLDER_DOCUMENT_REQUIRED se esses campos não forem enviados.
curl -X POST https://api-acquirer.pagsmile.com.br/v1/withdrawals \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: saque-2026-02-11-002" \
-d '{
"type": "ted",
"wallet_id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 500000,
"bank_account": {
"bank_code": "001",
"branch_number": "1234",
"account_number": "567890",
"account_check_digit": "1",
"account_type": "checking",
"holder_name": "João Silva",
"holder_tax_id": "12345678901"
}
}'| Tipo | Descrição |
|---|---|
cpf | CPF do titular |
cnpj | CNPJ do titular |
email | |
phone | Telefone |
random | Chave aleatória |
Envie o header Idempotency-Key com um valor único por saque (ex.: um UUID). Ele garante que uma mesma solicitação não seja processada mais de uma vez: se a requisição for repetida com a mesma chave (timeout, proxy instável, reenvio), a API retorna o resultado da solicitação original sem criar um novo saque.
-H "Idempotency-Key: a1b2c3d4-0000-4444-8888-1234567890ab"Use sempre uma Idempotency-Key única por operação. O campo idempotency_key no corpo também é aceito, mas o header é o padrão recomendado.
| Status | Descrição |
|---|---|
pending | Solicitação criada, aguardando processamento |
processing | Em processamento |
completed | Concluído, valor transferido |
failed | Falha no processamento |
canceled | Cancelado |
curl -X GET https://api-acquirer.pagsmile.com.br/v1/withdrawals/summary \
-H "Authorization: Basic {credentials}"Retorna saldo disponível, saques pendentes, valor sacado hoje e totais acumulados.