PSP integration guide

1.Introduction

The purpose of this guide is to give an overview of:

  • what AfterPay is and how payment works for an end-user
  • how payments are processed
  • the functional requirements for integrating AfterPay in your platform

Complete technical requirements and specifications can be found in the API documentation. References to the API documentation can be found in this guide when relevant.

2.How does it work

AfterPay is an post-delivery payment method. You don’t need a creditcard, account or e-reader to use AfterPay.

In general, this is how AfterPay can be used for payments:

  1. the user selects AfterPay as the payment method in the checkout process
  2. on submission, a real-time risk check is done, based on the entered information
  3. if payment is accepted, the user goes to the standard succces page and the order is placed
  4. after receiving the order, the user receives an invoice by e-mail

For more information, please see the explanation on the AfterPay website.

3.Payment Methods

Currently, AfterPay supports these payment methods:

Method Description
B2C invoice NL AfterPay for Dutch consumers
B2C invoice BE AfterPay for Belgium consumers
B2B invoice NL AfterPay for Dutch companies
B2C direct debit NL AfterPay for Dutch consumers (Direct Debit)

4.Payment processing

This section covers the process of an AfterPay payment.

4.1.From order to invoice

Technically, AfterPay is similar to the creditcard payment model.
This is how an AfterPay payment is processed:

1. Authorization
After placing the order, an authorization request is sent to AfterPay, using the data from the checkout. The AfterPay webservice checks if the data sent is correctly formatted and complete. If so, then it does a risk check using that data. If the payment request is accepted, the total amount of the order is reserved and can be invoiced.

The API documentation has an overview of all possible responses and how to process them.

2. Capture
After the order has been shipped, the reserved amount can be captured fully or partially. The captured amount is then set to be invoiced.

3. Invoicing
Within a few days, AfterPay sends an invoice by e-mail for the captured amount.

 

4.2.Order maintenance operations

The webservice also supports other order maintenance operations. For example, a cancel can be used if the the complete order is cancelled before capture/invoicing. AfterPay will not send an invoice.

In case of a full or partial return, a full or partial refund can be used. AfterPay will send an update by e-mail, stating the remaining amount to be paid.

The API documentation has a complete description of all order maintenance operations. It also provides an overview of use-cases, which describes how to use the operations in specific scenario’s.

4.3.Request and response flow

All requests from and responses to the merchant go through the PSP. This applies to both authorization and order maintenance operations.Presentatie1

5.Requirements

This section describes the most important requirements in order to integrate AfterPay in your platform.

5.1.Support all operations

Your platform and backoffice needs to support all operations of the AfterPay webservices, including the order maintenance operations. This offers the flexibility to merchants to use AfterPay in their processes/systems and is the only way to handle the different order scenario’s.

5.2.Payment method structure

A merchant can have one or more webshops, each webshop can have one or more payment methods. See the structure below.

Merchant

  • Webshop A
    — Payment method 1
    — Payment method 2
    — Payment method X
  • Webshop B
    — Payment method 1
  • Webshop X
    — Payment method 1
    — Payment method 2
    — Payment method 3

For each payment method, a unique combination is used for authorization:

  • merchant ID
  • portfolio ID
  • portfolio password

Therefore, it should be possible to configure these 3 for each payment method separately, per webshop, in your platform/backoffice.

5.3.Show validation errors to end-users

In case of a validation error, AfterPay sends a specific response containing the error type and a user friendly message in the field . This message should be visible to the end-user, with the option to change the data and try again.

Of multiple errors occur, all should be listed as provided in the response.

The API documentation has an example of a validation error.

5.4.Show rejection message

In case of a rejection, a generic rejection message should be shown, plus the reason of rejection. The latter is sent in the response of the AfterPay webservice in the field . The API documentation has an example of a rejection response.

Below you will find the text to be used, for both Dutch and Belgium payment methods.

Dutch payment methods (B2C invoice NL, B2B invoice NL, B2C direct debit NL):
Het spijt ons u te moeten mededelen dat uw aanvraag om uw bestelling achteraf te betalen op dit moment niet door AfterPay wordt geaccepteerd. De reden hiervoor is: . Voor vragen over uw afwijzing kunt u contact opnemen met de Klantenservice van AfterPay. Wij adviseren u voor een andere betaalmethode te kiezen om alsnog de betaling van uw bestelling af te ronden.

Belgium payment methods (B2C invoice BE):
Het spijt ons u te moeten mededelen dat uw aanvraag om uw bestelling achteraf te betalen op dit moment niet door AfterPay wordt geaccepteerd. De reden hiervoor is: . Voor vragen over uw afwijzing kunt u contact opnemen met de Klantenservice van AfterPay. Wij adviseren u voor een andere betaalmethode te kiezen om alsnog de betaling van uw bestelling af te ronden.

 

Note: please link to the contact pages, using the links in the text.

5.5.AfterPay terms and conditions

Legally, an end-user has to agree with the AfterPay terms and conditions. Below you will find the links to the relevant T&C per method. A link to the T&C should be shown in the checkout process, preferably with a checkbox. This could be when choosing AfterPay in the checkout, or on a separate payment page, for example.

Method URL
B2C invoice NL https://www.afterpay.nl/nl/algemeen/betalen-met-afterpay/betalingsvoorwaarden
B2C invoice BE https://www.afterpay.be/be/footer/betalen-met-afterpay/betalingsvoorwaarden
B2B invoice NL https://www.afterpay.nl/nl/algemeen/zakelijke-partners/betalingsvoorwaarden-zakelijk
B2C direct debit NL https://www.afterpay.nl/nl/algemeen/betalen-met-afterpay/betalingsvoorwaarden

5.6.Webshop order- and invoicenumber leading

In order to avoid confusion in communications between all parties (PSP, AfterPay and merchant) and to be able to quickly find orders and invoices, it is important that all parties use the same order- and invoicenumbers.

Therefore, the order- and invoicenumber of the webshop should be leading in all transactions passing through your platform to AfterPay.

PSP reference
If you need to use a unique identifier/reference generated by your platform, do not change or use the order- or invoice fields. Instead, you can use the PTR (Parent Transaction Reference) or TR(Transaction Reference) fields.

Please see the overview of authorization and order maintenance objects in the API documentation for more info on these fields.

5.7.Auto-capture option

Most merchants can deliver the majority of orders within a few days. For these merchants, a combined authorization and capture is a huge time-saver. They no longer have to do the capture/invoicing for each order manually.

So, please offer an ‘auto-capture’ option in your backoffice and/or plugins. That way, capture is done automatically, right after authorization.

Please do make sure the order- and invoicenumber of the merchant are used for authorization and capture.

5.8.Payment method names

Backoffice
In your backoffice/plugins, please refer to the payment methods in line with the table below. The idea is that a mechant can clearly distinguish the different methods.

Method Description
B2C invoice NL AfterPay for Dutch consumers
B2C invoice BE AfterPay for Belgium consumers
B2B invoice NL AfterPay for Dutch companies
B2C direct debit NL AfterPay for Dutch consumers (Direct Debit)

Webshop / HPP
In the webshop of the merchant or on a separate payment page, please use this name always:

AfterPay – achteraf betalen

Usually, payment options are filtered based on country or type (b2c/b2b), which results in AfterPay shown with just this name.

However, if different methods are shown together, please use the following names:

Method Name in checkout/external page
B2C invoice NL AfterPay – achteraf betalen
B2C invoice BE AfterPay – achteraf betalen (Belgie)
B2B invoice NL AfterPay – achteraf betalen (B2B)
B2C direct debit NL AfterPay – achteraf betalen (Eenmalige machtiging)

5.9.Ask for additional info, but only if needed

AfterPay needs a fixed set of fields in order to do a risk check. The fields per payment method can be found here.

However, not all merchants have all fields in their checkout. For example, date of birth or gender are not always standard.

Forcing a merchant to ask for this extra personal info in their shop by default for all orders, regardless of payment method does not help conversion.

So, enable the merchant to ask for this information only when needed, for example when choosing AfterPay as a payment method (or in an separate payment page).

If a merchant does have fields in place for gender, DOB etc. then do not make an end-user give that information again.

5.10.Make webshop data non-editable in HPP

If you use an HPP (Hosted Payment Page) or any other external page, make sure that any information that has been passed from the webshop to your platform/the HPP cannot be changed.

This is needed to prevent fraud. (we would receive different order information as opposed to how it is registered in on the merchant side)

5.11.Correction line for rounding errors

The AfterPay webservices expects that the sum of all orderlines is equal to the total order amount. If not, payment will fail.

For example:

  • 1x product 1 –  €5,00
  • 2x product 2 –  €3,99
  • 1x product 3 – €2,99
  • shipping – €4,95

The sum is €20,92. The webservice expects this exact amount in the totalorderamount field.

Now, sometimes, due to different tax calculations and settings, rounding errors can occur in the webshop of a merchant. While ideally, this can be corrected by the merchant on their side, this is not always an option or even possible.

To prevent failed payments in these situations, please add a correction line to the request automatically. With this added (positive or negative) correction, the sum always equals the total. A correction line can be sent as an orderline, just like any other. Please see the example request for more details.

5.12.AfterPay service fee

If allowed by contract, merchants may charge an extra fee to their customers for paying with AfterPay. It should be possible for a merchant to set this fee, through either the settings of a plugin/app or in your backoffice.

5.13.Dutch language in feedback to end-user

If an end-user gets feedback, for example in case of a validation error or rejection, the language of the message should always be Dutch.

5.14.Logo usage

Everywhere payment logo’s are used, you need to show the AfterPay logo as well. This could be in check-out (using plugins), external payment page, your backoffice etc.

5.15.Consistent functionality across implementation options

Usually, a PSP provides several options to connect to their platform.

For example:

  • plug-ins for popular platforms like WordPress or Prestashop
  • plug-ins/apps for SaaS platforms like Shopify or Lightspeed
  • API access for direct integration with custom built or other platforms

To provide a consistent, quality experience to both end-users and merchants, it is important that the way AfterPay works is mostly identical across all implementation options.

For merchants, some examples are:

  • set a service fee for AfterPay payments
  • cancel or refund an AfterPay payment (if one plug-in supports it, all should support it)
  • configure AfterPay payment methods in multishop systems, following the structure as outligned in this guide

For end-users, this could be:

  • error handling and showing of messages
  • logo usage
  • Dutch language in all messages

These are just examples, the general idea is to have a consistent experience, not matter how a merchant connects with the PSP.

6.When can I offer AfterPay to my merchants?

You can start connecting merchants for live payments only if:

  • Testing is completed by AfterPay
  • Legal agreements are in place between AfterPay and the PSP
  • The onboarding proces of merchants is agreed upon
  • Relevant instructions and communications are in place for merchants
  • AfterPay has verified and confirmed in writing that all requirements for go-live are met
Stel voor   bewerken