Guides
StatusPlazaCreate Account

Requests

Suggest Edits

PayPerEmail Service


1. Introduction

The PayPerEmail service allows you to send an email to a customer with a payment invitation link. Upon clicking the link, the customer can choose from various payment methods or proceed with a preselected method. You can either configure Buckaroo to send the email with a custom template or send the email yourself using the link provided by the Buckaroo Payment Engine.


2. Requirements

  • Service Subscription: The PayPerEmail service requires an additional service subscription that supports the Pay action, as it does not process payments directly.

3. Workflow

  1. Request Submission: The merchant sends a PayPerEmail request to the Buckaroo Payment Engine (BPE) transaction gateway.
  2. Response and Push Notification: The gateway processes the request, sends a response to the merchant, and a transaction push notification with the transaction status.
  3. Email Sending:
    • If configured, Buckaroo sends the email with the payment link.
    • Alternatively, the merchant sends the email using the provided link.
  4. Payment Process:
    • The customer clicks the link and is taken to the payment page to complete the transaction.
    • After completion, the customer is redirected back to the merchant’s website with transaction details.
    • A transaction push notification is also sent to the merchant with transaction details.

4. Single PayPerEmail, Multiple Transactions

  • A PayPerEmail transaction triggers at least one transaction, namely the PayPerEmail transaction.
  • When the customer follows the payment link and initiates the payment, a new transaction is created.
  • Once the payment is successful, the PayPerEmail transaction is marked as "Succeeded".
  • Push notifications are sent for all involved transactions.

📘

Note:

Some payment methods (e.g., direct debit, credit card) can be reversed, affecting the associated transactions' status.


5. Service Code and Actions

  • Service Code: payperemail
  • Supported Action: paymentinvitation – This action sends an invitation to the consumer to make a payment.

6. PaymentInvitation Action

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.

Payment Invitation Request

Parameters

ParameterTypeRequiredRecommendedDescription
CustomerGenderDecimalYesGender of the customer, possible values: 1: Male, 2: Female, 0: Unknown, 9: Not applicable.
CustomerEmailStringRequired when MerchantSendsEmail = TrueThe e-mail address of the customer.
CustomerFirstNameStringYesThe first name of the customer.
CustomerLastNameStringYesThe last name of the customer.
MerchantSendsEmailBooleanFalse: 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.
ExpirationDateStringThe expiration date (dd-mm-yyyy) 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.)
PaymentMethodsAllowedStringA 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.

Example Request

{
  "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": "[email protected]"
          },
          {
            "Name": "CustomerFirstName",
            "Value": "John"
          },
          {
            "Name": "CustomerLastName",
            "Value": "Smith"
          }
        ]
      }
    ]
  }
}

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


Parameters

ParameterTypeRequiredRecommendedDescription
PayLinkStringYesThe URL where the customer can complete the payment for the PayPerEmail.
ExpirationDateStringYesIf no expiration date is given in the request, the default is one year.

Example Response

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

8. PaymentInvitation Push

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.


Parameters

ParameterTypeRequiredRecommendedDescription
PayLinkStringYesThe URL where the customer can complete the payment for the PayPerEmail.
ExpirationDateStringYesIf no expiration date is given in the request, the default is one year.

Example Push

{
  "Transaction": {
    "Key": "F996EE747ECD43CDA8851C5F83XXXXXX",
    "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 success status:

Example Success Push

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

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

9.1 Uploading Your Attachments

Your attachment needs 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 are available for use. Please note: attachments are only available for 2 weeks; after 2 weeks, attachments will be removed.

Attachment Request

Parameters

ParameterTypeRequiredRecommendedDescription
attachmentStringYesFile name of the attachment. Needs to be a PDF file.

Example Attachment Request

{
   "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": "[email protected]"
               },
               {
                  "Name": "CustomerFirstName",
                  "Value": "John"
               },
               {
                  "Name": "CustomerLastName",
                  "Value": "Smith"
               },
               {
                  "Name": "attachment",
                  "GroupType": "",
                  "GroupID": "1",
                  "Value": "bijlage1.pdf"
               },
               {
                  "Name": "attachment",
                  "GroupType": "",
                  "GroupID": "2",
                  "Value": "bijlage2.pdf"
               }
            ]
         }
      ]
   }
}

Updated 3 months ago