Integration

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.

Testing

By default, a test invoice will not perform any CM steps (payment invitations included). If you wish to go through the Credit Management test flow in the test environment, you must create an invoice with a description (this is a basic parameter) that starts with "buckaroo_schema_test_". For example, your description could be: buckaroo_schema_test_Invoice123

Once the invoice has been created, you can go in the Buckaroo Plaza to Credit Management > Invoices and click on your invoice. Click on Actions at the top right and the name of the next step is displayed. Click on it to trigger the step. Please note that you need to have the Technical Administrator role for this.

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 Buckaroo Plaza under Credit Management -> CM scheme settings.

• 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.

Validation error messages

If a scheme action could not be performed due to a validation error, then it will be communicated with an invoice push. For each validation error we encounter in a scheme step, a ValidationErrorMessage will be provided in the push message (key value pair). This will be marked as a CmSchemeValidationError event.

In addition to this, Buckaroo will pause the invoice with invoice status code 23 (PausedDueToValidation) in the following situations:

The initial payment invitation (step 0) could not be performed due to a validation error
0 reminder message in a scheme step could be performed due to a validation error
The invoice could not be transferred to the collection agency due to a validation error

In these cases, we mark the event as InvoicePausedDueToValidationErrors.

Furthermore:

• Missing debtor information can be updated with the AddOrUpdateDebtor call or submitted via the Plaza.
• Missing product lines can be updated with the AddOrUpdateProductLines call.
• An invoice with invoice status 23 (PausedDueToValidation) can be unpaused at any time and will resume by re-executing the last scheme step.

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.

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.

The CreateCombinedInvoice is a transaction request. The CreateInvoice is a data request. The other calls are data requests only.

Data requests can be sent to https://checkout.buckaroo.nl/json/DataRequest (for live) or https://testcheckout.buckaroo.nl/json/DataRequest (for testing).

Transaction requests can be sent to https://checkout.buckaroo.nl/json/Transaction (for live) or https://testcheckout.buckaroo.nl/json/Transaction (for testing).