Criar cobranças
Pix, boleto ou cartão, sempre do mesmo jeito: POST /v1/payments.
Pix
{
"method": "pix",
"amount": 4990,
"customer": { "name": "Maria Silva" }
}
Mostre para o cliente o next_action.qr_code (copia e cola). Quando a conta manda a imagem do QR Code, ela vem em next_action.qr_code_base64. Em next_action.qr_code_url fica a imagem do QR Code num endereço público, pronta para um e-mail, um chat ou um bot do Discord.
Boleto
O boleto precisa do CPF ou CNPJ e do endereço do cliente:
{
"method": "boleto",
"amount": 15900,
"customer": {
"name": "Carlos Souza",
"email": "carlos@email.com",
"document": "11144477735",
"address": { "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "zip": "01310100" }
}
}
A linha digitável vem em next_action.digitable_line, e o link do boleto em next_action.url.
Cartão
Os dados do cartão nunca passam pela SuyPay. O seu site usa o formulário de cartão da conta (Mercado Pago, Stripe e outras) e manda para a SuyPay só o token:
{
"method": "card",
"amount": 25000,
"card": { "token": "tok_...", "installments": 3 },
"customer": { "name": "Ana Lima", "document": "12345678909" }
}
Dica: o token só funciona na conta que o gerou. Por isso, crie uma regra que mande cartão sempre para a mesma conta.
Todos os campos
| Campo | ||
|---|---|---|
method |
pix, boleto ou card |
opcional: omita para o cliente escolher no link |
amount |
valor em centavos | obrigatório |
customer.name |
nome do cliente | obrigatório |
customer.document |
CPF ou CNPJ | boleto, cartão, Asaas e Efí |
customer.email |
recomendado | |
customer.address |
endereço | boleto |
customer.ip |
IP de quem está comprando | se não mandar, a SuyPay usa o IP de quem chamou a API |
description |
o que aparece para você | |
expires_in_minutes |
prazo do Pix ou, sem method, prazo para o cliente escolher no link |
|
metadata |
informações suas ({ "pedido": "1042" }) |
usado nas regras e copiado para a conta |
IP do comprador
Asaas, Appmax e Mercado Pago usam o IP de quem compra para barrar fraude no cartão. Se você cria a cobrança do seu servidor, mande o IP do cliente em customer.ip. Sem ele, a SuyPay usa o IP de quem chamou a API, que nesse caso é o do seu servidor.
"customer": { "name": "Ana Lima", "document": "12345678909", "ip": "177.12.34.56" }
Metadata
Até 50 chaves, cada uma com até 40 letras, e valores em texto de até 500 letras. A SuyPay guarda tudo na cobrança, usa nas regras e copia para a conta quando ela tem onde guardar:
| Conta | Onde aparece |
|---|---|
| Stripe | metadata do pagamento |
| Mercado Pago | metadata do pagamento |
| Efí (Pix) | informações adicionais do Pix |
| Woovi | informações adicionais da cobrança |
| Asaas, Appmax | não têm onde guardar (fica só na SuyPay) |
Sem cobrança em dobro
Mande o cabeçalho Idempotency-Key com um código único do pedido. Se a mesma chamada for repetida, por exemplo numa falha de internet, a SuyPay devolve a mesma cobrança em vez de criar outra.
-H "Idempotency-Key: pedido-1042"