Criar pagamento (Cash-out/Payout)
Nesta seção, você aprenderá como criar pagamentos via PIX usando a API PixToPay.
Endpoints Disponíveis
- Sandbox chave PIX:
https://sandbox.pixtopay.com.br/v2/payout/pix - Produção chave PIX:
https://api.pixtopay.com.br/v2/payout/pix - Sandbox dados bancários:
https://sandbox.pixtopay.com.br/v2/payout - Produção dados bancários:
https://api.pixtopay.com.br/v2/payout
Criar pagamento via PIX (recomendado)
Crie um pagamento instantâneo via PIX usando uma chave PIX como destino.
Route
POST /v2/payout/pix
Headers
{
"Authorization": "YOUR_API_KEY",
"Content-Type": "application/json"
}Body Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
transaction_id | string | Sim | Identificador único da transação na sua plataforma (UUID v4 recomendado) |
currency | string | Sim | Moeda da transação (apenas "BRL" é suportado) |
amount | number | Sim | Valor do pagamento em reais (ex: 150.75) |
name | string | Sim | Nome completo do beneficiário |
document_type | string | Sim | Tipo de documento do beneficiário ("CPF" ou "CNPJ") |
document_number | string | Sim | Número do documento do beneficiário (apenas números) |
pix_key | string | Sim | Chave PIX do beneficiário (CPF/CNPJ, e-mail, telefone ou chave aleatória) |
phone_number | string | Não | Número de telefone do beneficiário no formato internacional (ex: "5547999999999") |
email | string | Não | Endereço de email do beneficiário |
webhook | string | Não | URL para receber notificações de status do pagamento via webhook |
Formatos de chave PIX aceitos:
- CPF/CNPJ: Apenas números (ex: "12345678900")
- E-mail: Endereço de e-mail válido (ex: "email@example.com")
- Telefone: Formato internacional com +55 (ex: "+5547999999999")
- Chave aleatória (EVP): Chave UUID gerada pelo banco (ex: "123e4567-e89b-12d3-a456-426614174000")
Exemplo de requisição:
curl --location 'https://sandbox.pixtopay.com.br/v2/payout/pix' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"transaction_id": "9233a90c-c4a8-4a3f-8da4-d77b7d0d3327",
"name": "Daniel Menegasso",
"document_type": "CPF",
"document_number": "12345678900",
"currency": "BRL",
"amount": 1500,
"pix_key": "email@example.com",
"webhook": "https://webhook.site/785a3e4e-e444-4838-9c31-1c62fe4d276e"
}'Resposta 200 - Sucesso:
{
"id": 796,
"transaction_id": "9233a90c-c4a8-4a3f-8da4-d77b7d0d3327",
"status": 0,
"currency": "BRL",
"amount": 1500,
"bank": {
"type": "email",
"bank_name": "COOPERATIVA DE CRÉDITO, POUPANÇA E INVESTIMENTO FRONTEIRAS DO PARANÁ",
"ispb": "82527557",
"account_agency": "3879",
"account_number": "7716539016157248"
}
}Campos da Resposta
| Parâmetro | Tipo | Descrição |
|---|---|---|
id | integer | ID interno do pagamento gerado pela PixToPay |
transaction_id | string | Identificador único da transação na sua plataforma |
status | integer | Status atual do pagamento (0 = criado) |
currency | string | Moeda da transação |
amount | number | Valor do pagamento |
bank | object | Informações da conta de destino identificada pela chave PIX |
bank.type | string | Tipo da chave PIX utilizada |
bank.bank_name | string | Nome do banco de destino |
bank.ispb | string | ISPB do banco de destino |
bank.account_agency | string | Agência da conta de destino |
bank.account_number | string | Número da conta de destino |
Resposta 400 - Chave PIX ausente:
{
"type": "ValidationError",
"message": "body.pix_key is a required field"
}Resposta 400 - transaction_id duplicado:
{
"type": "ValidationError",
"message": "body.transaction_id already exists"
}Criar pagamento via Dados Bancários
Crie um pagamento PIX usando dados bancários completos ao invés de uma chave PIX.
Route
POST /v2/payout
Headers
{
"Authorization": "YOUR_API_KEY",
"Content-Type": "application/json"
}Body Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
transaction_id | string | Sim | Identificador único da transação na sua plataforma |
currency | string | Sim | Moeda da transação (apenas "BRL" é suportado) |
amount | number | Sim | Valor do pagamento em reais |
name | string | Sim | Nome completo do beneficiário |
document_type | string | Sim | Tipo de documento do beneficiário ("CPF" ou "CNPJ") |
document_number | string | Sim | Número do documento do beneficiário (apenas números) |
bank | object | Sim | Objeto contendo informações bancárias |
bank.type | string | Sim | Tipo de transferência: "PIX" |
bank.bank_name | string | Não | Nome do banco (opcional, mas recomendado) |
bank.ispb | string | Sim | ISPB do banco — 8 dígitos |
bank.account_agency | string | Sim | Número da agência (4 dígitos) |
bank.account_number | string | Sim | Número da conta com dígito verificador (ex: "12345-6") |
phone_number | string | Não | Número de telefone do beneficiário |
email | string | Não | Endereço de email do beneficiário |
webhook | string | Não | URL para receber notificações de status |
Exemplo de requisição:
curl --location 'https://sandbox.pixtopay.com.br/v2/payout' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"transaction_id": "c5d81228-6d97-4b49-835a-d29eeeea7025",
"name": "Daniel Menegasso",
"document_type": "CPF",
"document_number": "12345678900",
"currency": "BRL",
"amount": 300,
"bank": {
"type": "PIX",
"bank_name": "Banco do Brasil S.A",
"ispb": "00000000",
"account_agency": "1234",
"account_number": "12345-6"
},
"phone_number": "47999999999",
"email": "email@example.com",
"webhook": "https://webhook.site/c154fa95-701c-4bc1-b6e7-a4ba0e0c01c7"
}'Resposta 200 - Sucesso:
{
"id": 686,
"transaction_id": "c5d81228-6d97-4b49-835a-d29eeeea7025",
"status": 0,
"currency": "BRL",
"amount": 300,
"bank": {
"type": "PIX",
"bank_name": "Banco do Brasil S.A",
"ispb": "00000000",
"account_agency": "1234",
"account_number": "12345-6"
}
}Resposta 400 - ISPB ausente:
{
"type": "ValidationError",
"message": "body.bank.ispb is required when type is PIX"
}Resposta 400 - Limite de agência excedido:
{
"type": "ValidationError",
"message": "body.bank.account_agency must be at most 4 characters"
}Observações Importantes
- ✅ Simples: Requer apenas a chave PIX
- ✅ Instantâneo: Processamento em segundos
- ✅ 24/7: Disponível a qualquer momento
- ✅ Validação automática: A API valida a chave PIX e retorna os dados bancários
Status do Pagamento
Após criar o pagamento, ele passa pelos seguintes status:
| Status | Descrição |
|---|---|
0 | Pagamento criado, aguardando processamento |
1 | Pagamento pago/concluído |
2 | Pagamento rejeitado |
3 | Pagamento devolvido |
Fluxo de status
O fluxo de status de um pagamento segue a sequência abaixo:
0 (Criado) → 1 (Pago)
0 (Criado) → 2 (Rejeitado)
0 (Criado) → 1 (Pago) → 3 (Devolvido)Modo Sandbox
No ambiente sandbox, você pode simular diferentes comportamentos:
Simulando status de pagamento
Adicione o header x-sandbox-behaviour à sua requisição com um dos seguintes valores:
| Valor | Descrição |
|---|---|
paid | Simula um pagamento aprovado/concluído (status 1) |
rejected | Simula um pagamento rejeitado (status 2) |
refunded | Simula um pagamento devolvido (status 3) |
Exemplo de requisição com x-sandbox-behaviour:
curl --location 'https://sandbox.pixtopay.com.br/v2/payout/pix' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-behaviour: paid' \
--data-raw '{
"transaction_id": "9233a90c-c4a8-4a3f-8da4-d77b7d0d3327",
"name": "Daniel Menegasso",
"document_type": "CPF",
"document_number": "12345678900",
"currency": "BRL",
"amount": 1500,
"pix_key": "email@example.com",
"webhook": "https://webhook.site/785a3e4e-e444-4838-9c31-1c62fe4d276e"
}'