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.

CampoTipoObrigatórioDescrição
amount_centsintegerum dos doisValor 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.
itemsarrayum dos doisProdutos 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.
payerobjectsimQuem vai pagar.
payer.namestringsimNome de quem paga, até 120 caracteres.
payer.documentstringsimCPF (11 dígitos) ou CNPJ (14 dígitos) de quem paga. Com ou sem pontuação.
descriptionstringnãoTexto que o cliente vê no Pix, até 140 caracteres. Sem ele, usamos o nome da sua empresa.
external_idstringnãoO id do pedido no seu sistema, até 120 caracteres. Não pode repetir.
expires_inintegernãoValidade em segundos, de 60 (1 minuto) a 604800 (7 dias). Padrão: 1800 (30 minutos).
metadataobjectnãoAté 20 pares chave e valor, em texto. Voltam iguais na resposta e nos webhooks.

Resposta

A API responde 201 com o pagamento.

CampoTipoDescrição
idstringId do pagamento. Guarde junto com o pedido.
statusstringStatus do pagamento. Começa em pending. Veja os status.
amount_centsintegerValor cobrado, em centavos.
fee_centsintegerTaxa da plataforma, em centavos.
net_centsintegerValor que entra no seu saldo: amount_cents menos fee_cents.
pixobject | nullDados do Pix. É null enquanto o código está sendo gerado e depois que o pagamento não pode mais ser pago.
pix.copy_pastestringCódigo Pix copia e cola. Mostre ao cliente.
pix.qr_svgstringQR Code do mesmo código, como imagem SVG pronta para mostrar ao cliente. Vem quando pix vem.
expires_atstring (ISO 8601) | nullAté quando o Pix pode ser pago.
paid_atstring (ISO 8601) | nullQuando o pagamento foi confirmado. null até lá.
paid_latebooleantrue quando o pagamento chegou depois de expires_at. O valor entra no saldo do mesmo jeito.
external_idstring | nullO id do pedido que você enviou.
descriptionstring | nullA descrição do Pix.
customerobject | nullQuem paga.
customer.namestringNome de quem paga.
customer.documentstringDocumento de quem paga, mascarado.
metadataobjectOs pares que você enviou.
payment_urlstringPágina pronta com QR Code e código copia e cola. Pode enviar ao cliente.
created_atstring (ISO 8601)Quando o pagamento foi criado.

Erros

HTTPCódigoQuando aconteceO que fazer
400idempotency_key_requiredFaltou o cabeçalho Idempotency-Key.Envie uma chave de 8 a 200 caracteres.
409duplicate_external_idJá existe um pagamento com este external_id.Busque o pagamento existente pela lista com external_id.
409idempotency_in_progressA mesma chave ainda está sendo processada.Espere um pouco e repita com a mesma chave.
422validation_failedAlgum campo está inválido.Veja o campo fields da resposta.
422idempotency_key_reusedA chave já foi usada com outro corpo.Use uma chave nova para um pedido novo.
503payments_unavailablePix está temporariamente indisponível.Tente de novo em alguns minutos, com a mesma chave.