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.
Request
JSON gateway request
|
InvoiceDate
datetime
|
Required
The (expected) delivery date of the invoice. |
|
DateDue
datetime
|
Required
The due date by which the customer must have paid. This should be InvoiceDate + 14 days. |
|
PaymentMethodsAllowed
string
|
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
string
|
Required
The customer ID , giving a unique ID to the customer for the merchant. |
|
CustomerTitle
string
|
The title to use for a customer. |
|
CustomerInitials
string
|
Required
The initials for the customer (first letter of each first name). |
|
CustomerFirstName
string
|
Required
The first name of the customer. |
|
CustomerLastNamePrefix
string
|
The prefix for the surname of the customer. |
|
CustomerLastName
string
|
Required
The surname of the customer (without any prefixes) |
|
CustomerGender
decimal
|
Required
The customer gender. Possible values: 1: Male 2: Female |
|
CustomerBirthDate
datetime
|
Required
The date of birth of the customer. |
|
CustomerEmail
string
|
Required
The e-mail address of the customer. |
|
PhoneNumber
string
|
Required
The phone number for the customer’s landline. Either PhoneNumber or MobilePhoneNumber (or both) must be supplied. |
|
MobilePhoneNumber
string
|
Required
The phone number for the customer’s cellular. Either PhoneNumber or MobilePhoneNumber (or both) must be supplied. |
|
FaxNumber
string
|
The fax number for the customer. |
|
CustomerIBAN
string
|
Required
The bank account number of the customer. This must be a SEPA IBAN number. |
|
AddressType
string
|
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
string
|
Required
GroupType: "address". The street name of the address. |
|
HouseNumber
decimal
|
Required
GroupType: "address". The house number for the address.. |
|
HouseNumberSuffix
string
|
GroupType: "address". The house number suffix for the address. |
|
ZipCode
string
|
Required
GroupType: "address". The zipcode for the address. |
|
City
string
|
Required
GroupType: "address". The city for the address. |
|
Country
string
|
Required
GroupType: "address". The country belonging to the address. |
|
clientip
string
|
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
{
"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 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
|
PayLink
string
|
This will contain a link to a webpage where the customer can pay for the transaction. This link is also used in the emails sent to the customer. |
JSON
{
"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
|
PayLink
string
|
This will contain a link to a webpage where the customer can pay for the transaction. This link is also used in the emails sent to the customer. |
JSON
{
"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.
Request
JSON gateway request
|
OrderDate
datetime
|
Required
The date of the order. |
|
Order
string
|
Required
Order number. Note: This is a basic parameter, not a service parameter. |
|
AmountVat
decimal
|
Required
The VAT amount for the transaction. |
|
OrderDate
datetime
|
Required
The date of the order. |
|
CustomerCode
string
|
Required
The customer ID, giving a unique ID to the customer for the merchant. |
|
CustomerTitle
string
|
The title to use for a customer. |
|
CustomerInitials
string
|
Required
The initials for the customer (first letter of each first name). |
|
CustomerFirstName
string
|
Required
The first name of the customer. |
|
CustomerLastNamePrefix
string
|
The prefix for the surname of the customer. |
|
CustomerLastName
string
|
Required
The last name of the customer (without any prefixes). |
|
CustomerGender
string
|
Required
The customer gender. Possible values: 1: Male 2: Female |
|
CustomerBirthDate
datetime
|
Required
The date of birth of the customer. |
|
CustomerEmail
string
|
Required
The email address of the customer. |
|
PhoneNumber
string
|
Required
The phone number for the customer’s landline. Either PhoneNumber or MobilePhoneNumber (or both) must be supplied. |
|
MobilePhoneNumber
string
|
Required
The phone number for the customer’s cellular. Either PhoneNumber or MobilePhoneNumber (or both) must be supplied. |
|
FaxNumber
string
|
The fax number for the customer. |
|
CustomerIBAN
string
|
Required
The bank account number of the customer. This must be a SEPA IBAN number. |
|
AddressType
string
|
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
string
|
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
string
|
Required
GroupType: "address". The house number for an address. |
|
HouseNumberSuffix
string
|
GroupType: "address". The house number suffix for an address. |
|
ZipCode
string
|
Required
GroupType: "address". The zipcode for an address. |
|
City
string
|
Required
GroupType: "address". The city for an address. |
|
State
string
|
The state for an address. |
|
Country
string
|
Required
GroupType: "address". The country belonging to an address. |
JSON
{
"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 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
|
OrderKey
string
|
Unique key to identify the order. |
JSON
{
"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
string
|
Unique key to identify the order |
JSON
{
"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.
Request
JSON gateway request
|
InvoiceDate
datetime
|
Required
The (expected delivery) date of the invoice |
|
CustomerCode
string
|
Required
The customer ID , giving a unique ID to the customer for the merchant. |
|
PaymentMethodsAllowed
string
|
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
decimal
|
Required
The VAT amount for the transaction |
|
DateDue
string
|
Required
The due date by which the customer must have paid. This should be InvoiceDate + 14 days. |
JSON
{
"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 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
|
PayLink
string
|
This will contain a link to a webpage where the customer can pay for the transaction. This link is also used in the emails sent to the customer. |
JSON
{
"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
|
PayLink
string
|
This will contain a link to a webpage where the customer can pay for the transaction. This link is also used in the emails sent to the customer. |
JSON
{
"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.
Request
JSON gateway request
|
OrderNumber
string
|
Required
The order number of the original order |
|
Currency
string
|
Required
Currency. Note: This is a basic parameter, not a service parameter. |
|
Amountcredit
string
|
Required
The reduced amount. Note: This is a basic paramter, not a service parameter. |
JSON
{
"Currency": "EUR",
"Amountcredit": 1.00,
"Services": {
"ServiceList": [
{
"Name": "paymentguarantee",
"Action": "ReduceGuaranteedAmount",
"Parameters": [
{
"Name": "OrderNumber",
"Value": "testorder 123123"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
JSON
{
"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
}