General

Credit Management is a service that registers an invoice with the Buckaroo Payment Engine. If desired, if the invoice remains unpaid beyond its due date, the system can send reminders and even transfer the invoice to a collection agency. Furthermore, certain reports can be generated.

Work flow

The general flow of a credit management is as follows:

When the due date on an invoice expires, steps on its schedule are taken in order, after their respective intervals. Each step consists of actions, such as sending a reminder to the debtor, or transferring the invoice to a collection agency if it remains unpaid1.

Reminders

A default schedule and default (e-mail) templates are available to merchants. Custom ones can be added in the Buckaroo Payment Plaza (depending on the credit management subscription). Furthermore, the invoice request can set the maximum number of steps to be taken in the invoice’s scheme. For example, the default scheme could be used both with and without its final TransferToCollectionAgency action, without the need to create two separate schemes.

Refunds & Credit notes

When an invoice is created in the Buckaroo Payment Engine it means that the debtor has a debt to the merchant. Doing a (partial) refund on a previously paid invoice will open up the invoice again, and will cause reminders to be sent to the debtor. To prevent this, create a credit note before creating the refund, to lower the debt for the debtor.

Additional Transactions

Additional transactions can be added to an existing invoice by using the same invoice number in a regular transaction request. (Note that the reverse is not possible, i.e. you cannot create an invoice for whose invoice number any transactions already exist.) Adding additional transactions can be useful for ExternalPayments, or to create a new transaction when a debtor does not finish their iDEAL transaction. Do not use this feature to create payment plans. Payment plans come with very strict legal restrictions. If your requirement is partial payments from the start, simply create a new invoice for each partial payment. For payment plans on overdue invoices, refer to the ‘CreatePaymentPlan’ section.

Credit Management Schemes

Invoices require a scheme to follow. The scheme defines what actions may be taken with regards to the invoice. Schemes are found in the Plaza under Configuration>Credit Management.

  • Scheme Keys. Each scheme has a short key consisting of letters and/or numbers. Invoice requests require such a key, to determine what scheme the invoice will follow.
  • Default Schemes. Certain schemes are available by default. For example, the scheme DefaultCM1 sends up to three e-mail reminders, two of which add administration costs, and may transfer the invoice to a collection agency if one is available. DefaultNone is a special case that allows invoices to be created without any follow-up actions. This is intended for merchants who want to create invoices, but do not want Buckaroo to take any further credit management actions for them. Default schemes cannot be edited. Rather, they can be duplicated, resulting in a new, editable scheme.
  • Custom Schemes. To add a new, custom scheme, use the button on the top left, or open an existing scheme and click Duplicate on the top right. A scheme consists of one or more steps. Steps are executed in order, with intervals, as long as the invoice remains open, i.e. not fully paid. Each step allows you to specify how many days after its predecessor it will be taken. For the first step, this number specifies how many days after the invoice is due. A step contains of one or more actions. When a step is taken, all its actions are executed, in the order the system deems appropriate. For instance, an administration cost increase is performed before sending the accompanying reminder, so that the updated information is included in the communication to the debtor.

Scheme Actions

  • Reminder. This action sends a reminder to the debtor. The chosen communication method may require certain debtor data when an invoice is created using this scheme. If the data does not suffice, the invoice request will be rejected up-front, and the system will provide information to help you provide the required data. Fallback methods can be specified for when the reminder attempt fails. For example, you can choose to send a letter or an SMS message if an e-mails (or if you have marked the e-mail address as unreachable). If you wish to send multiple simultaneous reminders, do not use fallbacks. Rather, set two separate reminder actions on a single step. For instance, you could send both and e-mail and an SMS message. Note that the letter and SMS options each require an additional module. Please contact Buckaroo if you wish to use them. Each communication method lets you define what to send, using the template link just below it. This opens a pop-up with settings for that particular reminder and method. This allows you to set different content for each reminder. In the template pop-up, specify a message template to use for one or more languages. The message template contains the content that will be sent. One language must be the default, meaning that it will be used if no template is set for the debtor’s language (perhaps that lone customer from an exotic place). English is usually a good choice of default. You can choose from several default templates or your own, or add new templates, which opens the Template Editor in a new window. Refer to the Templates section in this document for more information. Some additional info may be required, e.g. a subject and a reply-to address for an e-mail. Tags can be used here (refer to the section Tags in this document). Two important notes about reminders via SMS: 1) the sender name of an SMS will be the websitey name as defined for the used websitekey (it can be found here: https://plaza.buckaroo.nl/Configuration/WebSite/Index/.) It will leave out any spacing and contain a maximum of 11 characters, 2) SMS reminders will be sent between 09.00 and 22.00, depending on when an invoice status changes its status to unpaid.
  • Admin Cost Increase. This action adds administration costs to the invoice, increasing the amount due. This action can be used multiple time, each time increasing the total administration costs.
  • Transfer To Collection Agency. This action transfers the invoice to the given collection agency. You can choose from any supported collection agency that you have a subscription to. Note that collection agencies may require particular debtor data. The system validates this data on invoice requests, just as described for reminders. Alternatively, you can select ‘any’ collection agency. This chooses the preferred collection agency subscription, if there is one. The ‘DefaultCM1’ scheme, for example, uses this setting. As long as a merchant does not have an active, supported collection agency subscription, the action is ignored. Lastly, if you are subscribed to the collection agency Intrum Justitia, your invoice numbers cannot exceed the limit of 20 characters.
  • Threshold. A threshold action is always considered the first action in its step. As long as the invoice’s open amount is below the threshold (exclusive), the trajectory halts before the step. Should the open amount ever change to exceed the threshold, then the trajectory continues where it left off, i.e. starting with the aforementioned step. This could happen, for example, because of a direct debit reversal, or a refund without a credit note.
  • Payment Invitation. This action is very similar to the reminder action, but the communication is sent on the invoice date instead of after the due date. This option can only be set as the first action of a scheme and can be found above the first step. The only possible way to send a payment invitation is via e-mail. Selecting templates works the same way as in the reminder action.
  • Stop Subscription. This action can only be used in combination with subscriptions. When this action is reached, the subscription where the invoice belongs to, will be stopped immediately. A scheme with this action cannot be used with regular invoices.
  • Modifying Schemes. Changes to an existing scheme only affect new invoices created under that scheme from that point onward. Existing invoices under the scheme will follow the scheme as it was when the invoice was created. To let you view this information, modified schemes show a button labeled ‘show old versions’. All prior versions of the scheme are displayed (oldest at the bottom), along with the date and time at which they were replaced. For example, if the first version was active until 2016-01-01, and the second version was active until 2016-04-01, then an invoice created on 2016-03-01 is following the second version of the scheme.
  • Deleting Schemes. Schemes can be deleted if no invoices have been created that use it.

Templates

This section handles templates as they relate to the product. For detailed information on Templates, refer to its manual. Open the Template Editor under Configuration  Templates, or directly when choosing templates in a scheme. Choose the tab for the desired communication method (e.g. e-mail) and expand the relevant website. Besides the usual purpose-specific templates, such as “Buckaroo Credit Management credit note”, the reminders use a category that works slightly differently, “Buckaroo Credit Management”. On the one hand, the credit note templates (for example) are used when you create a credit note and specify the SendCreditNoteMessage parameter. It is a regular category that works as specified in the Template Editor manual, serving a specific purpose and being automatically used at the appropriate time. On the other hand, the “Buckaroo Credit Management” category can hold all sorts of reminders: first reminders, second reminders, tenth reminders, and so on. This means that multiple templates can be added for a language. The templates you add become available in the scheme editor (see next paragraph). The template simply defines a piece of text. It is the scheme that will determine in what situation a particular template is used. For example, Scheme “DefaultCM1” has a third reminder that, for English debtors, chooses to use template “_Buckaroo.ReminderLast.en”. Clearly, you should pick names that help distinguish the various templates you add. Then, back under Configuration  Credit Management, when editing a reminder action in a scheme (refer to the section Scheme Actions), and choosing templates for that reminder, simply choose the desired templates by name. Templates can be used in multiple places, if this is desired. In each place, custom information can be specified, such as the subject and reply-to address. Editing this information in the scheme, rather than in the Template Editor, provides greater flexibility and clearer context. After all, in a 7-step scheme supporting 5 languages, you will want to know exactly which reminder you are editing before settling on a subject. Or, as another example, you might use the same template in several schemes or steps, with a different subject or reply-to address.

Modifying Templates

Note that when you change the contents of a template, any scheme that uses it will now use the updated content. There is no versioning. Imagine that you update your logo or fix a typo: It seems preferable that this change affects existing schemes as well. To make a change that does not affect existing schemes, you can always create a new scheme and new templates, rather than edit existing templates.

Deleting Templates

To clean up in the Template Editor, templates can be deleted. In the regular scenario, such as for Buckaroo Credit Management credit note, this simply means that the template for that language is no longer available, and the default will be used, if there is one. If no template remains for said credit note, then a credit note request with the SendCreditNoteMessage parameter will not be able to inform the debtor. The Buckaroo Credit Management category is, again, slightly different. Templates that are in use by the current version of a scheme cannot be deleted. By deleting or modifying the scheme(s), i.e. no longer using the particular template, that template becomes eligible for deletion. As discussed under Modifying Schemes, existing invoices may still be following an older version of a scheme. This means that such invoices may still be using a template that is deleted by now. For this reason, the system retains the template internally, to continue communication according to that scheme version. However, deleted templates can no longer be viewed.

Tags

The content of messages can be made dynamic with tags. For example, an e-mail can use a salutation with the debtor’s name, or show the original invoice amount and the amount that is still open. Available tags are shown and explained on the bottom left when editing a template in the Template Editor. Note that tags that are available in the body of a message may also be used in details like its subject. Since the subject is set outside of the editor, you will need to enter the tag manually. For example, the subject “Reminder Invoice [InvoiceNumber]” may become something like “Reminder Invoice Inv20160001” when sent. For more information, refer to the Template Editor manual.

Invoice Push Notifications

Summary

If enabled (the default), push notifications are sent for invoices just as for transactions. Whenever an event of interest occurs (the invoice is created, a reminder is sent, an amount is paid, a credit note is created, etc.) a POST is made to the merchant’s push URL, with information about the event and the invoice itself. When creating an invoice through an API call (CreateInvoice & CreateCombinedInvoice), it's possible to provide a push URL in the request. If you do, every invoice push for that invoice will be sent to the URL provided, even if you send in new URLs for subsequent requests (such as a Creditnote request) that are related to this invoice. If you do not provide a push URL with the request that creates the invoice, the Plaza push URL will be used for this invoice. When you change the Plaza push URL, the invoice pushes will be sent to the new URL.

Invoice Push vs. Transaction Push

We recommend that merchants use the invoice push over the transaction push, since drawing conclusions about the invoice is more straightforward and less error-prone. Whether a payment is made, a refund is performed, or a credit note is created, the invoice push simply tells whether or not the invoice is now fully paid, and provides the current status of the invoice as a whole.

Order Of Events

Although pushes on an invoice almost always arrive in the original order of events, we recommend taking their EventDateTime into account, to avoid drawing conclusions from an outdated push. This is because there are some situations where the order cannot be guaranteed. For instance, if the HTML gateway is used, and the debtor is redirected back to the merchant’s website, we try to make sure that the merchant has received the latest push before we redirect the debtor, to allow the merchant to display the proper screen. To this end, the push is immediate (rather than queued), potentially catching up with earlier pushes that are still waiting in the send queue. In this scenario, the EventDateTime indicates that the latter pushes contain older information.

Use Case

As an example, let us take a look at a Sepa Direct Debit transaction, which benefits heavily from the invoice push.

  • The merchant creates an Invoice along with a Sepa Direct Debit transaction.
  • Let’s say the debtor misunderstands (it happens), and decides to wire transfer the money. The invoice push now informs the merchant that the invoice is fully paid.
  • The merchant calls the debtor, saying that the direct debit is about to take place, and the two agree that the wire transfer will be refunded, while the direct debit will be allowed to resolve.
  • The merchant refunds the wire transfer. The invoice push now informs the merchant that the invoice is no longer fully paid, because of the successful refund.
  • If the direct debit then succeeds, the invoice push informs the merchant that the invoice is (once again) fully paid. The merchant can proceed to deliver, if applicable. Should the debtor reverse the direct debit at a later time, the invoice push would report the change again. (Sepa Direct Debit is a reversible payment method. A non-reversible method would avoid this scenario.)
  • If the direct debit is rejected by the debtor before it succeeds, the flow of events is that (1) the original Sepa Direct Debit transaction becomes successful, and then (2) a reversal transaction is created and becomes successful. With the transaction push this could be confusing. The invoice push, however, is aware of both transactions. And although two successes lead to two invoice pushes, they each contain the final resulting amount, never showing the invoice as paid. This makes it easy to conclude whether or not to deliver.

Changes And Additions

The content of the push may change, so that Buckaroo can provide new features as they are invented. Although we avoid removing or renaming existing elements, your implementation must be able to deal with reordering and with additions of new parameters, events, status codes, etc. For example, if a push comes in for a new event that your implementation is not familiar with, the implementation should ignore it (or notify you of the change if you intend to implement new features as they become available). JSON is the recommended push format. Note that with JSON, the signature is included in the Authorization header, rather than in the body of the message.

Testing

By default, a test invoice will not send reminders. If you wish to go through the Credit Management flow in the test environment, you must create an invoice with the description parameter (this is a basic parameter) starting with "buckaroo_schema_test_", so for example your description could be: buckaroo_schema_test_Monthly invoice for subscription test.nl.

Once the invoice has been created, you can go to the Buckaroo plaza -> Invoices -> Overview and click on your invoice. Click on Actions at the top right and choose "Send reminder e-mail" to trigger the next reminder. Please note that you need to have the Technical Administrator role for this.

Servicecodes and actions

The service code for the Credit Management service is: CreditManagement3 The Credit Management service supports the following actions (using channel Web):

  • CreateInvoice: Creates an invoice with Credit Management.
  • CreateCombinedInvoice: Creates an invoice with Credit Management, in addition to the primary service’s transaction.
  • CreateCreditNote: Creates a credit note on an invoice.
  • AddOrUpdateDebtor: Adds or updates a debtor.
  • CreatePaymentPlan: Creates a payment plan for the debtor to pay the invoice in installments.
  • TerminatePaymentPlan: Terminates the payment plan.
  • PauseInvoice: Pause an invoice.
  • UnpauseInvoice: Resume a paused invoice.

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.

View in playground

Request


JSON gateway request

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.

InvoiceAmount
Required

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

The VAT amount on the invoice.

InvoiceDate
Required

The invoice date. (yyyy-mm-dd)

DueDate
Required

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
Required

The key of the scheme to use. Available keys are found in the Buckaroo Payment Plaza: Configuration > Credit Management.

MaxStepIndex

If given, only this many scheme steps are taken, allowing the scheme to be cut short. (min: 1)

AllowedServices

Allowed payment methods when using a pay link in Credit Management. This acts as a whitelist. Comma-separated. Cannot be combined with DisallowedServices. The order in which the payment methods are listed also determines the order in which they are displayed to the customer on the Buckaroo checkout page. Default: all services are allowed.

DisallowedServices

Disallowed payment methods when using a pay link in Credit Management. This acts as a blacklist. Comma-separated. Cannot be combined with AllowedServices. Default: all services are allowed.

AllowedServicesAfterDueDate

Allowed payment methods after the due date when using a pay link in Credit Management. This acts as a whitelist. Comma-separated. Cannot be combined with DisallowedServicesAfterDueDate. The order in which the payment methods are listed also determines the order in which they are displayed to the customer on the Buckaroo checkout page. Default: all services are allowed.

DisallowedServicesAfterDueDate

Disallow payment methods after the due date when using a pay link in Credit Management. This acts as a blacklist. Comma-separated. Cannot be combined with AllowServicesAfterDueDate. Default: all services are allowed.

Code
Required

GroupType: Debtor. A unique code by which the merchant identifies the debtor. If the debtor with this code exists, any given components are overwritten.

Culture

GroupType: Person. The person’s culture code. May be specific, e.g. nl-NL, en-US, or non-specific, e.g. en. Required if person information is provided.

Title

GroupType: Person. The person’s title.

Initials

GroupType: Person. The person’s initials.

FirstName

GroupType: Person. The person’s first name.

LastNamePrefix

GroupType: Person. The person’s last name prefix, e.g. ‘van der’.

LastName

GroupType: Person. The person’s last name, excluding prefix. Required if person information is provided.

Gender

GroupType: Person. The person’s gender. Possible values: 1, 2, 0, 9 (Male, female, unknown, not applicable. Default: 0).

BirthDate

GroupType: Person. The person’s date of birth (yyyy-mm-dd).

PlaceOfBirth

GroupType: Person. The person’s place of birth.

Culture

GroupType: Company. The company’s culture code. May be specific, e.g. nl-NL, en-US, or non-specific, e.g. en. Required if company information is provided.

Name

GroupType: Company. The company’s name. Required if company information is provided.

VatApplicable

GroupType: Company. Whether VAT applies to the company.

VatNumber

GroupType: Company. The company’s VAT identification number.

ChamberOfCommerce

GroupType: Company. The company’s Chamber of Commerce registration number.

Street

GroupType: Address. The address’ street name. Required if address is given.

HouseNumber

GroupType: Address. The address’ house number.

HouseNumberSuffix

GroupType: Address. The address’ house number suffix.

Zipcode

GroupType: Address. The address’ zip code. Required if address is given.

City

GroupType: Address. The address’ city. Required if address is given.

State

GroupType: Address. The address’ state or province.

Country

GroupType: Address. The address’ two-letter ISO country code, e.g. NL or US. Required if address is given.

Email

GroupType: Email. The e-mail address of the person or company.

Mobile

GroupType: Phone. The mobile phone number. Please note: this is the only number that can be used for SMS reminders. With regards to SMS reminders it is advised to send in the phone number formatted as either "+31612345678" or "0612345678", filtering out any dashes "-" and white spaces " ".

Landline

GroupType: Phone. The landline phone number.

Fax

GroupType: Phone. The fax number.

JSON

copy
{
   "Currency": "EUR",
   "Invoice": "testinvoice123r",
   "Services": {
      "ServiceList": [
         {
            "Name": "CreditManagement3",
            "Action": "CreateInvoice",
            "Parameters": [
               {
                  "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


JSON gateway response

InvoiceKey

The unique key that was created to identify the invoice.

DebtorGuid

Unique identifier of the debtor

JSON

copy
{
    "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


JSON invoice push

InvoiceKey

The unique key identifying the invoice. Was also output from the request that originally created the invoice.

InvoiceNumber

The invoice number.

WebsiteKey

The unique key identifying the website that the invoice belongs to.

DebtorCode

The unique code identifying the debtor that the invoice is for.

SchemeKey

The key of the scheme that the invoice follows.

IsTest

Does this concern a test invoice?

Type

The type of the invoice. Possible values: 1) RegularInvoice: the type of invoice that is normally used, 2) PartialInvoice: a partial invoice, such as those used in Payment Plans. Not applicable to most merchants, and can usually be ignored, 3) CreditNote: A credit note reducing the open amount of an existing invoice. The credit note also causes a financial change on the original invoice, which provides a clearer context. As such, the credit note push can usually be ignored.

Culture

The debtor’s culture, if available, or “en-US” otherwise.

InvoiceDate

The official date of the invoice.

DueDate

The date on which payment is due.

InvoiceStatusCode

The current status of the invoice. Possible Status codes are: 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. 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 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. 79: RefusedByCollectionAgency. The collection agency has not accepted the invoice. 80: WrittenOff. The invoice was manually written off by the merchant. 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.

PreviousStepIndex

The last step that was taken on the invoice’s scheme. E.g. 0 means no steps were taken, 1 means step 1 is the last step that was taken, and so on.

PreviousStepDateTime.

The moment the previous step was taken. DateTimes are in Buckaroo’s local time zone, CE(S)T, in ISO-8601 format, as seen in the examples. Most systems support automatic interpretation and conversion of this representation.

Event

The name of the event that caused this push. 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.

EventCategory

The category the event belongs to. Possible values: 1) FinancialChange; any change that relates to the invoice’s amounts, including the initial invoice creation, transaction status changes, and credit notes, 2) Other: anything else, e.g. a reminder being sent.

EventDateTime

The moment the event took place. Important, as earlier events should be ignored in case a later event has already been observed. See the section on “Order Of Events”. DateTimes are in Buckaroo’s local time zone, CE(S)T, in ISO-8601 format, as seen in the examples. Most systems support automatic interpretation and conversion of this representation.

EventParameters

Any number of additional pieces of data regarding the Event, as key-value pairs. E.g. the ChangedTransactionStatus event has a TransactionKey and a TransactionStatusCode parameter.

Currency

The invoice’s currency.

AmountDebit

An invoice’s amount. 0 for credit notes.

AmountCredit

A credit note’s amount. 0 except for credit notes.

AmountAdminCosts

The administration costs that have been added to the invoice so far, in accordance with its scheme.

AmountCreditNotes

The total amount that has been credited on the invoice, by means of credit notes.

AmountPaid

The total main amount that was paid on the invoice, i.e. excluding administration costs.

AmountAdminCostsPaid

The total amount of the administration costs that was paid on the invoice.

AmountPendingSlow

The total amount that could still come in from pending “slow” payment methods. At the time of writing, this only applies to pending Sepa Direct Debits. The invoice may not be paid yet, but it could very well become so when the payment succeeds, so we may not want to contact the debtor unless the payment fails.

OpenAmount

The main amount that is yet to be paid on the invoice, i.e. excluding administration costs.

OpenAmountAdminCosts

The amount of the administration costs that is yet to be paid on the invoice.

OpenAmountInclAdminCosts

The amount that is yet to be paid on the invoice, including administration costs.

IsPaid

Is the invoice fully paid? This is the same as OpenAmount being greater than 0. We do not take administration costs into consideration.

DebtorGuid

Unique identifier of the debtor

JSON

copy
{
  "Invoice": {
    "InvoiceKey": "9C9D0305DE4A47178DE903FA91C1xxxx",
    "InvoiceNumber": "testinvoice12xcx",
    "WebsiteKey": "0000",
    "DebtorCode": "johnsmith4",
    "DebtorGuid": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "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": 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-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,
    "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.

View in playground

Request


JSON gateway response

In this example, a Sepa Direct Debit is performed, combined with the CreateCombinedInvoice action of CreditManagement.

The requests consists of Sepadirectdebit parameters (for an explanation, see the Sepadirectdebit service section) and the CreateInvoice parameters (see previous call).

JSON

copy
{
   "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


JSON gateway response

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

InvoiceKey

The unique key identifying the invoice.

DebtorGuid

Unique identifier of the debtor

JSON

copy
{
   "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


JSON invoice push response

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

InvoiceKey

The unique key that was created to identify the invoice.

DebtorGuid

Unique identifier of the debtor

JSON

copy
{
   "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.

View in playground

Request


JSON gateway request

OriginalInvoiceNumber
Required

The invoice number of the original invoice that the credit note applies to.

InvoiceDate
Required

The credit note date. (yyyy-mm-dd)

InvoiceAmount
Required

The amount credited by the credit note. Positive.

InvoiceAmountVat

The VAT amount on the credit note. Positive. Must not exceed the original invoice VAT amount.

SendCreditNoteMessage

Any number of communication methods to use to inform the debtor of the credit note, comma-separated, in order of preference. Example: Email,SMS,Letter. If an e-mail address is available, it is used. Otherwise, SMS and letter are attempted in order.

JSON

copy
{
  "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


JSON gateway response

InvoiceKey

The unique key identifying the invoice.

JSON

copy
{
   "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


JSON invoice push response

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

JSON

copy
{
  "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.

View in playground

Request


AddOrUpdateDebtor uses all the parameters defined for CreateInvoice starting at the Debtor Group, down to the end. When adding a new Debtor, it is required to at least identify it as either a Person or a Company. This means that the person's last name or company name needs to be provided, as well as its culture. When updating a Debtor, this is not required, unless you wish to change their name or culture.

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.

AddressUnreachable

GroupType: Address.The given address is marked as unreachable (true), or the mark is removed (false).

EmailUnreachable

GroupType: Email. The given e-mail address is marked as unreachable (true), or the mark is removed (false).

MobileUnreachable

GroupType: Phone. The given mobile phone number is marked as unreachable (true), or the mark is removed (false).

LandlineUnreachable

GroupType: Phone.The given landline phone number is marked as unreachable (true), or the mark is removed (false).

FaxUnreachable

GroupType: Phone. The given fax number is marked as unreachable (true), or the mark is removed (false).

JSON

copy
{
   "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


JSON gateway response

This response contains no service specific parameters.

DebtorGuid

Unique identifier of the debtor

JSON

copy
{
  "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
View in playground

Request


JSON gateway request

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

IncludedInvoiceKey
Required

Pass once for each invoice key to include, e.g. IncludedInvoiceKey_1 = 737DDEC84BEE46298D029DBE0E6B397D, IncludedInvoiceKey_2 = D73F5D3BE1294799B5346E3E86CEF6DA. Maximum is 100.

DossierNumber
Required

A unique dossier number to identify the payment plan.

InstallmentCount
Required

The number of installments. Required unless InstallmentAmount is given.

InstallmentAmount
Required

The amount to be paid for each installment. The last installment may become lower, if necessary. Required unless InstallmentCount is given.

InitialAmount

If given, the first installment uses this amount instead of the amount used by the other installments. Can be used to require a show of the debtor’s good will.

StartDate
Required

The date of the first installment, i.e. when the first e-mail is sent. May be today or later.

Interval
Required

The interval between installments. Possible values: Day, TwoDays, Week, TwoWeeks, HalfMonth, Month, TwoMonths, QuarterYear, HalfYear, Year.

PaymentPlanCostAmount
Required

The cost charged to the debtor for the payment plan. If greater than 0, an invoice is created to accommodate this cost.

PaymentPlanCostAmountVat

For your own administration, you may specify how much of PaymentPlanCostAmount concerns VAT.

RecipientEmail
Required

The e-mail address to use for all communication regarding the payment plan. Should generally be the debtor’s own e-mail address.

JSON

copy
{
   "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


JSON gateway response

InvoiceKey

The unique key identifying the newly created partial invoice.

JSON

copy
{
   "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


JSON invoice push response

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

JSON

copy
{
   "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.

View in playground

Request


JSON gateway request

IncludedInvoiceKey
Required

Pass any one (and only one) of the originally included invoice keys, e.g. IncludedInvoiceKey = 737DDEC84BEE46298D029DBE0E6B397D. Only one invoice key is needed for the system to find the payment plan.

JSON

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

Response


JSON gateway response

This response contains no service specific parameters.

JSON

copy
{
   "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


JSON invoice push response

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

JSON

copy
{
  "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.

View in playground

Request


JSON gateway request

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

JSON

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

Response


JSON gateway response

This response contains no service specific parameters.

JSON

copy
{
   "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


JSON invoice push response

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

JSON

copy
{
  "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.

View in playground

Request


JSON gateway request

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

JSON

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

Response


JSON gateway response

This response contains no service specific parameters.

JSON

copy
{
   "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


JSON invoice push response

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

JSON

copy
{
  "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 an invoice.

View in playground

Request


JSON gateway request

JSON

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

Response


JSON gateway response

JSON

copy
{
   "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
}