Cobranças

Uma cobrança é um pedido de pagamento por Pix, boleto ou cartão. A SuyPay escolhe a conta, cria a cobrança nela e acompanha a situação até o fim. Para os campos de cada método, veja Criar cobranças.

Rotas

Rota
POST /payments criar (campos)
GET /payments listar. Filtros: status, method, provider, q
GET /payments/{id} ver uma, com histórico e tentativas
POST /payments/{id}/refund devolver { amount? }
POST /payments/{id}/cancel cancelar uma cobrança que ainda não foi paga
POST /payments/{id}/sync buscar a situação atual na conta
POST /payments/{id}/simulate confirmar no teste pela conta de teste da SuyPay, pelo Asaas sandbox ou pelo Inter sandbox; exige chave de teste
GET /customers clientes

Criar uma cobrança

curl https://api.suypay.com/v1/payments \
  -H "Authorization: Bearer suy_test_..." \
  -H "Idempotency-Key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{ "method": "pix", "amount": 4990, "customer": { "name": "Maria Silva" } }'

A resposta traz a conta escolhida em provider, o que o cliente precisa para pagar em next_action e a página para acompanhar a cobrança em payment_url (veja Link de pagamento). No cartão, o token precisa ser gerado antes pelo formulário da conta.

Se omitir method, a resposta vem com status: "requires_method" e payment_url. Envie esse link ao cliente: ele escolhe entre as formas disponíveis. Para cartão escolhido no link, a Stripe abre seu Checkout seguro, onde também mostra Apple Pay e Google Pay quando elegíveis. O valor e os dados da cobrança são fixados na criação; o cliente só escolhe a forma.

Para dividir a venda com subcontas, envie splits: [{ "subaccount_id": "sub_...", "amount": 1000 }] ou com percentage no lugar de amount. A cobrança vai pela conta das subcontas, e a resposta traz splits em centavos.

Contas que exigem dados que você não mandou (e-mail, celular, CPF) são puladas, e a venda vai pela próxima. Se nenhuma servir, a cobrança volta com status: "failed", failure_reason e failure_code (veja Erros).

Devolver

Sem amount, devolve tudo. Com amount, devolve só uma parte. Veja Devoluções.

Cancelar

Cancela uma cobrança que o cliente ainda não pagou: o QR code do Pix ou o boleto param de funcionar na conta e a cobrança fica com status: "canceled". Chega o aviso payment.canceled.

curl -X POST https://api.suypay.com/v1/payments/pay_.../cancel \
  -H "Authorization: Bearer suy_test_..."