Payloads do gateway Asaas

TLDR: exemplos reais dos payloads que trocamos com o Asaas — webhook de cobrança, resposta de cartão de crédito e criação de subconta — além do formato dos nossos webhooks de saída.

Visão geral

Este documento reúne exemplos de payload coletados em uso real, para consulta rápida ao mexer nos flows de pagamento. Os campos podem mudar sem aviso do lado do gateway — a fonte da verdade é a documentação do Asaas.

Documentação oficial: webhook para cobranças.

O fluxo que consome estes payloads está em payment_flow.md.

Contratos

Webhook de cobrança recebido do Asaas

json { "event": "PAYMENT_RECEIVED", "payment": { "object": "payment", "id": "pay_080225913252", "dateCreated": "2017-03-10", "customer": "cus_G7Dvo4iphUNk", "subscription": "sub_VXJBYgP2u0eO", "installment": "ins_000000001031", "paymentLink": "123517639363", "dueDate": "2017-03-15", "value": 100.0, "netValue": 94.51, "billingType": "CREDIT_CARD", "status": "RECEIVED", "description": "Pedido 056984", "externalReference": "056984", "confirmedDate": "2017-03-15", "originalValue": null, "interestValue": null, "originalDueDate": "2017-06-10", "paymentDate": null, "clientPaymentDate": null, "invoiceUrl": "https://www.asaas.com/i/080225913252", "bankSlipUrl": null, "invoiceNumber": "00005101", "deleted": false, "creditCard": { "creditCardNumber": "8829", "creditCardBrand": "MASTERCARD", "creditCardToken": "a75a1d98-c52d-4a6b-a413-71e00b193c99" } } }

subscription só aparece quando o pagamento pertence a uma assinatura; installment só quando pertence a um parcelamento; paymentLink é o identificador do link de pagamento.

Resposta de sucesso de cartão de crédito

json { "success": "Credit card transaction succeeded", "payment": { "object": "payment", "id": "pay_i1dzql93npqx0ihq", "dateCreated": "2024-11-13", "customer": "cus_000006345005", "installment": "f940ca45-2dfe-4c6a-bbde-2204d80af717", "paymentLink": null, "value": 800.0, "netValue": 775.59, "originalValue": null, "interestValue": null, "description": "Parcela 1 de 1. Tatiana Barbosa da Silva", "billingType": "CREDIT_CARD", "confirmedDate": "2024-11-13", "creditCard": { "creditCardNumber": "1111", "creditCardBrand": "VISA", "creditCardToken": "c5f3c916-c7d5-42a4-b49e-1f8005c8a448" }, "pixTransaction": null, "status": "CONFIRMED", "dueDate": "2024-11-15", "originalDueDate": "2024-11-15", "paymentDate": null, "clientPaymentDate": "2024-11-13", "installmentNumber": 1, "invoiceUrl": "https://sandbox.asaas.com/i/i1dzql93npqx0ihq", "invoiceNumber": "06982874", "externalReference": "payment_d0dd2c9d081561f891fa591731468289", "deleted": false, "anticipated": false, "anticipable": true, "creditDate": "2024-12-16", "estimatedCreditDate": "2024-12-16", "transactionReceiptUrl": "https://sandbox.asaas.com/comprovantes/0524818382539475", "nossoNumero": null, "bankSlipUrl": null, "lastInvoiceViewedDate": null, "lastBankSlipViewedDate": null, "discount": { "value": 0.0, "limitDate": null, "dueDateLimitDays": 0, "type": "FIXED" }, "fine": { "value": 0.0, "type": "FIXED" }, "interest": { "value": 0.0, "type": "PERCENTAGE" }, "postalService": false, "custody": null, "refunds": null } }

Subconta Asaas

json { "object": "account", "id": "e5559e94-fe21-420f-a912-4f75628b2c46", "name": "Subconta criada via API", "email": "conta@example.com", "loginEmail": "conta@example.com", "phone": null, "mobilePhone": null, "address": "Av. Rolf Wiest", "addressNumber": "277", "complement": "Sala 502", "province": "Bom Retiro", "postalCode": "89223005", "cpfCnpj": "24879136000181", "birthDate": "1994-05-16", "personType": "JURIDICA", "companyType": "MEI", "city": 13660, "state": "SC", "country": "Brasil", "site": "https://www.seudominioaqui.com", "walletId": "1388ba14-a18c-437d-bc74-027252348ad0", "apiKey": "<redigido>", "accountNumber": { "agency": "0001", "account": "134595", "accountDigit": "8" }, "incomeValue": 25000, "incomeRange": "UP_TO_50K" }

O apiKey da resposta é uma credencial. Nunca versione o valor real.

Formato dos nossos webhooks de saída

Os eventos possíveis estão definidos em INTEGRATION_EVENTS. No campo data, podem vir payment, transfer ou customer — ou qualquer um dos definidos em IntegrationWebhook::kind. Sempre enviamos a informação do customer em eventos de compra, para facilitar a integração dos sistemas.

json { "pid": "webhook_05b708f961d739ea7eba7e4db318f621&368604920", "version": "1.0.0", "event": "TRANSFER_CREATED", "created_at": "2024-06-12 16:45:03", "data": { "payment": { "status": "PAID" }, "customer": { "name": "Abc", "email": "email@at.com" } } }

O contrato completo para integradores está em payment_webhooks.md, com o exemplo canônico em assets/example_payment_webhook_payload.json.

Payload do webhook para os LMS

O formato enviado ao Apolo e ao CBTRG:

json { "payment": { "id": "payment_92839288432", "status": "paid", "billing_type": "CREDIT_CARD", "checkout_id": 1, "installment_count": 5, "customer": { "id": 123, "email": "cliente@example.com", "doc_number": "05278901462" } } }

Referências