Requests

Requests


CreateInvoice

CreateInvoice is a data request that registers an invoice with Credit Management in the Buckaroo Payment Engine.

A few parameters are mandatory. Most are optional, although the given scheme’s actions can impose additional requirements. For example, if a scheme can send e-mails, the Email group is required.

Note that the debtor-related parameters are grouped. The Person group handles personal information, the Address group handles address information, and so on. Groups are always either included or omitted.

A debtor is identified by its unique Debtor_Code, determined by the merchant. A new code registers a new debtor. An existing code with no further information uses the existing debtor as is. An existing code with additional information also updates (i.e. overwrites) any group that is given. E.g. if any parameters from the Address group are given, any previous address information is overwritten by the given group.

Each group should be included or omitted as a whole. If a group (e.g. Address) is given, except for some of its optional parameters (e.g. Address_HouseNumber), the missing parameters are considered empty.

For phone numbers, each type of phone (e.g. mobile, landline, or fax) is considered separately, as if it were a group of its own. Submitting a mobile phone number does not overwrite any existing landline phone number.

Example: Debtor_Code 1234 is already known, with Person, Address, and Phone_Landline information. A new request is made, using the same debtor code, accompanied by parameters Phone_Mobile, Address_Country, Address_City, Address_ZipCode, and Address_Street. The result is as follows: The Person and Phone_Landline data remains available, unchanged. The mobile phone number is added. The complete address is replaced by the new one. Note in particular that, because no state and no house number are given, these will indeed be empty in the new address, even if they were populated for the old address. (They are allowed to be empty because addresses exist that do not have them.)

Furthermore, if any contact detail was marked unreachable, re-submitting that information removes the mark, allowing the detail to be used again. For example, if a new e-mail address is submitted or the existing e-mail address is explicitly submitted again (rather than being omitted), then the merchant is instructing the use of that e-mail address. This is assumed to be a conscious decision (e.g. because the debtor has informed the merchant that the inbox is no longer full), and as such, the unreachable mark is removed.

Base JSON request

Use the base request as instructed on this page

Request

(CreateInvoice)

There is a certain amount of information needed to create an invoice. First off, you need to provide invoice related information, like the invoice amount, invoice date, scheme key, et cetera. Secondly, you need to provide a debtor. Debtor related information can be categorised into 6 groups:

  1. Debtor group: This group has only one parameter, namely the debtor Code and contains all defining information about the debtor. This group (parameter) is always required.

  2. Person Group: Contains personal information about the debtor. Every debtor requires either a person, a company, or both.

  3. Company Group: Contains company information about the debtor. May be combined with a person.

  4. Address Group. Contains address information about the debtor.

  5. Email Group. Contains e-mail information about the debtor.

  6. Phone Group. Contains phone information about the debtor. Each phone type is treated as if it were a separate group, e.g. mobile phone data will only ever overwrite existing mobile phone data, but never existing landline phone data.

When providing a debtor related parameter, include the group type as well.

Parameters

Service specific parameters

Parameter Type Required Recommended Description
InvoiceAmount decimal yes The amount of the invoice. Note: In case of a CreateCombinedInvoice request, the InvoiceAmount may deviate from the transaction amount, e.g. if additional transactions are to be added later, such as ExternalPayments.
InvoiceAmountVat decimal The VAT amount on the invoice.
InvoiceDate yes The invoice date. (yyyy-mm-dd)
DueDate yes The due date for the invoice. The schedule starts counting from this date. Important note: if combined with SEPA Direct Debit, the collect date should always precede the due date of the invoice, since you don't want to trigger a reminder step before debiting the customer. If however, the collect date is accidentally set after the due date, then the first reminder step will be postponed till the collect date, but only if it's set within 14 days after the due date. If it's set further than that, then our system will perform another check after 14 days and so on.
SchemeKey The key of the scheme to use. Available keys are found in the Buckaroo Payment Plaza: Configuration > Credit Management.
Basic parameters

Example request

{
   "Currency": "EUR",
   "Invoice": "testinvoice123r",
   "Services": {
      "ServiceList": [
         {
            "Name": "CreditManagement3",
            "Action": "CreateInvoice",
            "Parameters": [
               {
                  "Name": "ApplyStartRecurrent",
                  "Value": "False"
               },
               {
                  "Name": "InvoiceAmount",
                  "Value": "10.00"
               },
               {
                  "Name": "InvoiceAmountVAT",
                  "Value": "1.00"
               },
               {
                  "Name": "InvoiceDate",
                  "Value": "2017-09-22"
               },
               {
                  "Name": "DueDate",
                  "Value": "2018-12-23"
               },
               {
                  "Name": "SchemeKey",
                  "Value": "xxxx"
               },
               {
                  "Name": "MaxStepIndex",
                  "Value": "2"
               },
               {
                  "Name": "AllowedServices",
                  "Value": "ideal,mastercard"
               },
               {
                  "Name": "AllowedServicesAfterDueDate",
                  "Value": "ideal,mastercard"
               },
               {
                  "Name": "Code",
                  "GroupType": "Debtor",
                  "GroupID": "",
                  "Value": "johnsmith4"
               },
               {
                  "Name": "Email",
                  "GroupType": "Email",
                  "GroupID": "",
                  "Value": "youremail@example.nl"
               },
               {
                  "Name": "Culture",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "nl-NL"
               },
               {
                  "Name": "Title",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "Msc"
               },
               {
                  "Name": "Initials",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "JS"
               },
               {
                  "Name": "FirstName",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "John"
               },
               {
                  "Name": "LastNamePrefix",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "Jones"
               },
               {
                  "Name": "LastName",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "Smith"
               },
               {
                  "Name": "Gender",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "1"
               },
               {
                  "Name": "BirthDate",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "1990-01-01"
               },
               {
                  "Name": "PlaceOfBirth",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "Utrecht"
               },
               {
                  "Name": "Culture",
                  "GroupType": "Company",
                  "GroupID": "",
                  "Value": "nl-NL"
               },
               {
                  "Name": "Name",
                  "GroupType": "Company",
                  "GroupID": "",
                  "Value": "My Company Corporation"
               },
               {
                  "Name": "VatApplicable",
                  "GroupType": "Company",
                  "GroupID": "",
                  "Value": "true"
               },
               {
                  "Name": "VatNumber",
                  "GroupType": "Company",
                  "GroupID": "",
                  "Value": "NL140619562B01"
               },
               {
                  "Name": "ChamberOfCommerce",
                  "GroupType": "Company",
                  "GroupID": "",
                  "Value": "20091741"
               },
               {
                  "Name": "Street",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "Hoofdstraat"
               },
               {
                  "Name": "HouseNumber",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "90"
               },
               {
                  "Name": "HouseNumberSuffix",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "A"
               },
               {
                  "Name": "Zipcode",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "8441ER"
               },
               {
                  "Name": "City",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "Heerenveen"
               },
               {
                  "Name": "State",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "Friesland"
               },
               {
                  "Name": "Country",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "NL"
               },
               {
                  "Name": "Mobile",
                  "GroupType": "Phone",
                  "GroupID": "",
                  "Value": "06198765432"
               }
            ]
         }
      ]
   }
}

Response

(CreateInvoice)

Parameters

Basic parameters

Example response

{
    "Key": "EAE77A1EDCCC479DA94325A4D245xxxx",
    "Status": {
        "Code": {
            "Code": 190,
            "Description": "Success"
        },
        "SubCode": {
            "Code": "S001",
            "Description": "Transaction successfully processed"
        },
        "DateTime": "2017-09-18T16:42:10"
    },
    "RequiredAction": null,
    "Services": [
        {
            "Name": "CreditManagement3",
            "Action": null,
            "Parameters": [
                {
                    "Name": "InvoiceKey",
                    "Value": "9C9D0305DE4A47178DE903FA91C1xxxx"
                },
                {
                    "Name": "DebtorGuid",
                    "Value": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
                },
                {
                    "Name": "InvoicePayLink",
                    "Value": "https://testcheckout.buckaroo.nl/html/?brq_paydirect_inv=xxxxxx"
                }
            ]
        }
    ],
    "CustomParameters": null,
    "AdditionalParameters": null,
    "RequestErrors": null,
    "ServiceCode": "CreditManagement3",
    "IsTest": true,
    "ConsumerMessage": null
}

Push

(CreateInvoice)

Parameters

Basic parameters

Example push

{
   "Invoice": {
      "InvoiceKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "InvoiceNumber": "testinvoice_1614689513",
      "WebsiteKey": "0000",
      "DebtorCode": "JohnSmith12345",
      "DebtorGuid": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "SchemeKey": "xxxxx",
      "IsTest": true,
      "Type": "RegularInvoice",
      "Culture": "nl-NL",
      "InvoiceDate": "2021-03-02T00:00:00",
      "DueDate": "2021-03-02T00:00:00",
      "InvoiceStatusCode": 23,
      "PreviousStepIndex": 0,
      "PreviousStepDateTime": "2021-03-02T15:59:21",
      "InvoicePayLink": "http://testcheckout.local/html/?brq_paydirect_inv=xxxx",
      "Event": "InvoicePausedDueToValidationErrors",
      "EventCategory": "ValidationError",
      "EventDateTime": "2021-03-02T16:02:04.321891",
      "EventParameters": [
         {
            "Key": "ValidationErrorMessage0",
            "Value": "Required data Email missing."
         },
         {
            "Key": "ValidationErrorMessage1",
            "Value": "Required data MobilePhone missing."
         }
      ],
      "Currency": "EUR",
      "AmountDebit": 1,
      "AmountCredit": 0,
      "AmountAdminCosts": 0,
      "AmountCreditNotes": 0,
      "AmountPaid": 0,
      "AmountAdminCostsPaid": 0,
      "AmountPendingSlow": 0,
      "OpenAmount": 1,
      "OpenAmountAdminCosts": 0,
      "OpenAmountInclAdminCosts": 1,
      "IsPaid": false,
      "CustomParameters": [],
      "AdditionalParameters": []
   }
}

CreateCombinedInvoice

CreateCombinedInvoice is a supplementary action on a transaction request. It functions exactly like CreateInvoice, with the notable difference that it creates the invoice side-by-side with the primary action’s transaction.

Base JSON request

Use the base request as instructed on this page

Request

(CreateCombinedInvoice)

Parameters

Basic parameters

Example request

{
   "AmountDebit": 10.00,
   "Currency": "EUR",
   "Invoice": "testinvoice1337",
   "Services": {
      "ServiceList": [
         {
            "Name": "SepaDirectDebit",
            "Action": "Pay",
            "Parameters": [
               {
                  "Name": "CollectDate",
                  "Value": "2017-10-01"
               },
               {
                  "Name": "customeraccountname",
                  "Value": "John Smith"
               },
               {
                  "Name": "CustomerIBAN",
                  "Value": "NL13TEST0123456789"
               },
               {
                  "Name": "customerbic",
                  "Value": "TESTNL2A"
               }
            ]
         },
         {
            "Name": "CreditManagement3",
            "Action": "CreateCombinedInvoice",
            "Parameters": [
               {
                  "Name": "InvoiceAmount",
                  "Value": "10.00"
               },
               {
                  "Name": "InvoiceDate",
                  "Value": "2017-09-15"
               },
               {
                  "Name": "DueDate",
                  "Value": "2017-10-12"
               },
               {
                  "Name": "SchemeKey",
                  "Value": "xxxxx"
               },
               {
                  "Name": "Code",
                  "GroupType": "Debtor",
                  "GroupID": "",
                  "Value": "JohnSmith9"
               },
               {
                  "Name": "Culture",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "nl-NL"
               },
               {
                  "Name": "LastName",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "Smith"
               },
               {
                  "Name": "Email",
                  "GroupType": "Email",
                  "GroupID": "",
                  "Value": "johnsmith@example.nl"
               }
            ]
         }
      ]
   }
}

Response

(CreateCombinedInvoice)
A response follows, notifying you of the pending status of the Sepa Direct Debit transaction and providing you a related invoice key.

Parameters

Basic parameters

Example response

{
   "Key": "D44521B7E4B84EDBBC37D9168E8Bxxxx",
   "Status": {
      "Code": {
         "Code": 791,
         "Description": "Pending processing"
      },
      "SubCode": {
         "Code": "C620",
         "Description": "Awaiting transfer to bank."
      },
      "DateTime": "2017-09-15T13:48:26"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "CreditManagement3",
         "Action": null,
         "Parameters": [
            {
               "Name": "InvoiceKey",
               "Value": "ADD2EC4CC5824F669D317F1D7C4Axxxx"
            },
            {
               "Name": "DebtorGuid",
               "Value": "xxxxxxxxxxxxxxxxxxxx"
            },
            {
               "Name": "InvoicePayLink",
               "Value": "https://testcheckout.buckaroo.nl/html/?brq_paydirect_inv=xxxxxxxxxx"
            }
         ]
      },
      {
         "Name": "SepaDirectDebit",
         "Action": null,
         "Parameters": [
            {
               "Name": "MandateReference",
               "Value": "001D44521B7E4B84EDBBC37D9168E8Bxxxx"
            },
            {
               "Name": "MandateDate",
               "Value": "2017-09-15"
            },
            {
               "Name": "CustomerIBAN",
               "Value": "NL13TEST0123456789"
            },
            {
               "Name": "CustomerBIC",
               "Value": "TESTNL2A"
            },
            {
               "Name": "CollectDate",
               "Value": "2017-10-02"
            },
            {
               "Name": "DirectDebitType",
               "Value": "OneOff"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice1337",
   "ServiceCode": "SepaDirectDebit",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 10,
   "TransactionType": "C004",
   "MutationType": 1,
   "RelatedTransactions": null,
   "ConsumerMessage": {
      "MustRead": true,
      "CultureName": null,
      "Title": "Your SEPA Direct Debit has been scheduled.",
      "PlainText": "We have processed your request. The SEPA Direct Debit is scheduled to be collected from you bank account on Monday, October 2, 2017. It will be done using the mandate reference 001D44521B7E4B84EDBBC37D9168E8B3304.",
      "HtmlText": "We have processed your request. The SEPA Direct Debit is scheduled to be collected from you bank account on Monday, October 2, 2017. It will be done using the mandate reference <b>001D44521B7E4B84EDBBC37D9168E8B3304<\/b>."
   },
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": "John Smith",
   "PayerHash": null,
   "PaymentKey": "5FCE6E3ACA2249CF9F61A8B316D0xxxx"
}

Push

(CreateCombinedInvoice)
For an explanation on the parameters: see the push response in the CreateInvoice section.

Parameters

Basic parameters

Example push

{
   "Invoice": {
      "InvoiceKey": "ADD2EC4CC5824F669D317F1D7C4Axxxx",
      "InvoiceNumber": "testinvoice1337",
      "WebsiteKey": "0000",
      "DebtorCode": "JohnSmith9",
      "DebtorGuid": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "SchemeKey": "xxxxx",
      "IsTest": true,
      "Type": "RegularInvoice",
      "Culture": "nl-NL",
      "InvoiceDate": "2017-09-15T00:00:00+02:00",
      "DueDate": "2017-10-12T00:00:00+02:00",
      "InvoiceStatusCode": 10,
      "PreviousStepIndex": 0,
      "PreviousStepDateTime": "0001-01-01T00:00:00+01:00",
      "InvoicePayLink": "https://testcheckout.buckaroo.nl/html/?brq_paydirect_inv=xxxxxxxxxxxx",
      "Event": "ChangedStatus",
      "EventCategory": "FinancialChange",
      "EventDateTime": "2017-09-15T13:48:24.9451584+02:00",
      "EventParameters": [
         {
            "Key": "StatusCode",
            "Value": "10"
         }
      ],
      "Currency": "EUR",
      "AmountDebit": 10,
      "AmountCredit": 0,
      "AmountAdminCosts": 0,
      "AmountCreditNotes": 0,
      "AmountPaid": 0,
      "AmountAdminCostsPaid": 0,
      "AmountPendingSlow": 0,
      "OpenAmount": 10,
      "OpenAmountAdminCosts": 0,
      "OpenAmountInclAdminCosts": 10,
      "IsPaid": false,
      "CustomParameters": [],
      "AdditionalParameters": []
   }
}

CreateCreditNote

CreateCreditNote is a data request that registers a credit note on an invoice in Buckaroo Credit Management. The credit note amount reduces the amount due on the original invoice.

The credit note may cover the full original invoice amount, or only part of it. Multiple credit notes are possible, so long as their sum does not exceed the original invoice amount.

Note how credit notes can cause an invoice to be considered paid, by reducing the amount due to 0.

A credit note does not result in a refund. Imagine creating a credit note on an invoice that was already fully paid. The invoice is now overpaid: the amount due is negative, since we have reduced the amount due to less than what we have received. In this scenario, the merchant may want to perform a refund. This requires a separate request.

Base JSON request

Use the base request as instructed on this page

Request

(CreateCreditNote)
#### Parameters

Basic parameters

Example request

{
  "Currency": "EUR",
  "Invoice": "testinvoice1337creditnote",
  "Services": {
    "ServiceList": [
      {
        "Name": "CreditManagement3",
        "Action": "CreateCreditNote",
        "Parameters": [
          {
            "Name": "InvoiceAmount",
            "Value": "10.00"
          },
          {
            "Name": "InvoiceDate",
            "Value": "2017-09-18"
          },
          {
            "Name": "OriginalInvoiceNumber",
            "Value": "testinvoice1337"
          }
        ]
      }
    ]
  }
}

Response

(CreateCreditNote)

Parameters

Basic parameters

Example response:

{
   "Key": "81DDC6678B834413A6BC01DC4EADxxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2017-09-18T13:40:35"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "CreditManagement3",
         "Action": null,
         "Parameters": [
            {
               "Name": "InvoiceKey",
               "Value": "A0E4462214DB4E0F886F399CC283xxxx"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "CreditManagement3",
   "IsTest": true,
   "ConsumerMessage": null
}

Push

(CreateCreditNote)

Parameters

Basic parameters

Example push

{
  "Invoice": {
    "InvoiceKey": "ADD2EC4CC5824F669D317F1D7C4Axxxx",
    "InvoiceNumber": "testinvoice1337",
    "WebsiteKey": "0000",
    "DebtorCode": "JohnSmith9",
    "SchemeKey": "yf7yf9",
    "IsTest": true,
    "Type": "RegularInvoice",
    "Culture": "nl-NL",
    "InvoiceDate": "2017-09-15T00:00:00+02:00",
    "DueDate": "2017-10-12T00:00:00+02:00",
    "InvoiceStatusCode": 10,
    "PreviousStepIndex": 0,
    "PreviousStepDateTime": "0001-01-01T00:00:00+01:00",
    "Event": "CreatedCreditNote",
    "EventCategory": "FinancialChange",
    "EventDateTime": "2017-09-18T13:40:35.0589813+02:00",
    "EventParameters": [
      {
        "Key": "PlazaUsername",
        "Value": ""
      }
    ],
    "Currency": "EUR",
    "AmountDebit": 10.0,
    "AmountCredit": 0.0,
    "AmountAdminCosts": 0.0,
    "AmountCreditNotes": 10.0,
    "AmountPaid": 10.0,
    "AmountAdminCostsPaid": 0.0,
    "AmountPendingSlow": 0.0,
    "OpenAmount": -10.0,
    "OpenAmountAdminCosts": 0.0,
    "OpenAmountInclAdminCosts": -10.0,
    "IsPaid": true,
    "CustomParameters": [],
    "AdditionalParameters": []
  }
}

AddOrUpdateDebtor

AddOrUpdateDebtor is a data request that adds or updates debtor information in the Buckaroo Payment Engine. This is exactly like the debtor-related behavior or CreateInvoice, without creating an invoice. This allows the updating of debtor information at any time, and even in bulk, e.g. by using a batch file.

Additionally, AddOrUpdateDebtor allows marking or unmarking contact information as unreachable. Contact information can become marked unreachable by this request, from the Buckaroo Payment Plaza, or by communication failures such as mail bounces.

See CreateInvoice for further information.

Base JSON request

Use the base request as instructed on this page

Request

(AddOrUpdateDebtor)

AddOrUpdateDebtor uses all the parameters defined for CreateInvoice starting at the Debtor Group, down to the end. When adding or updating a Debtor, it is required to at least provide a debtor code, identify it as either a Person or a Company by providing the person's last name of the company name and it's culture. It is not possible to change an existing debtor code.

In addition, the following parameters can be added to their respective groups. Remember to include or omit each group as a whole, thus if a group (e.g. Address) is given, except for some of its optional parameters (e.g. Address_HouseNumber), the missing parameters are considered empty.

Parameters

Basic parameters

Example request

{
   "Services": {
      "ServiceList": [
         {
            "Name": "CreditManagement3",
            "Action": "AddOrUpdateDebtor",
            "Parameters": [
               {
                  "Name": "Code",
                  "GroupType": "Debtor",
                  "GroupID": "",
                  "Value": "Johnsmith99"
               },
               {
                  "Name": "Culture",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "nl-NL"
               },
               {
                  "Name": "LastName",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "Smith"
               }
            ]
         }
      ]
   }
}

Response

(AddOrUpdateDebtor)

Parameters

Basic parameters

Example response:

{
  "Key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "Status": {
    "Code": {
      "Code": 190,
      "Description": "Success"
    },
    "SubCode": {
      "Code": "S001",
      "Description": "Transaction successfully processed"
    },
    "DateTime": "2019-05-17T08:57:38"
  },
  "RequiredAction": null,
  "Services": [
    {
      "Name": "CreditManagement3",
      "Action": null,
      "Parameters": [
        {
          "Name": "DebtorGuid",
          "Value": "xxxxxxxxxxxxxxxx"
        }
      ]
    }
  ],
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "ServiceCode": "CreditManagement3",
  "IsTest": true,
  "ConsumerMessage": null
}

CreatePaymentPlan

When an invoice is overdue – perhaps even already approaching being transferred to the collection agency – you may want to give the debtor the chance to pay in several smaller installments. You might do this to protect the relationship, or to increase the odds of receiving what you are owed.

A payment plan works as follows:

  • One or more of a single debtor’s existing invoices are included.

  • You may charge a cost for the payment plan. In this case, an extra invoice is created and included, its invoice number based on the payment plan’s chosen dossier number.

  • The sum open amount is distributed into either a set number of installments, or into installments of a set amount. (The last installment may have a smaller amount to ensure the correct total.)

  • You choose a start date and an interval, e.g. every month.

  • The debtor is informed of the payment plan, including all partial payment dates and amounts. See ‘Buckaroo Credit Management Payment Plan 1/5: Announcement’ in the Template Editor. (Note that this and the other templates can be edited to your liking.)

  • At every installment date, the debtor receives an e-mail with a pay link. See ‘Buckaroo Credit Management – Payment Plan 2/5: Payment Invitation’ in the Template Editor.

  • By default, only iDEAL is enabled for this pay link. You can contact Buckaroo to request additional payment methods to be made available in your payment plans.

  • If an installment is not paid within 7 days, the debtor receives a reminder. See ‘Buckaroo Credit Management – Payment Plan 3/5: Payment Reminder’ in the Template Editor.

  • If a reminder is ignored for another 3 days, at any point in the payment plan, the regular flow stops immediately. At this point, the debtor is given a last chance to pay the full remaining amount at once. See ‘Buckaroo Credit Management – Payment Plan 4/5: Last Chance’ in the Template Editor.

  • If the last chance is ignored for 14 days, the payment plan is cancelled and the debtor is informed. See ‘Buckaroo Credit Management – Payment Plan 5/5: Termination’. All included original invoices immediately go to their scheme’s ‘transfer to collection agency’ step, or to the end of their scheme if there is no such step. The invoices become active again. As such, if there is a collection agency, an invoice is immediately transferred.

Here is what else you should know:

  • Payment plans can be created through the CreatePaymentPlan request or from the Plaza’s invoice screen, directly on an invoice. From this point forward, the invoice screen shows the payment plan tab for each of the included invoices.

  • Payment plans can be terminated early through the TerminatePaymentPlan request or from the payment plan tab. In this case, the original invoices gain the ‘paused’ status (and can be manually resumed if desired). The debtor receives no notification of this termination, so you should inform them accordingly.

  • Payment plans can be paused from the payment plan tab. This is intended for emergencies only, as it has the natural side effect of shifting the upcoming partial payments further into the future. This means that the dates communicated in the initial announcement e-mail are no longer correct. As such, this feature should only be used in correspondence with the debtor.

  • Included invoices must be live invoices, must be active or paused, must have an open amount, and must have a DueDate that does not lie in the future.

  • Invoices that have been involved in a prior payment plan cannot be used.

  • When the payment plan is created, a simulated partial invoice is created for each expected partial payment. These are used internally to facilitate the process, and they should not be needed in your own administration. You can, however, still access them, in the payment plan tab (via any one of the original invoices). Also, if you receive push notification on invoices, you will receive them on the partial invoices as well, and should decide whether to use or ignore them.

  • Incoming transactions on the partial invoices are reflected on the originally included invoices, in order of due date, allowing them to become paid. This is done using a special, processing transaction type, much resembling the ‘External Payment’ transaction type. This allows you to fully ignore the partial invoices, and track only the state of the originally included invoices.

  • To refund payments on the payment plan, find the appropriate payment on the partial invoice. You should refund the payment itself, which is done on the partial invoice, rather than its reflection on the original invoices. The distinction should be evident from the transaction types. For instance, the partial invoice may have a transaction of type “iDEAL” (actual payment, with actual money refund this), whereas the original invoice will show a transaction of type “Partial payment on payment plan” (reflection, for administrative purposes). When you perform a refund in this way, the refund will get its own reflection on the original invoices, updating their paid amounts accordingly

Base JSON request

Use the base request as instructed on this page

Request

(CreatePaymentPlan)

Parameters

For this request, the basic parameter "Description" is required.

Basic parameters

Example request

{
   "Description": "Payment in two intstallments",
   "Services": {
      "ServiceList": [
         {
            "Name": "CreditManagement3",
            "Action": "CreatePaymentPlan",
            "Parameters": [
               {
                  "Name": "IncludedInvoiceKey",
                  "Value": "20D09973FB5C4DBC9A33DB0F4F707xxx"
               },
               {
                  "Name": "DossierNumber",
                  "Value": "PaymentplanJohnsmith123"
               },
               {
                  "Name": "InstallmentCount",
                  "Value": "2"
               },
               {
                  "Name": "StartDate",
                  "Value": "2017-09-21"
               },
               {
                  "Name": "Interval",
                  "Value": "Day"
               },
               {
                  "Name": "PaymentPlanCostAmount",
                  "Value": "0.00"
               },
               {
                  "Name": "RecipientEmail",
                  "Value": "johnsmith@example.nl"
               }
            ]
         }
      ]
   }
}

Response

(CreatePaymentPlan)

Parameters

Basic parameters

Example response:

{
   "Key": "9E5E5D160C814C3D94DD9283978ABxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2017-09-19T16:59:00"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "CreditManagement3",
         "Action": null,
         "Parameters": [
            {
               "Name": "InvoiceKey",
               "Value": "4CCD9334DA844D058BC3CBF983CEFxxx"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "CreditManagement3",
   "IsTest": true,
   "ConsumerMessage": null
}

Push

(CreatePaymentPlan)

Parameters

Basic parameters

Example push

{
   "Invoice": {
      "InvoiceKey": "4CCD9334DA844D058BC3CBF983CEFB92",
      "InvoiceNumber": "PaymentplanJohnsmith123-2",
      "WebsiteKey": "0000",
      "DebtorCode": "johnsmith4",
      "SchemeKey": "DefaultPP",
      "IsTest": false,
      "Type": "PartialInvoice",
      "Culture": "nl-NL",
      "InvoiceDate": "2017-09-19T00:00:00+02:00",
      "DueDate": "2017-09-22T00:00:00+02:00",
      "InvoiceStatusCode": 10,
      "PreviousStepIndex": 0,
      "PreviousStepDateTime": "0001-01-01T00:00:00+01:00",
      "Event": "ChangedStatus",
      "EventCategory": "FinancialChange",
      "EventDateTime": "2017-09-19T16:58:59.1374012+02:00",
      "EventParameters": [
         {
            "Key": "StatusCode",
            "Value": "10"
         }
      ],
      "Currency": "EUR",
      "AmountDebit": 0.01,
      "AmountCredit": 0,
      "AmountAdminCosts": 0,
      "AmountCreditNotes": 0,
      "AmountPaid": 0,
      "AmountAdminCostsPaid": 0,
      "AmountPendingSlow": 0,
      "OpenAmount": 0.01,
      "OpenAmountAdminCosts": 0,
      "OpenAmountInclAdminCosts": 0.01,
      "IsPaid": false,
      "CustomParameters": [],
      "AdditionalParameters": []
   }
}

TerminatePaymentPlan

As discussed under CreatePaymentPlan, this request can be used to terminate an active payment plan. The payment plan stops immediately, and the originally included invoices get the ‘paused’ status. The payment plan’s partial invoices are cancelled. You should inform the debtor accordingly.

No further payments can be received on the partial invoices, although payments can now be received on the original invoices again. Any successful payments resulting from the payment plan remain valid, of course.

Base JSON request

Use the base request as instructed on this page

Request

(TerminatePaymentPlan)

Parameters

Basic parameters

Example request

{
   "Services": {
      "ServiceList": [
         {
            "Name": "CreditManagement3",
            "Action": "TerminatePaymentPlan",
            "Parameters": [
               {
                  "Name": "IncludedInvoiceKey",
                  "Value": "20D09973FB5C4DBC9A33DB0F4F70xxx"
               }
            ]
         }
      ]
   }
}

Response

(TerminatePaymentPlan)

Parameters

Basic parameters

Example response:

{
   "Key": "74AAD64A6F2F46D38AB4145E18457xxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2017-09-19T17:16:22"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "CreditManagement3",
   "IsTest": true,
   "ConsumerMessage": null
}

Push

(TerminatePaymentPlan)

Parameters

Basic parameters

Example push:

  "Invoice": {
    "InvoiceKey": "20D09973FB5C4DBC9A33DB0F4F707xxx",
    "InvoiceNumber": "Testinvoice184915",
    "WebsiteKey": "0000",
    "DebtorCode": "Customercode123456",
    "SchemeKey": "khkn95",
    "IsTest": false,
    "Type": "RegularInvoice",
    "Culture": "nl-NL",
    "InvoiceDate": "2017-02-09T00:00:00+01:00",
    "DueDate": "2017-02-16T00:00:00+01:00",
    "InvoiceStatusCode": 20,
    "PreviousStepIndex": 1,
    "PreviousStepDateTime": "2017-03-01T00:50:06+01:00",
    "Event": "ChangedStatus",
    "EventCategory": "Other",
    "EventDateTime": "2017-09-19T17:16:22.4274001+02:00",
    "EventParameters": [
      {
        "Key": "StatusCode",
        "Value": "20"
      }
    ],
    "Currency": "EUR",
    "AmountDebit": 0.02,
    "AmountCredit": 0.0,
    "AmountAdminCosts": 0.0,
    "AmountCreditNotes": 0.0,
    "AmountPaid": 0.0,
    "AmountAdminCostsPaid": 0.0,
    "AmountPendingSlow": 0.0,
    "OpenAmount": 0.02,
    "OpenAmountAdminCosts": 0.0,
    "OpenAmountInclAdminCosts": 0.02,
    "IsPaid": false,
    "CustomParameters": [],
    "AdditionalParameters": []
  }
}

PauseInvoice

With the PauseInvoice action you can pause an invoice with the given invoice number.

Base JSON request

Use the base request as instructed on this page

Request

(PauseInvoice)

Parameters

For this action only the invoice (basic parameter) is required.

Basic parameters

Example request

{
   "Invoice": "Testinvoice184915",
   "Services": {
      "ServiceList": [
         {
            "Name": "CreditManagement3",
            "Action": "PauseInvoice"
         }
      ]
   }
}

Response

(PauseInvoice)

Parameters

Basic parameters

Example response:

{
   "Key": "A5968426DA0A467A89098B4D1F0Cxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2017-09-19T17:43:37"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "CreditManagement3",
   "IsTest": true,
   "ConsumerMessage": null
}

Push

(PauseInvoice)

Parameters

For an explanation on the parameters: see the push response in the CreateInvoice section.

Basic parameters

Example push

{
  "Invoice": {
    "InvoiceKey": "20D09973FB5C4DBC9A33DB0F4F707xxx",
    "InvoiceNumber": "Testinvoice184915",
    "WebsiteKey": "0000",
    "DebtorCode": "Customercode123456",
    "SchemeKey": "khkn95",
    "IsTest": false,
    "Type": "RegularInvoice",
    "Culture": "nl-NL",
    "InvoiceDate": "2017-02-09T00:00:00+01:00",
    "DueDate": "2017-02-16T00:00:00+01:00",
    "InvoiceStatusCode": 20,
    "PreviousStepIndex": 1,
    "PreviousStepDateTime": "2017-03-01T00:50:06+01:00",
    "Event": "ChangedStatus",
    "EventCategory": "Other",
    "EventDateTime": "2017-09-19T17:43:37.0801684+02:00",
    "EventParameters": [
      {
        "Key": "StatusCode",
        "Value": "20"
      }
    ],
    "Currency": "EUR",
    "AmountDebit": 0.02,
    "AmountCredit": 0.0,
    "AmountAdminCosts": 0.0,
    "AmountCreditNotes": 0.0,
    "AmountPaid": 0.0,
    "AmountAdminCostsPaid": 0.0,
    "AmountPendingSlow": 0.0,
    "OpenAmount": 0.02,
    "OpenAmountAdminCosts": 0.0,
    "OpenAmountInclAdminCosts": 0.02,
    "IsPaid": false,
    "CustomParameters": [],
    "AdditionalParameters": []
  }
}

UnpauseInvoice

With the UnpauseInvoice action you can resume a paused invoice with the given invoice number.

Base JSON request

Use the base request as instructed on this page

Request

(UnpauseInvoice)

Parameters

For this action only the invoice (basic parameter) is required.

Basic parameters

Example request

{
   "Invoice": "Testinvoice184915",
   "Services": {
      "ServiceList": [
         {
            "Name": "CreditManagement3",
            "Action": "UnPauseInvoice"
         }
      ]
   }
}

Response

(UnpauseInvoice)

Parameters

Basic parameters

Example response

{
   "Key": "AD7A5299205A4E8EAFCDD637929CFxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2017-09-19T17:46:14"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "CreditManagement3",
   "IsTest": true,
   "ConsumerMessage": null
}

Push

(UnpauseInvoice)

Parameters

Basic parameters

Example push

{
  "Invoice": {
    "InvoiceKey": "20D09973FB5C4DBC9A33DB0F4F707xxx",
    "InvoiceNumber": "Testinvoice184915",
    "WebsiteKey": "0000",
    "DebtorCode": "Customercode123456",
    "SchemeKey": "khkn95",
    "IsTest": false,
    "Type": "RegularInvoice",
    "Culture": "nl-NL",
    "InvoiceDate": "2017-02-09T00:00:00+01:00",
    "DueDate": "2017-02-16T00:00:00+01:00",
    "InvoiceStatusCode": 10,
    "PreviousStepIndex": 1,
    "PreviousStepDateTime": "2017-03-01T00:50:06+01:00",
    "Event": "ChangedStatus",
    "EventCategory": "Other",
    "EventDateTime": "2017-09-19T17:46:14.3219867+02:00",
    "EventParameters": [
      {
        "Key": "StatusCode",
        "Value": "10"
      }
    ],
    "Currency": "EUR",
    "AmountDebit": 0.02,
    "AmountCredit": 0.0,
    "AmountAdminCosts": 0.0,
    "AmountCreditNotes": 0.0,
    "AmountPaid": 0.0,
    "AmountAdminCostsPaid": 0.0,
    "AmountPendingSlow": 0.0,
    "OpenAmount": 0.02,
    "OpenAmountAdminCosts": 0.0,
    "OpenAmountInclAdminCosts": 0.02,
    "IsPaid": false,
    "CustomParameters": [],
    "AdditionalParameters": []
  }
}

InvoiceInfo

Perform this call to retrieve info about one invoice.

Base JSON request

Use the base request as instructed on this page

Request

(InvoiceInfo)

Parameters

Basic parameters

Example request

{
   "Invoice": "testinvoice123",
   "Services": {
      "ServiceList": [
         {
            "Name": "CreditManagement3",
            "Action": "InvoiceInfo"
         }
      ]
   }
}

Response

(InvoiceInfo)

Parameters

Basic parameters

Example response

{
   "Key": "D805757A03A9423AB59475295Axxxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2019-07-03T11:05:09"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "CreditManagement3",
         "Action": null,
         "Parameters": [
            {
               "Name": "AmountCredit",
               "Value": "0.00"
            },
            {
               "Name": "AmountDebit",
               "Value": "20.00"
            },
            {
               "Name": "AmountPaid",
               "Value": "20.00"
            },
            {
               "Name": "AmountVat",
               "Value": "3.47"
            },
            {
               "Name": "CreditManagement",
               "Value": "true"
            },
            {
               "Name": "InvoiceKey",
               "Value": "6A886AEE179645F3A990D8C3333xxxxx"
            },
            {
               "Name": "Paid",
               "Value": "True"
            },
            {
               "Name": "AgencyStatus",
               "Value": "unsent"
            },
            {
               "Name": "CmStatus",
               "Value": "10"
            },
            {
               "Name": "Active",
               "Value": "True"
            },
            {
               "Name": "StatusDateTime",
               "Value": "5/3/2019 12:33:08 AM"
            },
            {
               "Name": "AmountAdmincosts",
               "Value": "0.0000"
            },
            {
               "Name": "Running",
               "Value": "True"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "CreditManagement3",
   "IsTest": true,
   "ConsumerMessage": null
}

InvoiceInfo multiple invoices

Perform this call to retrieve info about multiple invoices. Extra invoices can be provided through the service parameter "InvoiceNumber". If an invoice number is provided through the basic field as well as through a service parameter, it's info will be returned only once in the reponse.

Base JSON request

Use the base request as instructed on this page

Request

(InvoiceInfo Multiple Invoices)

Parameters

Service specific parameters

Parameter Type Required Recommended Description
InvoiceNumber string InvoiceNumber
Basic parameters

Example request

{
   "Currency": "EUR",
   "Invoice": "INV001",
   "Services": {
      "ServiceList": [
         {
            "Name": "CreditManagement3",
            "Action": "InvoiceInfo",
            "Parameters": [
               {
                  "Name": "InvoiceNumber",
                  "GroupID": "1",
                  "Value": "INV002"
               },
               {
                  "Name": "InvoiceNumber",
                  "GroupID": "2",
                  "Value": "INV003"
               }
            ]
         }
      ]
   }
}

Response

(InvoiceInfo Multiple Invoices)

Parameters

Basic parameters

Example response

{
   "Key": "164810F253814B2DBDB066885D0Bxxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2020-09-08T14:27:53"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "CreditManagement3",
         "Action": null,
         "Parameters": [
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_AmountCredit",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_AmountDebit",
               "Value": "10.00"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_AmountPaid",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_AmountVat",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_CreditManagement",
               "Value": "True"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_InvoiceKey",
               "Value": "17CD5232302542DFBED3F942CE04"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_Paid",
               "Value": "False"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_AgencyStatus",
               "Value": "unsent"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_CmStatus",
               "Value": "10"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_Active",
               "Value": "True"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_StatusDateTime",
               "Value": "6/27/2019 2:25:58 PM"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_AmountAdminCosts",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_Description",
               "Value": "Invoice testing"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE043710_InvoiceNumber",
               "Value": "INV001"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_CmSchemeKey",
               "Value": "yf7yxx"
            },
            {
               "Name": "Invoice_17CD5232302542DFBED3F942CE04_Running",
               "Value": "True"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_AmountCredit",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_AmountDebit",
               "Value": "10.00"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_AmountPaid",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_AmountVat",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_CreditManagement",
               "Value": "True"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_InvoiceKey",
               "Value": "DEC11D0D3A334A85849EAE27A4F7"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_Paid",
               "Value": "False"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_AgencyStatus",
               "Value": "unsent"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_CmStatus",
               "Value": "10"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_Active",
               "Value": "True"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_StatusDateTime",
               "Value": "8/21/2020 2:31:57 PM"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_AmountAdminCosts",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_Description",
               "Value": ""
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_InvoiceNumber",
               "Value": "INV002"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_CmSchemeKey",
               "Value": "m5b5xx"
            },
            {
               "Name": "Invoice_DEC11D0D3A334A85849EAE27A4F7_Running",
               "Value": "True"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB46_AmountCredit",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_AmountDebit",
               "Value": "10.00"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_AmountPaid",
               "Value": "10.00"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_AmountVat",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_CreditManagement",
               "Value": "True"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_InvoiceKey",
               "Value": "4F971C31945F4E95A53FCE2FBB4"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_Paid",
               "Value": "True"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_AgencyStatus",
               "Value": "unsent"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_CmStatus",
               "Value": "10"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_Active",
               "Value": "True"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_StatusDateTime",
               "Value": "8/21/2020 1:48:56 PM"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB40_AmountAdminCosts",
               "Value": "0.00"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_Description",
               "Value": ""
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_InvoiceNumber",
               "Value": "INV003"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_CmSchemeKey",
               "Value": "m5b5xx"
            },
            {
               "Name": "Invoice_4F971C31945F4E95A53FCE2FBB4_Running",
               "Value": "True"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "CreditManagement3",
   "IsTest": true,
   "ConsumerMessage": null
}

DebtorInfo

Perform this call to retrieve Debtor information.

Base JSON request

Use the base request as instructed on this page

Request

(DebtorInfo)

Parameters

Service specific parameters

Parameter Type Required Recommended Description
DebtorCode string Required DebtorCode
Basic parameters

Example request

{
   "Services": {
      "ServiceList": [
         {
            "Name": "CreditManagement3",
            "Action": "DebtorInfo",
            "Parameters": [
               {
                  "Name": "DebtorCode",
                  "GroupType": "Debtor",
                  "GroupID": "",
                  "Value": "JanVanPietersen123"
               }
            ]
         }
      ]
   }
}

Response

(DebtorInfo)
The gateway response will provide any available information about the debtor. This can be name, address and contact information, as well as SubscriptionGuids and invoice numbers.

Parameters

Basic parameters

Example response

{
   "Key": "DD9CA9829CA14029AAE1C829B37841E8",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2020-03-23T09:52:48"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "CreditManagement3",
         "Action": null,
         "Parameters": [
            {
               "Name": "Guid",
               "Value": "79D054C8F89A4E9C8A618D1D7543F880"
            },
            {
               "Name": "Code",
               "Value": "JanVanPietersen123"
            },
            {
               "Name": "LastName",
               "Value": "Smith"
            },
            {
               "Name": "PersonCulture",
               "Value": "en-EN"
            },
            {
               "Name": "CompanyCulture",
               "Value": "nl-NL"
            },
            {
               "Name": "Name",
               "Value": "Buckaroo B.V."
            },
            {
               "Name": "VatApplicable",
               "Value": "False"
            },
            {
               "Name": "Email",
               "Value": "k.nguyen@buckaroo.nl"
            },
            {
               "Name": "Mobile",
               "Value": "3100000000"
            },
            {
               "Name": "Street",
               "Value": "Hoofdstraat"
            },
            {
               "Name": "HouseNumber",
               "Value": "90"
            },
            {
               "Name": "City",
               "Value": "HEERENVEEN\t"
            },
            {
               "Name": "Country",
               "Value": "NL"
            },
            {
               "Name": "ZipCode",
               "Value": "8841ER"
            },
            {
               "Name": "Landline",
               "Value": "3100000000"
            },
            {
               "Name": "InvoiceNumbers",
               "Value": "\"BCKMAG00000050\",\"BCKMAG00000049\",\"testinvoice12ewr3r\",\"BCKMAG00000048\",\"BCKMAG00000047\",\"testinvoice1ert23r\",\"BCKMAG00000046\",\"BATCHA12455110045\",\"BATCHA12455110041\",\"BATCHA12455110040\",\"BATCHA12455110038\",\"BATCHA12455110039\",\"BATCHA12455110037\",\"BATCHA12455110036\",\"BATCHA12455110035\",\"BATCHA12455110032\",\"BATCHA12455110030\",\"BATCHA12455110029\",\"BATCHA12455110027\",\"BATCHA12455110026\",\"BATCHA12455110025\",\"BATCHA12455110024\",\"BATCHA12455110021\",\"BATCHA12455110020\",\"BATCHA12455110016\",\"BATCHA12455110015\",\"BATCHA12455110014\",\"BATCHA12455110013\",\"BATCHA12455110012\",\"BATCHA12455110011\",\"BATCHA12455110008\",\"BATCHA12455110007\",\"BATCHA12455110006\",\"BATCHA12455110005\",\"BATCHA12455110003\",\"BATCHA12455110002\",\"BATCHA12455110001\",\"BATCHA12455110000\",\"Testert003\",\"TestPI1\",\"TestPDF13\",\"TestPDF11\",\"TestPDF10\",\"BCKMAG00000045\",\"testje1337115\",\"testje1337113\",\"testje1337112\",\"testje133711\",\"Tessafdsf\",\"testje13371\",\"BCKMAG00000044\",\"BCKMAG00000043\",\"testje123455\",\"testje123456\",\"testje1337\",\"BCKMAG00000042\",\"BCKMAG00000041\",\"BCKMAG00000040\",\"BCKMAG00000039\",\"BCKMAG00000038\",\"BCKMAG00000037\",\"BCKMAG00000036\",\"BCKMAG00000035\",\"BCKMAG00000034\",\"BCKMAG00000033\",\"BCKMAG00000032\",\"BCKMAG00000031\",\"BCKMAG00000030\",\"BCKMAG00000029\",\"BCKMAG00000028\",\"BCKMAG00000027\",\"BCKMAG00000026\",\"BCKMAG00000025\",\"BCKMAG00000024\",\"BCKMAG00000023\",\"BCKMAG00000022\",\"BCKMAG00000021\",\"Testinvoice000x1\",\"BCKMAG00000020\",\"BCKMAG00000019\",\"BCKMAG00000018\",\"BCKMAG00000017\",\"BCKMAG00000016\",\"Testfactuur022\",\"Testfactuur021\",\"Testfactuur007\",\"Testfactuur006\",\"BCKMAG00000015\",\"BCKMAG00000014\",\"BCKMAG00000013\",\"BCKMAG00000012\",\"BATCHERROR\",\"TestPDF9\",\"TestPDF8\",\"TestPDF7\",\"TestPDF6\",\"TestPDF5\",\"TestPDF4\",\"TestPDF3\",\"TestPDF2\""
            },
            {
               "Name": "SubscriptionGuids",
               "Value": "\"0DBD8C956D264C02BAA6E2967E875F01\",\"58FC6D51DF1A486580BA782796C61ABA\",\"0F23C7B60E274BD884E05DB7F074278B\",\"AD14253009BA48FD9EEB840ECA1DC451\",\"28EBAE9241D0471994DD003D9BF9CB8A\",\"6CF8BDD2F9AE4123BD256143D7E3C300\",\"BFF3BF4E9F3A4B328E36CC37D78D785A\",\"85B4C292402E40409715450D5CF46365\",\"276F8E6F21674DC9994EBE1FAB3F5763\",\"E079F7D223724BBABC103EB382A9DB3F\",\"47DF0687D3CF4E21BF82D26705F0D299\",\"123221885941454680923CB4497BF0C2\",\"576AA8DD8967469083F99BFE9441F905\",\"A6FD461CF7E24F798C29A82E15173406\",\"A84F33234AD24DEC935B8A49A1331416\""
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "CreditManagement3",
   "IsTest": true,
   "ConsumerMessage": null
}

AddOrUpdateProductLines

Perform this request to add or update product lines of an existing invoice. Besides an invoice key, product lines can be provided for the invoice specification.

Base JSON request

Use the base request as instructed on this page

Request

(AddOrUpdateProductLines)

Parameters

Service specific parameters

Parameter Type Required Recommended Description
InvoiceKey string Required Invoice key of the invoice for which product lines need to be added or updated.
Basic parameters

Example request

{
    "Services": {
        "ServiceList": [
            {
                "Name": "CreditManagement3",
                "Action": "AddOrUpdateProductLines",
                "Parameters": [
                    {
                        "Name": "InvoiceKey",
                        "Value": "xxxxxxxxxxxxxxxxxxxxxxxx"
                    },
                    {
                        "Name": "ProductId",
                        "GroupType": "ProductLine",
                        "GroupId": "1",
                        "Value": "2092"
                    },
                    {
                        "Name": "ProductName",
                        "GroupType": "ProductLine",
                        "GroupId": "1",
                        "Value": "Test"
                    },
                    {
                        "Name": "Quantity",
                        "GroupType": "ProductLine",
                        "GroupId": "1",
                        "Value": "1"
                    },
                    {
                        "Name": "PricePerUnit",
                        "GroupType": "ProductLine",
                        "GroupId": "1",
                        "Value": "50"
                    },
                    {
                        "Name": "VatPercentage",
                        "GroupType": "ProductLine",
                        "GroupId": "1",
                        "Value": "7"
                    },
                    {
                        "Name": "TotalVat",
                        "GroupType": "ProductLine",
                        "GroupID": 1,
                        "Value": "10"
                    },
                    {
                        "Name": "TotalAmount",
                        "GroupType": "ProductLine",
                        "GroupID": "1",
                        "Value": "200"
                    },
                    {
                        "Name": "Type",
                        "GroupType": "ProductLine",
                        "GroupId": "1",
                        "Value": "Regular"
                    }
                ]
            }
        ]
    }
}

Response

(AddOrUpdateProductLines)

Parameters

Basic parameters

Example response

{
   "Key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2017-09-19T17:46:14"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "CreditManagement3",
   "IsTest": true,
   "ConsumerMessage": null
}

Debtor Collection

Introduction

If an invoice is overdue, Credit Management is activated and its scheme will run with its defined steps and actions. So if a debtor has multiple overdue invoices, multiple schemes are being carried out for the debtor. This can cause an overload of communication and the debtor can have a harder time keeping track of which invoices are overdue and their individual payment terms. Secondly, it can become cumbersome to fulfill the invoices, since each invoice must be paid individually (through their own pay links). The goal of Credit Management is to perform the right actions to motivate the debtor to fulfills its payment obligation. As we can see, multiple overdue invoices can complicate this process.

Debtor collection is a feature that simplifies the credit management process if a debtor has multiple overdue invoices. Instead of running a scheme for each individual invoice, all overdue invoices are aggregated into a “Debtor File”. The Debtor File will then run its own scheme, on behalf of all invoices in it. Actions and communication performed from the Debtor File’s scheme are attuned to getting the Debtor File paid as a whole, as quickly as possible. Its communication should address and specify all overdue invoices clearly and lay out one set of payment terms that apply to all of them at the same time. Secondly, a possibility should be provided to fulfill the overdue invoices with one single payment.

There is no specific pre-configured Debtor File scheme. Instead, a Debtor File will always follow the scheme of the longest overdue invoice in the Debtor File. We call this invoice the “leading invoice”. The Debtor file carries out the steps and actions of the leading invoice’s scheme, but these actions will have a slighty different execution in the context of a Debtor File.

Flow

If a debtor has only one overdue invoice, its scheme will run its actions and these are performed for standard CM. If a second invoice of the debtor becomes overdue, its scheme will not be carried out. Instead, a Debtor file is created and both the first and second invoice is added to the Debtor file. The first invoice will be identified as the leading invoice, for it’s the one with the oldest DueDate. The Debtor File will then follow the scheme of the leading invoice and it will resume the scheme where it left off, since it already made progression. From then on, every action in the scheme is performed on Debtor Collection level. As long as the Debtor File is active, any subsequent invoice of this debtor that becomes overdue will be added to the Debtor File. If a Debtor File remains unpaid and reaches the end of its scheme, then the action(s) in the final step are executed and the Debtor File is terminated. The invoices in the Debtor File will not resume their individual schemes and therefore CM has ended for all invoices. A debtor can only have one active Debtor File at a time. Once a Debtor file is terminated (by fulfillment or ending its scheme), then a new one will be created once a second invoice becomes overdue.

Invoices in a Debtor File can still be paid separately, as explained a bit later. If an invoice in a Debtor File is fully paid, it will be removed from the Debtor File. The Debtor File continues its CM process for the remaining open invoices. This also means that if the paid invoice happened to be the leading invoice, the Debtor File will no longer follow its scheme. Instead, the invoice that's been in the Debtor File the longest at that moment will become the new leading invoice. The Debtor File will then resume the scheme of this new leading invoice from the point where this scheme would be if it were active since the DueDate of this leading invoice. This will usually lead to an extension of the remaining time for the debtor to fulfill the Debtor File.

Payments and refunds

A Debtor File has its own pay link, that can be used to perform one transaction to fulfill every invoice in the Debtor File. Buckaroo will register an external payment transaction for each invoice in the Debtor File. Another way to fulfill a Debtor File is via Bank Transfer. Each Debtor File has a Debtor File number. It is a bank transfer reference that can be used by the debtor to fulfill the Debtor File. With bank transfers, there is always a possibility that a lower amount is transferred than is needed to fulfill all invoices in the Debtor File. Buckaroo will always start with fulfilling the oldest overdue invoice to the newest one, until all invoices are paid. If the latter is the case, the Debtor File is terminated. If there is still a remaining part of the Debtor File not fulfilled, then the Debtor File stays active and its CM continues.

Even if a Debtor File is active, the possibility remains to pay each invoice in it separately. This can be done by using an invoice's individual pay link (it remains active) or performing a bank transfer with the invoice number as reference. If this happens, the data in the Debtor File will be updated; the remaining open Debtor File amount is updated and if an invoice is fully paid, it will be removed from the Debtor File.

If a debtor file payment is (partially) refunded, then it is up to the merchant to decide which invoice(s) should be re-opened. This can be done by refunding one or more related external payments. Note that the refund of an external payment is pure informational.

Configuration

For an invoice to be able to be included into a Debtor File, its scheme must have Debtor Collection enabled. This is an option that can be turned on in the scheme. By doing so, the invoice will also be able to function as a leading invoice of a Debtor File. Therefore, alternative Debtor Collection messages should be set up for reminders and custom events. The execution of each action in a Debtor File context is as follows:

  • Reminders. For the reminder action, an alternative Debtor Collection message should be set, next to the Standard CM message. A default Debtor Collection reminder template is available when setting up the Debtor Collection reminder in the scheme. The template provides an example text and tags to display information on the invoices in the Debtor File, the Debtor File pay link and the Debtor File Number.
  • Custom events. For the Custom event action, an alternative Debtor Collection custom event should be set.
  • Admin fee. Will only be charged for the leading invoice and therefore only once per Debtor File. The reason for this is that it is legally not permitted to charge admin fees for multiple invoices if they are aggregated in one reminder process.
  • Transfer to collection Agency. All invoices in a Debtor File will be transferred to the collection agency.
  • Stop subscription. All Buckaroo subscriptions that are linked to invoices in a Debtor File will be stopped.
  • Threshold. A Debtor File will ignore thresholds. As Debtor Collection aims to stimulate the debtor to fulfill multiple overdue invoices, using a threshold in this context is counter-intuitive and therefore not applicable.

Push

(Debtor Collection)

A Debtor File follows the scheme of the leading invoice. Therefore, every scheme event will only be pushed from the leading invoice. Events like financial mutations are always pushed for the involved invoices. In any case, an invoice that is part of a Debtor File will always specify the DebtorFileGuid, DebtorFileNumber and the DebtorFilePayLink.

Parameters

Service specific parameters

Parameter Type Required Recommended Description
DebtorFileGuid string Unique identifier of the Debtor File
DebtorFileNumber string Bank Transfer reference for the consumer to include in the Transfer's description. By providing the DebtorFileNumber, the transferred amount will be used fulfill the invoices in the Debtor File.
DebtorFilePaylink string Paylink to fulfill the Debtor File
Basic parameters

Example push

{
  "Invoice": {
    "InvoiceKey": "E3409F142BD94BB3B8047A73",
    "InvoiceNumber": "INV0001",
    "WebsiteKey": "vcKCNXSCDw",
    "DebtorCode": "JohnSmith123",
    "DebtorGuid": "903FADD72ABC4A6E91FCA5AE4",
    "SchemeKey": "abc123",
    "IsTest": false,
    "Type": "RegularInvoice",
    "Culture": "nl-NL",
    "InvoiceDate": "2021-10-01T00:00:00",
    "DueDate": "2021-10-01T00:00:00",
    "InvoiceStatusCode": 10,
    "PreviousStepIndex": 1,
    "PreviousStepDateTime": "2021-11-18T14:04:03",
    "InvoicePayLink": http://checkout.local/html/?brq_paydirect_inv=XXX,
    "Event": "SentReminderMessage",
    "EventCategory": "Other",
    "EventDateTime": "2021-11-18T14:06:29.7783014",
    "EventParameters": [
      {
        "Key": "CommunicationMethod",
        "Value": "Email"      },
      {
        "Key": "Template",
        "Value": "_Buckaroo.DebtorCollectionReminder.en.html"      }
    ],
    "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": [
    ],
    "DebtorFileGuid": "3B82F6ECDC1D4CF5BC856",    
    "DebtorFileNumber": "DNR000000106",
    "DebtorFilePayLink": http://checkout.local/html/?brq_paydirect_debtor_file=123 }
}

ResumeDebtorFile

Resumes a paused Debtor File. A Debtor File will be automatically paused if a reminder could not be sent due to incorrect or missing information.

Base JSON request

Use the base request as instructed on this page

Request

(ResumeDebtorFile)

Parameters

Service specific parameters

Parameter Type Required Recommended Description
DebtorFileGuid string Required Unique identifier of the Debtor File.
Basic parameters

Example request

{
  "Services": {
    "ServiceList": [
      {
        "Name": "CreditManagement3",
        "Action": "ResumeDebtorFile",
        "Parameters": [
          {
            "Name": "DebtorFileGuid",
            "Value": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
          }
        ]
      }
    ]
  }
}

Response

(ResumeDebtorFile)

Parameters

Basic parameters

Example response

{
  "Key": "A6FEBD16BD5849B38CF1AF3DBDB1",
  "Status": {
    "Code": {
      "Code": 190,
      "Description": "Success"
    },
    "SubCode": {
      "Code": "S001",
      "Description": "Transaction successfully processed"
    },
    "DateTime": "2020-11-19T15:29:40"
  },
  "RequiredAction": null,
  "Services": null,
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "ServiceCode": "Creditmanagement3",
  "IsTest": false,
  "ConsumerMessage": null
}

PauseDebtorFile

Perform this action to pause a debtor file.

Base JSON request

Use the base request as instructed on this page

Request

(PauseDebtorFile)

Parameters

Basic parameters

Example request

{
  "Services": {
    "ServiceList": [
      {
        "Name": "CreditManagement3",
        "Action": "PauseDebtorFile",
        "Parameters": [
          {
            "Name": "DebtorFileGuid",
            "Value": ""
          }
        ]
      }
    ]
  }
}

Response

(PauseDebtorFile)

Parameters

Basic parameters

Example response

{
  "Key": "D9B6D3B23FE245CA91E459326D0XXXXX",
  "Status": {
    "Code": {
      "Code": 490,
      "Description": "Failed"
    },
    "SubCode": {
      "Code": "S172",
      "Description": "Debtor file with key DAF93790B6CC489691658B814CCCCC is not active."
    },
    "DateTime": "2022-06-13T18:10:00"
  },
  "RequiredAction": null,
  "Services": null,
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "ServiceCode": "CreditManagement3",
  "IsTest": false,
  "ConsumerMessage": null
}

Was dit artikel nuttig?