Invoice push

      Invoice push


        Article Summary

        Status changes of the invoices offered with Credit Management 3.0. will be communicated to the Merchant by means of an invoice push. Below, you’ll find a list of the different codes that can be used in the push, with an explanation of the status and event push messages. But first, here’s an example of a push message:

           "InvoiceStatusCode": 10,
           "PreviousStepIndex": 0,
           "PreviousStepDateTime": "0001-01-01T00:00:00+01:00",
           "Event": "ChangedStatus",
           "EventCategory": "FinancialChange",
           "EventDateTime": "2017-09-18T16:42:10.3607772+02:00",
           "EventParameters": [
             {
               "Key": "StatusCode",
               "Value": "10"
             }
           ]
        

        Invoice status codes

        CodeMeaningDescription Invoice Status Code
        10ActiveThe invoice follows its scheme, if applicable.
        20PausedThe invoice currently does proceed on its scheme.
        21PausedByDisputeLike Paused, but specifically caused by a manually registered dispute.
        22PausedByPaymentPlanLike Paused, but specifically caused by a payment plan. This status can only be removed through termination of the payment plan.
        23PausedDueToValidationThe invoice is paused because one or more scheme actions could not be performed due to a validation error.
        70PendingTransferToCollectionAgencyThe invoice is marked for transfer to the collection agency, in accordance with its scheme.
        71TransferredToCollectionAgencyThe invoice is at the collection agency, and awaiting their response.
        72AcceptedByCollectionAgencyThe collection agency has accepted the invoice and will work on it.
        73ProcessedByCollecionAgencyThe invoice is paid at the collection agency and the collection agency has finished its work on the invoice.
        74ProcessedByCollectionAgencyIncompleteThe collection agency has finished its work on the invoice but did not manage to (fully) collect the invoice.
        75PendingRecallThe recall request has yet to be confirmed by the collection agency.
        76RecalledCollection agency has confirmed the recall.
        77RecallFailedCollection agency has confirmed the recall attempt to be unsuccessful.
        79RefusedByCollectionAgencyThe collection agency has not accepted the invoice.
        80WrittenOffThe invoice was manually written off by the merchant.
        81ErrorAtCollectionAgencyThere was an error in transferring the invoice to the collection agency.
        82CaseClosedAtCollectionAgencyThe invoice was not paid at the collection agency and the collection agency has closed the case and no further action will be taken on their part.
        90RejectedThe invoice was rejected, most likely because its request was invalid. It has never been active.
        91CancelledThe invoice has been active, but is no longer. For example, this can happen to the partial invoices created by a payment plan (see CreatePaymentPlan) if they cease to apply.
        99EmergencyThis invoice was manually disabled because of an emergency. Tech support is examining it.
        0NotSetA technical error took place. This status should never occur.

        Invoice events

        EventDescription of event
        1ChangedTransactionStatusOne of the invoice’s transactions changed status in a relevant way. Generally only a change to ‘successful’ is relevant, although there are exceptions, e.g. a Sepa Direct Debit moving to or away from ‘pending’ influences PendingSlowPaymentAmount
        2ChangedStatusThe invoice changed status, e.g. to ‘active’ or ‘paused’. See below for options
        3CreatedCreditNoteCredit note was created on the invoice. Note that a push may be sent for the credit note itself, but the CreatedCreditNote event on the original invoice is the most relevant
        4SentReminderMessageA reminder was sent for the invoice, in accordance with its scheme
        5SentBackupReminderMessageA reminder was sent for the invoice using a backup method, in accordance with its scheme. E.g. the scheme may be set to send a letter if the e-mail cannot be delivered
        6SkippedReminderBecauseNoMethodsRemainA reminder action in the invoice’s scheme has failed to reach the debtor. This happens when all of the given communication methods bounce (e.g. incorrect e-mail address) or have been marked as unreachable by the merchant (e.g. through the Debtor screen in the Payment Plaza)
        7IncreasedAdminFeeThe administration fee on the invoice has been increased, in accordance with the invoice’s scheme
        8TransferredToCollectionAgencyThe invoice has entered the collection agency process, in accordance with its scheme. Note that the ChangedStatus event provides more detailed updates as the invoice status changes throughout this process (transfer, acceptance, refusal, completion)
        9CreatedRecollectA recollect was created for the invoice, in accordance with its scheme. This happens when Sepa Direct Debit recollection is active on the scheme, when the previous attempt fails and there is enough time for another attempt
        10SentPaymentInvitationMessageA payment invitation was sent for the invoice, in accordance with its scheme
        11SentBackupPaymentInvitationMessageA payment invitation was sent for the invoice using a backup method, in accordance with its scheme. E.g. the scheme may be set to send a letter if the e-mail cannot be delivered
        12CmSchemeValidationErrorOne or more scheme actions could not be performed due to a validation error
        13InvoicePausedDueToValidationErrorsThe invoice is paused because one or more scheme actions could not be performed due to a validation error. This will only occur if (1) the payment invitation could not be performed, (2) not a single reminder message within a CM step could be performed or (3) the invoice could not be transferred to the collection agency.
        14CollectionAgencyWebhookAn event has taken place at the collection agency.
        Cat.Event CategoryDescription Category
        1FinancialChangeany change that relates to the invoice’s amounts, including the initial invoice creation, transaction status changes, and credit notes
        2ValidationErrorA validation error occurred
        3Otheranything else, e.g. a reminder being sent

        Event parameters

        Each invoice event has one or more event specific parameters. Here are a few examples:

        Event: ChangedStatus

           "Event": "ChangedStatus",
           "EventCategory": "FinancialChange",
           "EventDateTime": "2017-09-18T16:42:10.3607772+02:00",
           "EventParameters": [
             {
               "Key": "StatusCode",
               "Value": "10"
             }
        

        Event: ChangedTransactionStatus

            "Event": "ChangedTransactionStatus",
            "EventCategory": "FinancialChange",
            "EventDateTime": "2023-12-05T09:33:33.4908194",
            "EventParameters": [
              {
                "Key": "TransactionKey",
                "Value": "694804CE1D6F408EA4BCCE860A354057"
              },
              {
                "Key": "TransactionStatusCode",
                "Value": "190"
              }
            ]
        

        Event: CollectionAgencyWebhook (collection agency sent email)

            "Event": "CollectionAgencyWebhook",
            "EventCategory": "Other",
            "EventDateTime": "2023-11-20T22:55:00.3463353",
            "EventParameters": [
              {
                "Key": "status",
                "Value": "sub.status.send_email"
              },
              {
                "Key": "reference",
                "Value": "JanVanPietersen123"
              },
              {
                "Key": "paymentLink",
                "Value": "https://coeo.fyi/C/R0Az"
              },      
              {
                "Key": "mainStatus",
                "Value": "main.status.extrajudicial"
              }
            ]
        

        Event: CollectionAgencyWebhook (payment at collection agency)

            "Event": "CollectionAgencyWebhook",
            "EventCategory": "Other",
            "EventDateTime": "2023-11-20T22:55:00.3463353",
            "EventParameters": [
              {
                "Key": "amount_paid",
                "Value": "40.15"
              },
              {
                "Key": "payment_date",
                "Value": "2023-06-30+06%3a46%3a27"
              },
              {
                "Key": "paymentId",
                "Value": "16544564"
              },
              {
                "Key": "paymentLink",
                "Value": "https://coeo.fyi/C/R0Az"
              },      
              {
                "Key": "reference",
                "Value": "JohnSmith1"
              },            
              {
                "Key": "mainStatus",
                "Value": "main.status.closures"
              }
            ]
        

        Event: CollectionAgencyWebhook (payment fulfilled at collection agency)

            "Event": "CollectionAgencyWebhook",
            "EventCategory": "Other",
            "EventDateTime": "2023-11-20T22:55:00.3463353",
            "EventParameters": [
              {
                "Key": "status",
                "Value": "sub.status.full_payment"
              },
              {
                "Key": "statusReasonClose",
                "Value": "reason.close.full_payment_received"
              },
              {
                "Key": "paymentLink",
                "Value": "https://coeo.fyi/C/R0Az"
              },         
              {
                "Key": "reference",
                "Value": "JohnSmith1"
              },            
              {
                "Key": "mainStatus",
                "Value": "main.status.closures"
              }
            ]
        

        Event: CollectionAgencyWebhook (file withdrawn at collection agency)

            "Event": "CollectionAgencyWebhook",
            "EventCategory": "Other",
            "EventDateTime": "2023-11-20T22:55:00.3463353",
            "EventParameters": [
              {
                "Key": "status",
                "Value": "sub.status.do_not_generate_invoice"
              },      
              {
                "Key": "statusReasonClose",
                "Value": "reason.close.withdrawn_by_client"
              },
              {
                "Key": "paymentLink",
                "Value": "https://coeo.fyi/C/R0Az"
              },         
              {
                "Key": "reference",
                "Value": "JohnSmith1"
              },            
              {
                "Key": "mainStatus",
                "Value": "main.status.closures"
              }
            ]
        

        Event: CollectionAgencyWebhook (invoice merged to other file)

            "Event": "CollectionAgencyWebhook",
            "EventCategory": "Other",
            "EventDateTime": "2023-11-20T22:55:00.3463353",
            "EventParameters": [
              {
                "Key": "status",
                "Value": "sub.status.merged"
              },      
              {
                "Key": "statusReasonClose",
                "Value": "reason.close.merged"
              },
              {
                "Key": "paymentLink",
                "Value": "https://coeo.fyi/C/R0Az"
              },         
              {
                "Key": "reference",
                "Value": "JohnSmith1"
              },            
              {
                "Key": "mainStatus",
                "Value": "main.status.closures"
              },
              {
                "Key": "merged_to",
                "Value": "95967944"
              }
            ]
        

        Event: CollectionAgencyWebhook (payment arrangement)

            "Event": "CollectionAgencyWebhook",
            "EventCategory": "Other",
            "EventDateTime": "2023-11-20T22:55:00.3463353",
            "EventParameters": [
              {
                "Key": "status",
                "Value": "sub.status.payment"
              },
              {
                "Key": "paymentLink",
                "Value": "https://coeo.fyi/C/R0Az"
              },         
              {
                "Key": "reference",
                "Value": "JohnSmith1"
              },            
              {
                "Key": "mainStatus",
                "Value": "main.status.closures"
              }
            ]
        

        Event: CustomEvent

            "Event":"CustomEvent",
            "EventCategory":"Other",
            "EventDateTime":"2021-04-15T01:15:34.2773546",
            "EventParameters": [
             {
              "Key":" CustomEventMessage",
              "Value": "This is a test"
             }
            ]
        

        CustomEvent

        The Merchant can also use Buckaroo Credit Management to send push messages for their own use. Think of actions or memories that are used by their own systems to take actions. When creating the event, the value in the push message can also be entered as a code or description. For the usage, think of notifications that you can design yourself such as:

        • Controlling the mail or other messaging service of the Merchant, based on a text such as:
          "Send first reminder [invoicenumber]"
          This is used when Buckaroo only has to give the trigger and the CRM system of the Merchant sends the mails or other messages itself.

        • Scheduling a phone call including the data of the invoice. The text can then be:
          "Call customer [debtorcode] about invoice [InvoiceNumber] the outstanding amount is [InvoiceAmountOpen]"
          This is used for actions that Buckaroo does not perform itself, but that are part of the treatment plan for the Merchant.

        • Giving a warning for the management of outstanding invoice amounts. The example text could look like:
          "W03: [invoicenumber] enters the last reminder phase"
          This is about being able to automatically estimate and warn for the outstanding money at a certain point in time in the treatment plan.

        Example of a CustomEvent in a push message is shown below in italics as an invoice push:

        {
        
          "Invoice": {
        
            "InvoiceKey": "2EC4B83B55E74xxxxxx9C6627A208",
        
            "InvoiceNumber": "CreditManagement3_0001_1618441848",
        
            "WebsiteKey": "vcKCxxxxCDw",
        
            "DebtorCode": "TestDebtor001",
        
            "DebtorGuid": "7668521FA3xxxxxx0A444A5B194FB",
        
            "SchemeKey": "nhxxx3j",
        
            "IsTest": true,
        
            "Type": "RegularInvoice",
        
            "Culture": "nl-NL",
        
            "InvoiceDate": "2021-04-01T00:00:00",
        
            "DueDate": "2021-04-15T00:00:00",
        
            "InvoiceStatusCode": 10,
        
            "PreviousStepIndex": 0,
        
            "PreviousStepDateTime": "2021-04-15T01:14:01",
        
            "InvoicePayLink": https://testcheckout.buckaroo.nl/html/?brq_paydirect_inv=2EC4B83Bxxxxxxx292281F9C6627A208,
        
            "Event": "CustomEvent",
        
            "EventCategory": "Other",
        
            "EventDateTime": "2021-04-15T01:15:34.2773546",
        
            "EventParameters": [
        
              {
        
                "Key": "CustomEventMessage",
        
                "Value": "This is a test"
        
              }
        
            ],
        
            "Currency": "EUR",
        
            "AmountDebit": 0.0500,
        
            "AmountCredit": 0.0000,
        
            "AmountAdminCosts": 0.0000,
        
            "AmountCreditNotes": 0.0,
        
            "AmountPaid": 0.0,
        
            "AmountAdminCostsPaid": 0.0,
        
            "AmountPendingSlow": 0.0,
        
            "OpenAmount": 0.0500,
        
            "OpenAmountAdminCosts": 0.0000,
        
            "OpenAmountInclAdminCosts": 0.0500,
        
            "IsPaid": false,
        
            "CustomParameters": [
        
            ],
        
            "AdditionalParameters": [
        
            ]
        
          }
        
        }
        

        Stop Subscription

        The invoices can be generated by the Buckaroo Subscription module. In that case, from Credit Management, the Subscription can be stopped in one of the steps in the Credit Management scheme. The invoices that have been created up to that point remain and are still under control of Credit Management. The Subscription is stopped, so that no more new invoices are created. The push message that is then sent looks like this:

        {
        
          "Invoice": {
        
            "InvoiceKey": "9C9D0305DE4A47178DE903FA91C1xxxx",
        
            "InvoiceNumber": "testinvoice12xcx",
        
            "WebsiteKey": "xxxx",
        
            "DebtorCode": "johnsmith123",
        
            "SchemeKey": "xxxx",
        
            "IsTest": true,
        
            "Type": "RegularInvoice",
        
            "Culture": "nl-NL",
        
            "InvoiceDate": "2017-09-18T00:00:00+02:00",
        
            "DueDate": "2017-12-12T00:00:00+01:00",
        
            "InvoiceStatusCode": 10,
        
            "PreviousStepIndex": 3,
        
            "PreviousStepDateTime": "0001-01-01T00:00:00+01:00",
        
            "Event": "StoppedSubscription",
        
            "EventCategory": "Other",
        
            "EventDateTime": "2017-09-18T16:42:10.3607772+02:00",
        
            "EventParameters": [
        
              {
        
                "Key": "StatusCode",
        
                "Value": "10"
        
              }
        
            ],
        
            "Currency": "EUR",
        
            "AmountDebit": 10.0,
        
            "AmountCredit": 0.0,
        
            "AmountAdminCosts": 0.0,
        
            "AmountCreditNotes": 0.0,
        
            "AmountPaid": 0.0,
        
            "AmountAdminCostsPaid": 0.0,
        
            "AmountPendingSlow": 0.0,
        
            "OpenAmount": 10.0,
        
            "OpenAmountAdminCosts": 0.0,
        
            "OpenAmountInclAdminCosts": 10.0,
        
            "IsPaid": false,
        
            "SubscriptionGuid": "BDDC3050DB1B41E2983B0B5ABD98xxxx",
        
          }
        
        }
        

        Was this article helpful?