Pagamentos
Criar um pagamento Pix
Cria uma cobrança Pix e devolve o código copia e cola para o cliente pagar.
POST
/v1/payments Requer o escopo PAYMENT:CREATE
Envie o valor em centavos (ou os produtos do seu catálogo) e os dados de quem paga. A API calcula a taxa e devolve o pagamento com status pending e o código Pix em pix.copy_paste.
Requisição
Cabeçalhos: Authorization, Content-Type: application/json e Idempotency-Key (obrigatório). Veja Idempotência.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount_cents | integer | um dos dois | Valor em centavos, número inteiro. Mínimo 100 (R$ 1,00). O máximo é o limite da sua conta. Envie amount_cents ou items, nunca os dois. |
items | array | um dos dois | Produtos do seu catálogo, até 50. Cada item tem product_id (o id do produto no painel) e qty (de 1 a 1000). Nós calculamos o total pelo preço cadastrado. |
payer | object | sim | Quem vai pagar. |
payer.name | string | sim | Nome de quem paga, até 120 caracteres. |
payer.document | string | sim | CPF (11 dígitos) ou CNPJ (14 dígitos) de quem paga. Com ou sem pontuação. |
description | string | não | Texto que o cliente vê no Pix, até 140 caracteres. Sem ele, usamos o nome da sua empresa. |
external_id | string | não | O id do pedido no seu sistema, até 120 caracteres. Não pode repetir. |
expires_in | integer | não | Validade em segundos, de 60 (1 minuto) a 604800 (7 dias). Padrão: 1800 (30 minutos). |
metadata | object | não | Até 20 pares chave e valor, em texto. Voltam iguais na resposta e nos webhooks. |
Resposta
A API responde 201 com o pagamento.
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Id do pagamento. Guarde junto com o pedido. |
status | string | Status do pagamento. Começa em pending. Veja os status. |
amount_cents | integer | Valor cobrado, em centavos. |
fee_cents | integer | Taxa da plataforma, em centavos. |
net_cents | integer | Valor que entra no seu saldo: amount_cents menos fee_cents. |
pix | object | null | Dados do Pix. É null enquanto o código está sendo gerado e depois que o pagamento não pode mais ser pago. |
pix.copy_paste | string | Código Pix copia e cola. Mostre ao cliente. |
pix.qr_svg | string | QR Code do mesmo código, como imagem SVG pronta para mostrar ao cliente. Vem quando pix vem. |
expires_at | string (ISO 8601) | null | Até quando o Pix pode ser pago. |
paid_at | string (ISO 8601) | null | Quando o pagamento foi confirmado. null até lá. |
paid_late | boolean | true quando o pagamento chegou depois de expires_at. O valor entra no saldo do mesmo jeito. |
external_id | string | null | O id do pedido que você enviou. |
description | string | null | A descrição do Pix. |
customer | object | null | Quem paga. |
customer.name | string | Nome de quem paga. |
customer.document | string | Documento de quem paga, mascarado. |
metadata | object | Os pares que você enviou. |
payment_url | string | Página pronta com QR Code e código copia e cola. Pode enviar ao cliente. |
created_at | string (ISO 8601) | Quando o pagamento foi criado. |
Erros
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 400 | idempotency_key_required | Faltou o cabeçalho Idempotency-Key. | Envie uma chave de 8 a 200 caracteres. |
| 409 | duplicate_external_id | Já existe um pagamento com este external_id. | Busque o pagamento existente pela lista com external_id. |
| 409 | idempotency_in_progress | A mesma chave ainda está sendo processada. | Espere um pouco e repita com a mesma chave. |
| 422 | validation_failed | Algum campo está inválido. | Veja o campo fields da resposta. |
| 422 | idempotency_key_reused | A chave já foi usada com outro corpo. | Use uma chave nova para um pedido novo. |
| 503 | payments_unavailable | Pix está temporariamente indisponível. | Tente de novo em alguns minutos, com a mesma chave. |