General

A PaymentGuarantee results in at least 1 transaction, namely the PaymentGuarantee transaction. This transaction however will never have a payment directly associated with it. Instead, whenever a consumer follows the paylink and starts the payment process on the payment page, a new transaction and a payment of the selected payment method will be created. Once the payment (and consequently the associated transaction) succeeds, the associated invoice will be paid. A transaction push will then be given on the new transaction. If the consumer does not pay, a new transaction with payment will be created after the guarantee period expires.

Service codes and actions

The PaymentGuarantee service uses the service code: paymentguarantee

The PaymentGuarantee services supports the following actions: PaymentInvitation, CreditNote, Order, PartialInvoice, ReduceGuaranteedAmount.

PaymentInvitation

The paymentinvitation action is the default action provided by the PaymentGuarantee service. The action is used to register a payment invitation and perform the risk check. If the risk check is successful, it will result in a paylink that is either sent via email by Buckaroo, or that is returned in the response message, so the merchant can send it via email.

View in playground

Request


JSON gateway request

InvoiceDate
Required

The (expected) delivery date of the invoice.

DateDue
Required

The due date by which the customer must have paid. This should be InvoiceDate + 14 days.

PaymentMethodsAllowed

This is a comma separated list of service codes that specify which of services can be used to pay the payment guarantee invoice.

SendMail

If set to true (default), the payment engine will send a confirmation email to the customer. (Boolean)

CustomerCode
Required

The customer ID , giving a unique ID to the customer for the merchant.

CustomerTitle

The title to use for a customer.

CustomerInitials
Required

The initials for the customer (first letter of each first name).

CustomerFirstName
Required

The first name of the customer.

CustomerLastNamePrefix

The prefix for the surname of the customer.

CustomerLastName
Required

The surname of the customer (without any prefixes)

CustomerGender
Required

The customer gender. Possible values: 1: Male 2: Female

CustomerBirthDate
Required

The date of birth of the customer.

CustomerEmail
Required

The e-mail address of the customer.

PhoneNumber
Required

The phone number for the customer’s landline. Either PhoneNumber or MobilePhoneNumber (or both) must be supplied.

MobilePhoneNumber
Required

The phone number for the customer’s cellular. Either PhoneNumber or MobilePhoneNumber (or both) must be supplied.

FaxNumber

The fax number for the customer.

CustomerIBAN
Required

The bank account number of the customer. This must be a SEPA IBAN number.

AddressType
Required

GroupType: "address". The type of address. 1 or more of the values below can be provided together in a comma separated list: INVOICE: if the address is the invoice address. SHIPPING: if items is being shipped to this address. HOME: if this is the home address for the customer. It is required to specify at least an invoice address and shipping address. (Though they can both be sent in together in the same address group, just set AddressType to “INVOICE,SHIPPING”)

Street
Required

GroupType: "address". The street name of the address.

HouseNumber
Required

GroupType: "address". The house number for the address..

HouseNumberSuffix

GroupType: "address". The house number suffix for the address.

ZipCode
Required

GroupType: "address". The zipcode for the address.

City
Required

GroupType: "address". The city for the address.

Country
Required

GroupType: "address". The country belonging to the address.

clientip
Required

In this field the IP address of the customer for which the action is being performed must be passed. Please note: This is a basic request variable, not a service specific variable.

JSON

copy
{
   "Currency": "EUR",
   "AmountDebit": 10,
   "Invoice": "testinvoice 123",
   "ClientIP": {
      "Type": 0,
      "Address": "0.0.0.0"
   },
   "Services": {
      "ServiceList": [
         {
            "Name": "paymentguarantee",
            "Action": "PaymentInvitation",
            "Parameters": [
               {
                  "Name": "AmountVat",
                  "Value": "1.00"
               },
               {
                  "Name": "InvoiceDate",
                  "Value": "05-07-2018"
               },
               {
                  "Name": "DateDue",
                  "Value": "19-07-2018"
               },
               {
                  "Name": "PaymentMethodsAllowed",
                  "Value": "ideal,paypal,mastercard,visa"
               },
               {
                  "Name": "SendMail",
                  "Value": "true"
               },
               {
                  "Name": "CustomerCode",
                  "Value": "123abc"
               },
               {
                  "Name": "CustomerInitials",
                  "Value": "JS"
               },
               {
                  "Name": "CustomerFirstName",
                  "Value": "John"
               },
               {
                  "Name": "CustomerLastName",
                  "Value": "Smith"
               },
               {
                  "Name": "CustomerGender",
                  "Value": "1"
               },
               {
                  "Name": "CustomerBirthDate",
                  "Value": "01-01-1990"
               },
               {
                  "Name": "CustomerEmail",
                  "Value": "your@email.com"
               },
               {
                  "Name": "MobilePhoneNumber",
                  "Value": "0601234567"
               },
               {
                  "Name": "CustomerIBAN",
                  "Value": "NL13TEST0123456789"
               },
               {
                  "Name": "AddressType",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "Invoice"
               },
               {
                  "Name": "Street",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "Hoofdstraat"
               },
               {
                  "Name": "HouseNumber",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "90"
               },
               {
                  "Name": "HouseNumberSuffix",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "A"
               },
               {
                  "Name": "ZipCode",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "8441ER"
               },
               {
                  "Name": "City",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "Heerenveen"
               },
               {
                  "Name": "Country",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "NL"
               },
               {
                  "Name": "AddressType",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "Shipping"
               },
               {
                  "Name": "Street",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "Afleverstraat"
               },
               {
                  "Name": "HouseNumber",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "1"
               },
               {
                  "Name": "HouseNumberSuffix",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "B"
               },
               {
                  "Name": "ZipCode",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "1000ER"
               },
               {
                  "Name": "City",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "Leeuwarden"
               },
               {
                  "Name": "Country",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "NL"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

JSON

copy
{
   "Key": "6B6D487C94784F6DB772F18B87xxxxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": null,
      "DateTime": "2018-07-05T14:15:20+02:00"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "paymentguarantee",
         "Action": null,
         "Parameters": [
            {
               "Name": "paylink",
               "Value": "https://testcheckout.buckaroo.nl/html/?brq_paydirect_trx=6B6D487C94784F6DB772F18B8xxxxxx"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice 123",
   "ServiceCode": "paymentguarantee",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 10,
   "TransactionType": "I242",
   "MutationType": 3,
   "RelatedTransactions": null,
   "ConsumerMessage": null,
   "Order": "testinvoice 123",
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": "John Smith",
   "PayerHash": null,
   "PaymentKey": null
}

Push


JSON push response

JSON

copy
{
   "Transaction": {
      "Key": "6B6D487C94784F6DB772F18B87Bxxxxx",
      "Invoice": "testinvoice 123",
      "ServiceCode": "paymentguarantee",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": null,
         "DateTime": "2018-07-05T14:15:20"
      },
      "IsTest": true,
      "Order": "testinvoice 123",
      "Currency": "EUR",
      "AmountDebit": 10,
      "TransactionType": "I242",
      "Services": [
         {
            "Name": "paymentguarantee",
            "Action": null,
            "Parameters": [
               {
                  "Name": "paylink",
                  "Value": "https://testcheckout.buckaroo.nl/html/?brq_paydirect_trx=6B6D487C94784F6DB772F18B87Bxxxxx"
               }
            ],
            "VersionAsProperty": 1
         }
      ],
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 3,
      "RelatedTransactions": null,
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": "John Smith",
      "PayerHash": null,
      "PaymentKey": null
   }
}

CreditNote

CreditNote is a separate primary action which can be performed to register a credit note for a Payment Guarantee invoice. The amount of the credit note will be subtracted from the invoice amount (principal amount). This can be the same amount as the original invoice, leaving no remaining amount to pay or send reminders for, or any smaller amount. Multiple credit notes are allowed but the sum may never exceed the original invoice amount. A credit note doesn’t automatically result in a refund, so when a credit note is created after a payment is done, and the amount paid is higher than the remaining principal amount, a separate refund must be done. Because a refund is also a primary action, this cannot be done in a single transaction request.

Order

The order action is a primary action used to register an order with a risk check on it. This means that for the guarantee duration separate invoices can then be registered with the payment engine (using the PartialInvoice action) which will be covered by this guarantee.  Please note that when doing an Order it is not possible to provide an invoice number for the transaction. Only an order number can then be provided.

View in playground

Request


JSON gateway request

OrderDate
Required

The date of the order.

Order
Required

Order number. Note: This is a basic parameter, not a service parameter.

AmountVat
Required

The VAT amount for the transaction.

OrderDate
Required

The date of the order.

CustomerCode
Required

The customer ID, giving a unique ID to the customer for the merchant.

CustomerTitle

The title to use for a customer.

CustomerInitials
Required

The initials for the customer (first letter of each first name).

CustomerFirstName
Required

The first name of the customer.

CustomerLastNamePrefix

The prefix for the surname of the customer.

CustomerLastName
Required

The last name of the customer (without any prefixes).

CustomerGender
Required

The customer gender. Possible values: 1: Male 2: Female

CustomerBirthDate
Required

The date of birth of the customer.

CustomerEmail
Required

The email address of the customer.

PhoneNumber
Required

The phone number for the customer’s landline. Either PhoneNumber or MobilePhoneNumber (or both) must be supplied.

MobilePhoneNumber
Required

The phone number for the customer’s cellular. Either PhoneNumber or MobilePhoneNumber (or both) must be supplied.

FaxNumber

The fax number for the customer.

CustomerIBAN
Required

The bank account number of the customer. This must be a SEPA IBAN number.

AddressType
Required

GroupType: "address". The type of address. 1 or more of the values below can be provided together in a comma separated list: INVOICE: if the address is the invoice address. SHIPPING: if items is being shipped to this address. HOME: if this is the home address for the customer. It is required to specify at least an invoice address and shipping address. (Though they can both be sent in together in the same address group, just set AddressType to “INVOICE,SHIPPING”).

Street
Required

GroupType: "address". The street name of an address. These are all part of the “address” parameter group type. Remember to also use this group type when creating the request. Additionally, the multiple addresses can be supplied, identifying each one with a unique group name.

HouseNumber
Required

GroupType: "address". The house number for an address.

HouseNumberSuffix

GroupType: "address". The house number suffix for an address.

ZipCode
Required

GroupType: "address". The zipcode for an address.

City
Required

GroupType: "address". The city for an address.

State

The state for an address.

Country
Required

GroupType: "address". The country belonging to an address.

JSON

copy
{
   "Currency": "EUR",
   "AmountDebit": 10,
   "Order": "testorder 123",
   "ClientIP": {
      "Type": 0,
      "Address": "0.0.0.0"
   },
   "Services": {
      "ServiceList": [
         {
            "Name": "paymentguarantee",
            "Action": "Order",
            "Parameters": [
               {
                  "Name": "AmountVat",
                  "Value": "1.00"
               },
               {
                  "Name": "OrderDate",
                  "Value": "05-07-2018"
               },
               {
                  "Name": "DateDue",
                  "Value": "19-07-2018"
               },
               {
                  "Name": "PaymentMethodsAllowed",
                  "Value": "ideal,paypal,mastercard,visa"
               },
               {
                  "Name": "SendMail",
                  "Value": "true"
               },
               {
                  "Name": "CustomerCode",
                  "Value": "123abc"
               },
               {
                  "Name": "CustomerInitials",
                  "Value": "JS"
               },
               {
                  "Name": "CustomerFirstName",
                  "Value": "John"
               },
               {
                  "Name": "CustomerLastName",
                  "Value": "Smith"
               },
               {
                  "Name": "CustomerGender",
                  "Value": "1"
               },
               {
                  "Name": "CustomerBirthDate",
                  "Value": "01-01-1990"
               },
               {
                  "Name": "CustomerEmail",
                  "Value": "your@email.com"
               },
               {
                  "Name": "MobilePhoneNumber",
                  "Value": "0601234567"
               },
               {
                  "Name": "CustomerIBAN",
                  "Value": "NL13TEST0123456789"
               },
               {
                  "Name": "AddressType",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "Invoice"
               },
               {
                  "Name": "Street",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "Hoofdstraat"
               },
               {
                  "Name": "HouseNumber",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "90"
               },
               {
                  "Name": "HouseNumberSuffix",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "A"
               },
               {
                  "Name": "ZipCode",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "8441ER"
               },
               {
                  "Name": "City",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "Heerenveen"
               },
               {
                  "Name": "Country",
                  "GroupType": "Address",
                  "GroupID": "1",
                  "Value": "NL"
               },
               {
                  "Name": "AddressType",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "Shipping"
               },
               {
                  "Name": "Street",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "Afleverstraat"
               },
               {
                  "Name": "HouseNumber",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "1"
               },
               {
                  "Name": "HouseNumberSuffix",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "B"
               },
               {
                  "Name": "ZipCode",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "1000ER"
               },
               {
                  "Name": "City",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "Leeuwarden"
               },
               {
                  "Name": "Country",
                  "GroupType": "Address",
                  "GroupID": "2",
                  "Value": "NL"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

OrderKey

Unique key to identify the order.

JSON

copy
{
   "Key": "14E4630063F1481DA2BD3F911669xxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": null,
      "DateTime": "2018-07-05T14:26:45+02:00"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "paymentguarantee",
         "Action": null,
         "Parameters": [
            {
               "Name": "OrderKey",
               "Value": "156715452046452289BFA3351404xxxx"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": null,
   "ServiceCode": "paymentguarantee",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 10,
   "TransactionType": "I246",
   "MutationType": 3,
   "RelatedTransactions": null,
   "ConsumerMessage": null,
   "Order": "testorder 123",
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": "John Smith",
   "PayerHash": null,
   "PaymentKey": null
}

Push


JSON push response

OrderKey

Unique key to identify the order

JSON

copy
{
   "Transaction": {
      "Key": "14E4630063F1481DA2BD3F911669xxxx",
      "Invoice": null,
      "ServiceCode": "paymentguarantee",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": null,
         "DateTime": "2018-07-05T14:26:45"
      },
      "IsTest": true,
      "Order": "testorder 123",
      "Currency": "EUR",
      "AmountDebit": 10,
      "TransactionType": "I246",
      "Services": [
         {
            "Name": "paymentguarantee",
            "Action": null,
            "Parameters": [
               {
                  "Name": "OrderKey",
                  "Value": "156715452046452289BFA3351404xxxx"
               }
            ],
            "VersionAsProperty": 1
         }
      ],
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 3,
      "RelatedTransactions": null,
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": "John Smith",
      "PayerHash": null,
      "PaymentKey": null
   }
}

PartialInvoice

The PartialInvoice action is a primary action used to register an invoice on an earlier performed order. The only validation that is done is checking if the guarantee is still valid and if enough of the guarantee amount remains for the offered invoice. (It is possible to offer multiple partial invoices on a single order) If the validation is successful, it will result in a paylink that is either sent via email by Buckaroo, or that is returned in the response message, so the merchant can sent it via email. Please note that when doing a PartialInvoice Request, the OrderNumber basic request parameter is also required.

View in playground

Request


JSON gateway request

InvoiceDate
Required

The (expected delivery) date of the invoice

CustomerCode
Required

The customer ID , giving a unique ID to the customer for the merchant.

PaymentMethodsAllowed

This is a comma separated list of service codes that specify which of services can be used to pay the payment guarantee invoice

SendMail

If set to true, the payment engine will send a confirmation email to the customer.

AmountVat
Required

The VAT amount for the transaction

DateDue
Required

The due date by which the customer must have paid. This should be InvoiceDate + 14 days.

JSON

copy
{
   "AmountDebit": 5,
   "Currency": "EUR",
   "Invoice": "testinvoice123xx3",
   "Order": "testorder 123sdfsdf",
   "Services": {
      "ServiceList": [
         {
            "Name": "paymentguarantee",
            "Action": "PartialInvoice",
            "Parameters": [
               {
                  "Name": "InvoiceDate",
                  "Value": "18-10-2018"
               },
               {
                  "Name": "CustomerCode",
                  "Value": "123abc"
               },
               {
                  "Name": "PaymentMethodsAllowed",
                  "Value": "ideal,mastercard,visa,amex,paypal"
               },
               {
                  "Name": "SendMail",
                  "Value": "TRUE"
               },
               {
                  "Name": "AmountVat",
                  "Value": "1.00"
               },
               {
                  "Name": "DateDue",
                  "Value": "01-11-2018"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

JSON

copy
{
   "Key": "B33E5B988034412099B94153680Exxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": null,
      "DateTime": "2018-10-18T13:59:50+02:00"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "paymentguarantee",
         "Action": null,
         "Parameters": [
            {
               "Name": "PayLink",
               "Value": "https://testcheckout.buckaroo.nl/html/?brq_paydirect_trx=B33E5B9880xxxxx"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice123xx3",
   "ServiceCode": "paymentguarantee",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 5,
   "TransactionType": "I247",
   "MutationType": 3,
   "RelatedTransactions": null,
   "ConsumerMessage": null,
   "Order": "testorder 123sdfsdf",
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": "John Smith",
   "PayerHash": null,
   "PaymentKey": null
}

Push


JSON push response

JSON

copy
{
   "Transaction": {
      "Key": "B33E5B988034412099B94153680Exxxx",
      "Invoice": "testinvoice123xx3",
      "ServiceCode": "paymentguarantee",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": null,
         "DateTime": "2018-10-18T13:59:50"
      },
      "IsTest": true,
      "Order": "testorder 123sdfsdf",
      "Currency": "EUR",
      "AmountDebit": 5,
      "TransactionType": "I247",
      "Services": [
         {
            "Name": "paymentguarantee",
            "Action": null,
            "Parameters": [
               {
                  "Name": "PayLink",
                  "Value": "https://testcheckout.buckaroo.nl/html/?brq_paydirect_trx=B33E5B9880xxx"
               }
            ],
            "VersionAsProperty": 1
         }
      ],
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 3,
      "RelatedTransactions": null,
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": "John Smith",
      "PayerHash": null,
      "PaymentKey": null
   }
}

ReduceGuaranteedAmount

When placing an order with the order action, it is possible te refund the guaranteed amount to Focum. To do this, perform the ReduceGuaranteedAmount action.

View in playground

Request


JSON gateway request

OrderNumber
Required

The order number of the original order

Currency
Required

Currency. Note: This is a basic parameter, not a service parameter.

Amountcredit
Required

The reduced amount. Note: This is a basic paramter, not a service parameter.

JSON

copy
{
   "Currency": "EUR",
   "Amountcredit": 1.00,
   "Services": {
      "ServiceList": [
         {
            "Name": "paymentguarantee",
            "Action": "ReduceGuaranteedAmount",
            "Parameters": [
               {
                  "Name": "OrderNumber",
                  "Value": "testorder 123123"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

JSON

copy
{
   "Key": "DCEF7CD4B8424C7589E243F6D3C3xxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2018-10-18T13:37:57"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "paymentguarantee",
   "IsTest": true,
   "ConsumerMessage": null
}