Cobranças Pix

Criar cobrança

Cria uma cobrança Pix e devolve o código copia e cola para o seu cliente pagar. Quando o pagamento cai, o webhook charge.paid avisa a sua aplicação.

POST/charges

Cria uma cobrança Pix avulsa.

Headers

Campo	Tipo	Descrição
`Authorization`obrigatório	string	`Bearer <TOKEN>`
`Idempotency-Key`obrigatório	string	Única por cobrança. Repetir a mesma chave devolve a cobrança já criada. Veja Idempotência.
`Content-Type`obrigatório	string	`application/json`

Corpo da requisição

Campo	Tipo	Descrição
`amount`obrigatório	number	Valor em reais. Mínimo 1.00.
`reference`opcional	string	Identificador do seu sistema (pedido, fatura). Volta na resposta, nos webhooks e serve de filtro.
`message`opcional	string	Mensagem da cobrança, até 255 caracteres.
`customer`opcional	object	Quem vai pagar.
`customer.name`opcional	string	Nome do cliente, até 255 caracteres.
`customer.email`opcional	string	E-mail do cliente.
`customer.tax_id`opcional	string	CPF ou CNPJ do cliente, até 50 caracteres.
`metadata`opcional	object	Dados livres do seu sistema (chave e valor). Uma lista `[{"field", "value"}]` também é aceita e vira objeto.

Requisição

1curl -X POST "https://api.sancopay.com/api/v1/charges" \2  -H "Authorization: Bearer <TOKEN>" \3  -H "Idempotency-Key: pedido-123" \4  -H "Content-Type: application/json" \5  -d '{6    "amount": 150,7    "reference": "PED-123",8    "message": "Pedido #123",9    "customer": {10      "name": "Maria Souza",11      "email": "[email protected]",12      "tax_id": "12345678909"13    },14    "metadata": {15      "order_id": "123",16      "coupon": "OFF10"17    }18  }'

Resposta

Cobrança criada.

1{2  "id": 4821,3  "tracking_id": "c62abd1d-9092-4892-b163-cef2951912ad",4  "reference": "PED-123",5  "status": "pending",6  "amount": 150,7  "fee": null,8  "message": "Pedido #123",9  "customer": {10    "name": "Maria Souza",11    "email": "[email protected]",12    "tax_id": "12345678909"13  },14  "pix": {15    "copy_paste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d65204000053039865406150.005802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2"16  },17  "end_to_end_id": null,18  "metadata": {19    "order_id": "123",20    "coupon": "OFF10"21  },22  "failure_reason": null,23  "created_at": "2026-11-09T15:04:05.000000Z",24  "updated_at": "2026-11-09T15:04:05.000000Z"25}

Campos da cobrança

id: Id da cobrança na SancoPay.
tracking_id: Código de rastreio do Pix no processador.
reference: O identificador que você enviou.
amount: Valor cobrado. fee é a taxa da SancoPay sobre ele; vem null enquanto ainda não foi calculada.
pix.copy_paste: Código Pix copia e cola (o mesmo conteúdo do QR Code).
end_to_end_id: Identificador do Pix no Banco Central, preenchido quando pago.
failure_reason: Motivo da falha, só com status: "failed".

Status

pending: Criada, aguardando o pagamento.
paid: Pagamento confirmado. O valor menos a taxa entra na carteira.
failed: Não foi concluída (recusada ou cancelada). Motivo em failure_reason.
refunded: O pagamento foi devolvido ao pagador.
expired: O Pix expirou sem pagamento.