Manual do Dev
InstitucionalBlogService DeskStatus Page

Faturas de cartão

Confira os eventos relativos a faturas de cartões.

beta

Suggest Edits

Os eventos de faturas de cartão disparam mensagens que comunicam ao destinatário informações sobre as faturas de pagamento de cartão.
Como esses eventos chegam ao recebedor via webhook, é preciso realizar previamente a sua configuração.

Contexto e nome do evento

Nos eventos de faturas de cartão, o campo context sempre informará “Invoice”, enquanto o campo name poderá variar de acordo com a transação, conforme a tabela a seguir:

Nome do evento (name)Descrição
INVOICE_PAYMENT_PROCESSEDFatura do cartão processada.
INVOICE_PAYMENT_OPTION_CREATEDPagamento proporcional ou total realizado para a fatura.
INVOICE_CLOSEDFatura do cartão fechada.

EntityId

O campo entityId é o identificador da entidade emissora do evento e seu valor depende do contexto de sua emissão.
No contexto de faturas de cartão, o entityId pode ser:

Nome do evento (name)Valor do entityId
INVOICE_PAYMENT_PROCESSEDpaymentId
INVOICE_PAYMENT_OPTION_CREATEDstatementId
INVOICE_CLOSEDstatementId

Exemplos de eventos

{
  "name": "INVOICE_PAYMENT_PROCESSED",
  "entityId": "315",
  "idempotencyKey": "763cd6ed-f0c2-437e-896a-6b57lf3c690e",
  "companyKey": "COMPANY_KEY",
  "timestamp": "2022-04-19T11:23:02.2257857Z",
  "correlationId": "5873d178-797f-4176-902d-db6d6253d5p8",
  "version": 1,
  "metadata": {
    "StatementId": 12345
  },
  "context": "Invoice",
  "data": {
    "paymentDate": "2022-04-18T00:00:00+00:00",
    "amount": {
      "value": 61.52,
      "currency": "BRL"
    },
    "paymentType": "Cash",
    "paymentOptionType": "Billet",
    "status": "Paid",
    "ourNumber": "89407844536",
    "statementId": 48645,
    "statementPaymentStatus": "Paid"
  }
}

{
  "name": "INVOICE_PAYMENT_OPTION_CREATED",
  "entityId": "12345",
  "idempotencyKey": "1f40aeec-310c-4c71-b393-461bcbbd6348",
  "companyKey": "COMPANY_KEY",
  "timestamp": "2022-04-25T11:54:10.923222Z",
  "correlationId": "3811ed19-ac34-4e77-b300-64479666a503",
  "version": 1,
  "metadata": {
    "closed": "2022-05-02T00:00:00"
  },
  "context": "Invoice",
  "data": {
    "statementId": 12345,
    "paymentType": "Cash",
    "holder": {
      "document": {
        "value": "12345678901",
        "type": "CPF"
      }
    },
    "payment": {
      "authenticationCode": "581828c6-d1da-42ea-ba55-77d59083239b",
      "digitableLine": "332900011514736489619164458789901239720000111115",
      "dueDate": "2022-05-01T00:00:00",
      "paymentOptionType": "Billet",
      "status": "Pending",
      "amount": {
        "value": 1111.15,
        "currency": "BRL"
      },
      "ourNumber": "12345678900"
    }
  }
}

{
    "entityId": "10",
    "idempotencyKey": "86447d19-687f-4fa8-80cf-a5ii406457b9",
    "companyKey": "ACESSO",
    "context": "Invoice",
    "name": "INVOICE_CLOSED",
    "timestamp": "2021-12-06T11:10:25.3853601Z",
    "correlationId": "7a1bfc3f-50e6-458c-aa9b-d33a22ddb84d",
    "metadata": {
        "closed": "2021-12-06T11:10:20.282+00:00"
    },
    "data": {
        "statementId": 10,
        "month": 10,
        "year": 2021,
        "cycle": 4,
        "CycleCloseDate": "2021-10-06T00:00:00",
        "dueDate": "2021-10-06T00:00:00",
        "balance": {
            "value": 676.16,
            "currency": "BRL"
        },
        "holder": {
            "document": {
                "value": "12346789000",
                "type": "CPF"
            }
        },
        "paymentOptions": [
            {
                "paymentType": "Partial",
                "amount": {
                    "value": 6234.93,
                    "currency": "BRL"
                }
            },
            {
                "paymentType": "Cash",
                "amount": {
                    "value": 13234.93,
                    "currency": "BRL"
                }
            },
            {
                "paymentType": "InstallmentWithEntry",
                "amount": {
                    "value": 222.71,
                    "currency": "BRL"
                },
                "refinancingCondition": {
                    "installmentTotal": 2,
                    "refinancingAmount": {
                        "value": 1262.02,
                        "currency": "BRL"
                    },
                    "interestAmount": {
                        "value": 295.15819193064215,
                        "currency": "BRL"
                    },
                    "totalAmount": {
                        "value": 1567.7,
                        "currency": "BRL"
                    },
                    "iofAmount": {
                        "value": 10.52,
                        "currency": "BRL"
                    },
                    "installments": [
                        {
                            "installmentNumber": 1,
                            "dueDate": "2022-09-01T00:00:00",
                            "amount": {
                                "value": 783.85,
                                "currency": "BRL"
                            },
                            "interestAmount": {
                                "value": 208.06,
                                "currency": "BRL"
                            },
                            "iofAmount": {
                                "value": 10.52,
                                "currency": "BRL"
                            }
                        },
                        {
                            "installmentNumber": 2,
                            "dueDate": "2022-10-03T00:00:00",
                            "amount": {
                                "value": 783.85,
                                "currency": "BRL"
                            },
                            "interestAmount": {
                                "value": 87.1,
                                "currency": "BRL"
                            },
                            "iofAmount": {
                                "value": 0,
                                "currency": "BRL"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

🚧

Importante

Para conhecer a estrutura básica dos eventos com os campos que chegarão à sua API, consulte nossa documentação específica de Eventos.

Objeto data nos eventos de faturas de cartão

O objeto data traz detalhes específicos do contexto em que o evento ocorre. No caso de eventos de faturas de cartão, esse objeto irá variar de acordo com o evento, conforme explicitado a seguir:

Evento INVOICE_PAYMENT_PROCEED

  • paymentDate: data de pagamento da fatura;
  • amount: objeto que representa o valor pago:
    • value: valor de pagamento;
    • currency: código da moeda com base na ISO-4217.
  • paymentType: opção de pagamento , que pode ser: “Cash” (à vista), “Partial” (parcial), “InstallmentWithEntry” (parcelado com entrada), “InstallmentWithoutEntry” (parcelado sem entrada);
  • paymentOptionType: forma de pagamento. No caso de faturas de cartão, este campo virá preenchido com o valor “Billet” (Boleto).
  • status: situação do pagamento, a qual pode ser: “Pending” (pendente), “Paid” (pago) ou “Expired” (expirado);
  • statementId: identificador único da fatura;
  • statementPaymentStatus: situação do pagamento da fatura, a qual pode ser: “Pending” (pendente), “Paid” (pago), “PartialPaid” (parcialmente pago) e "LatePaid" (atrasado).

Evento INVOICE_PAYMENT_OPTION_CREATED

  • statementId: identificador único da fatura;
  • paymentType: opção de pagamento , que pode ser: “Cash” (à vista), “Partial” (parcial), “InstallmentWithEntry” (parcelado com entrada), “InstallmentWithoutEntry” (parcelado sem entrada);
  • holder: objeto que contém informações do titular da fatura:
    • document: objeto que contém o número e o tipo de documento (CPF ou CNPJ) do titular do cartão;
      • value: número do documento do titular do cartão;
      • type: tipo de documento do titular do cartão.
  • payment: objeto que contém informações sobre o pagamento:
    • authenticationcode: identificador da forma de pagamento;
    • digitableLine: linha digitável do boleto de pagamento;
    • dueDate: data de vencimento do pagamento;
    • paymentOptionType: forma de pagamento. No caso de faturas de cartão, este campo virá preenchido com o valor “Billet” (Boleto).
    • status: situação da forma de pagamento, que pode ser: “Pending” (pendente), “Paid” (pago) ou “Expired” (expirado);
  • amount: objeto que representa o valor pago:
    • value: valor de pagamento;
    • currency: código da moeda com base na ISO-4217.

Evento INVOICE_CLOSED

  • statementId: identificador único da fatura;
  • holder: objeto que contém informações do titular da fatura:
    • document: objeto que contém o número e o tipo de documento (CPF ou CNPJ) do titular do cartão;
      • value: número do documento do titular do cartão;
      • type: tipo de documento do titular do cartão.
  • balance: objeto que contém informações referentes ao valor total da fatura:
    • value: valor total da fatura;
    • currency: código da moeda com base na ISO-4217.
  • dueDate: data de vencimento da fatura;
  • cycleCloseDate: data de fechamento da fatura;
  • cycle: indicador do ciclo da fatura;
  • year: representa o ano de vencimento da fatura;
  • month: representa o mês de vencimento da fatura;
  • amount: objeto que representa o valor pago:
    • value: valor de pagamento;
    • currency: código da moeda com base na ISO-4217.
  • paymentOptions: objeto que contém informações referente ao tipo de pagamento:
    • paymentType: opção de pagamento, que pode ser: “Cash” (à vista), “Partial” (parcial), “InstallmentWithEntry” (parcelado com entrada), “InstallmentWithoutEntry” (parcelado sem entrada).

Updated 11 months ago