Invoice push

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

Code	Meaning	Description Invoice Status Code
10	Active	The invoice follows its scheme, if applicable.
20	Paused	The invoice currently does proceed on its scheme.
21	PausedByDispute	Like Paused, but specifically caused by a manually registered dispute.
22	PausedByPaymentPlan	Like Paused, but specifically caused by a payment plan. This status can only be removed through termination of the payment plan.
23	PausedDueToValidation	The invoice is paused because one or more scheme actions could not be performed due to a validation error.
70	PendingTransferToCollectionAgency	The invoice is marked for transfer to the collection agency, in accordance with its scheme.
71	TransferredToCollectionAgency	The invoice is at the collection agency, and awaiting their response.
72	AcceptedByCollectionAgency	The collection agency has accepted the invoice and will work on it.
73	ProcessedByCollecionAgency	The invoice is paid at the collection agency and the collection agency has finished its work on the invoice.
74	ProcessedByCollectionAgencyIncomplete	The collection agency has finished its work on the invoice but did not manage to (fully) collect the invoice.
75	PendingRecall	The recall request has yet to be confirmed by the collection agency.
76	Recalled	Collection agency has confirmed the recall.
77	RecallFailed	Collection agency has confirmed the recall attempt to be unsuccessful.
79	RefusedByCollectionAgency	The collection agency has not accepted the invoice.
80	WrittenOff	The invoice was manually written off by the merchant.
81	ErrorAtCollectionAgency	There was an error in transferring the invoice to the collection agency.
82	CaseClosedAtCollectionAgency	The 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.
90	Rejected	The invoice was rejected, most likely because its request was invalid. It has never been active.
91	Cancelled	The 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.
99	Emergency	This invoice was manually disabled because of an emergency. Tech support is examining it.
0	NotSet	A technical error took place. This status should never occur.

Invoice Events

1	ChangedTransactionStatus	One 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
2	ChangedStatus	The invoice changed status, e.g. to ‘active’ or ‘paused’. See below for options
3	CreatedCreditNote	Credit 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
4	SentReminderMessage	A reminder was sent for the invoice, in accordance with its scheme
5	SentBackupReminderMessage	A 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
6	SkippedReminderBecauseNoMethodsRemain	A 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)
7	IncreasedAdminFee	The administration fee on the invoice has been increased, in accordance with the invoice’s scheme
8	TransferredToCollectionAgency	The 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)
9	CreatedRecollect	A 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
10	SentPaymentInvitationMessage	A payment invitation was sent for the invoice, in accordance with its scheme
11	SentBackupPaymentInvitationMessage	A 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
12	CmSchemeValidationError	One or more scheme actions could not be performed due to a validation error
13	InvoicePausedDueToValidationErrors	The 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.
14	CollectionAgencyWebhook	An event has taken place at the collection agency.

Cat.	Event Category	Description Category
1	FinancialChange	any change that relates to the invoice’s amounts, including the initial invoice creation, transaction status changes, and credit notes
2	ValidationError	A validation error occurred
3	Other	anything else, e.g. a reminder being sent

Event Parameters

Each invoice event has one or more event specific parameters. Here an example:

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

Merchants can use Buckaroo Credit Management to send push messages for their own use, such as:

Controlling the mail service: "Send first reminder [invoicenumber]"
Scheduling phone calls: "Call customer [debtorcode] about invoice [InvoiceNumber]"

Example of a CustomEvent:

{

  "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

Invoices generated by the Buckaroo Subscription module can be managed from Credit Management. When stopping a subscription, the push message 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",

  }

}