General
1.1 Introduction
The PayPerEmail service can be used to send an email to a customer, inviting the customerto pay by following a hyperlink in the email. Following the link, the customer can bepresented with a choice of different payment methods, or a payment method can bepreselected for the customer.Different scenarios can be created. It’s possible to have Buckaroo send the email for you,in which case it is possible to configure a custom email template in the Buckaroo PaymentPlaza. Another option is to send the email yourself, in which case the link to which to sendthe customer will be returned by the Buckaroo Payment Engine.
1.2 Requirements
The PayPerEmail service is special in that it does not actually processes payments. Anadditional service subscription is needed, for a service that supports the Pay action.
1.3 Work Flow
The merchant starts by sending the request for a PayPerEmail to a BPE transactiongateway. The gateway processes the request and sends a response to the merchant.Additionally, a transaction push is sent to the merchant as well (Both contain the currentstatus of the transaction). Next the email is sent. Depending on whether the merchanttold the BPE to send an email or not, either the merchant or the BPE sends an email tothe customer, containing a paylink. When the consumer clicks on this link, he will be takento a page where the transaction can be completed. After the customer finishes on this page, the customer is redirected back to the merchant website and the transaction detail are sent along with the consumer. In parallel, a transaction push is also sent to the merchant, also containing the transaction details.
1.4 A Single PayPerEmail, Multiple Transactions
A PayPerEmail results in at least 1 transaction, namely the PayPerEmail 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 PayPerEmail transaction will be given the status Succeeded. A transaction push will then be given on all transactions involved (So a push on the chosen payment method transaction and a push on the PayPerEmail transaction)Please note: Certain payment methods (for example direct debit and credit card) can be reversed. If these payment methods are used for paying the PayPerEmail, the PayPerEmail transaction can have a succeeded status, but the associated payment will have been reversed (A reversal payment and transaction will have been created).
2. Servicecode and Actions
To specify the PayPerEmail service, use the following service code: payperemail. This service supports the following action: paymentinvitation. With this action you can sent an invitation to a consumer to invite him/her to pay.
Paymentinvitation
The paymentinvitation action is the only action provided by the PayPerEmail service, it is also the default action. The action is used to register a payment invitation and 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
|
CustomerGender
decimal
|
Required
Gender of the customer, possible values: 1: Male, 2: Female, 0: Unknown, 9: Not applicable. |
|
CustomerEmail
string
|
Required
The e-mail address of the customer. |
|
CustomerFirstName
string
|
Required
The first name of the customer. |
|
CustomerLastName
string
|
Required
The last name of the customer. |
|
MerchantSendsEmail
string
|
Boolean value. False: Buckaroo will send the e-mail to the customer. True: Buckaroo will not send the e-mail and will only provide the paylink in the response. Default value is false. |
|
ExpirationDate
string
|
The expiration date (dd-mm-yyy) for the paylink. From this date onwards, the paylink will no longer work. (Please note that if a ‘delayed’ payment has been chosen (like bank transfer) on the paylink page before this expiration date, the payment for that payment can still arrive and be accepted. |
|
PaymentMethodsAllowed
string
|
A comma separated list of service codes specifying which services (that support the Pay action) can be used to pay the PayPerEmail with. 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. If no service code is provided, all services the merchant has a valid subscription for are offered to the customer. Please note: if you are sending the service Credit Management in the request as well, this parameter won't work. Instead you can use the "AllowedServices" and "AllowedServicesAfterDueDate" parameters within the Credit Management service. See the Credit Management documentation for more information. |
JSON
{
"Currency": "EUR",
"AmountDebit": 10.00,
"Invoice": "testinvoice 123",
"Services": {
"ServiceList": [
{
"Name": "payperemail",
"Action": "PaymentInvitation",
"Parameters": [
{
"Name": "customergender",
"Value": "1"
},
{
"Name": "MerchantSendsEmail",
"Value": "false"
},
{
"Name": "ExpirationDate",
"Value": "2017-10-01"
},
{
"Name": "PaymentMethodsAllowed",
"Value": "ideal,mastercard,paypal"
},
{
"Name": "Attachment",
"Value": ""
},
{
"Name": "CustomerEmail",
"Value": "johnsmith@gmail.com"
},
{
"Name": "CustomerFirstName",
"Value": "John"
},
{
"Name": "CustomerLastName",
"Value": "Smith"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
If the request has a valid structure and a valid signature, a transaction will be created in the Payment Engine and a response will be returned. In this case, a pay link will be returned. This link can then be forwarded to the customer per email.
|
PayLink
string
|
The URL where the customer can complete the payment for the PayPerEmail. |
|
ExpirationDate
string
|
If no expiration date is given in the request, the default is one year. |
JSON
{
"Key": "DB65C22E81EE4409B27A60A6C2XXXXXX",
"Status": {
"Code": {
"Code": 792,
"Description": "Waiting for consumer"
},
"SubCode": null,
"DateTime": "2017-05-18T11:45:44+02:00"
},
"RequiredAction": null,
"Services": [
{
"Name": "payperemail",
"Action": null,
"Parameters": [
{
"Name": "PayLink",
"Value": "https://testcheckout.buckaroo.nl/html/?brq_paydirect_trx=DB65C22E81EE4409B27A60A6C2XXXXXX"
},
{
"Name": "ExpirationDate",
"Value": "2017-10-01"
}
]
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"Invoice": "testinvoice 123",
"ServiceCode": "payperemail",
"IsTest": true,
"Currency": "EUR",
"AmountDebit": 10,
"TransactionType": "I100",
"MutationType": 3,
"RelatedTransactions": null,
"ConsumerMessage": {
"MustRead": false,
"CultureName": "en-US",
"Title": null,
"PlainText": "An invitation to pay has been sent to your e-mail address.",
"HtmlText": null
},
"Order": null,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": "John Smith",
"PayerHash": null,
"PaymentKey": null
}Push
JSON push response
The initial transaction status will be 'pending', which will be pushed first. When the customer uses the paylink to complete the payment, a transaction is created for the chosen service. For more information about these transactions, please refer to the implementation manual for their respective service.
|
PayLink
string
|
The URL where the customer can complete the payment for the PayPerEmail. |
|
ExpirationDate
string
|
If no expiration date is given in the request, the default is one year. |
JSON
{
"Transaction": {
"Key": "DB65C22E81EE4409B27A60A6C2XXXXXX",
"Invoice": "testinvoice 123",
"ServiceCode": "payperemail",
"Status": {
"Code": {
"Code": 792,
"Description": "Waiting for consumer"
},
"SubCode": null,
"DateTime": "2017-05-18T11:45:44"
},
"IsTest": true,
"Order": null,
"Currency": "EUR",
"AmountDebit": 10,
"TransactionType": "I100",
"Services": [
{
"Name": "payperemail",
"Action": null,
"Parameters": [
{
"Name": "PayLink",
"Value": "https://testcheckout.buckaroo.nl/html/?brq_paydirect_trx=DB65C22E81EE4409B27A60A6C2XXXXXX"
},
{
"Name": "ExpirationDate",
"Value": "2017-10-01"
}
],
"VersionAsProperty": 1
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"MutationType": 3,
"RelatedTransactions": null,
"IsCancelable": true,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": "John Smith",
"PayerHash": null,
"PaymentKey": null
}
}
Once the payment has been fulfilled (for example with iDEAL),
a new push response will follow with a succes status:
{
"Transaction": {
"Key": "8E61753006BC468CB3349011EE19Cxxx",
"Invoice": "testinvoice 1235",
"ServiceCode": "payperemail",
"Status": {
"Code": {
"Code": 190,
"Description": "Succes"
},
"SubCode": {
"Code": "S001",
"Description": "Transactie succesvol uitgevoerd"
},
"DateTime": "2018-03-09T12:19:37"
},
"IsTest": true,
"Order": null,
"Currency": "EUR",
"AmountDebit": 10,
"TransactionType": "I100",
"Services": [
{
"Name": "payperemail",
"Action": null,
"Parameters": [
{
"Name": "PayLink",
"Value": "https://testcheckout.buckaroo.nl/html/?brq_paydirect_trx=8E61753006BC468CB3349011EE19Cxxx"
},
{
"Name": "ExpirationDate",
"Value": "2019-10-01"
}
],
"VersionAsProperty": 1
},
{
"Name": "ideal",
"Action": null,
"Parameters": [
{
"Name": "consumerIssuer",
"Value": "ABN Amro Bank"
},
{
"Name": "transactionId",
"Value": "0000000000000001"
},
{
"Name": "consumerName",
"Value": "J. de Tèster"
},
{
"Name": "consumerIBAN",
"Value": "NL44RABO0123456789"
},
{
"Name": "consumerBIC",
"Value": "RABONL2U"
}
],
"VersionAsProperty": 2
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"MutationType": 3,
"RelatedTransactions": null,
"IsCancelable": false,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": "John Smith",
"PayerHash": "xxxxxxxxxxxxxxxxxxxxx",
"PaymentKey": "593EA66D43414C428BBFE20391C8Exxx"
}
}Attachment
3. Attachments
It is possible to let the Payment Engine send emails that include attachment. However, the attachment must first be uploaded to the Buckaroo SFTP server. Please contact your sales contact for information about our SFTP service. If an attachment is not available at the time of requesting a PayPerEmail, the PaymentInvitation request will fail.
3.1 Uploading your attachments
Your attachment need to be uploaded in the subfolder of your sftp home folder: ~/uploads/attachments/
At this time, only PDF files are allowed to be uploaded. There is a maximum file size of 300kB and all files need to be virus free. After your files have been uploaded, allow at least 30 minutes for us to verify your files conform to our guidelines. Once the attachments folder is empty, your files will have been processed and is available for use. Please note: attachments are only available for 2 weeks, after 2 weeks, attachments will be removed.
Request
JSON gateway request
To have the Payment Engine send an email with attachment, you perform a normal PaymentInvitation request, but this time you add an additional request variable for each attachment that needs to be included. See example request. If multiple attachments need to be included with the same email, then each attachment need to have a unique number.
|
attachment
string
|
Required
File name of the attachment. Needs to be a PDF file. |
JSON
{
"Currency": "EUR",
"AmountDebit": 10,
"Invoice": "testinvoice 123",
"Services": {
"ServiceList": [
{
"Name": "payperemail",
"Action": "PaymentInvitation",
"Parameters": [
{
"Name": "customergender",
"Value": "1"
},
{
"Name": "MerchantSendsEmail",
"Value": "false"
},
{
"Name": "ExpirationDate",
"Value": "2019-10-01"
},
{
"Name": "PaymentMethodsAllowed",
"Value": "ideal,mastercard,paypal"
},
{
"Name": "Attachment",
"Value": ""
},
{
"Name": "CustomerEmail",
"Value": "johnsmith@gmail.com"
},
{
"Name": "CustomerFirstName",
"Value": "John"
},
{
"Name": "CustomerLastName",
"Value": "Smith"
},
{
"Name": "attachment",
"GroupType": "",
"GroupID": "1",
"Value": "bijlage1.pdf"
},
{
"Name": "attachment",
"GroupType": "",
"GroupID": "2",
"Value": "bijlage2.pdf"
}
]
}
]
}
}