Payment capture API

This page describes an optional step in the direct API integration process. It presents alternatives to a checkout integration where a payment can be set up using the programmatic API.

In this system, all payments are Order centric. An order is a list of items you intend to purchase. To pay for an order, you require a payment token. A payment token is a single-use, time limited identifier that represents the payment of a specific amount and currency.

There are several ways to create a Payment Token, and they may represent a number of financing options including full payments, subscriptions or payment plans.

The default way of generating payment tokens is to use the checkout integration, which provides a PCI-compliant user interface for generating payment tokens that represent either full payments or pay plans. This page documents the alternative programmatic API.

Payment Sources

All financing options require an underlying funding mechanism. We refer to these as payment sources. Typically, in an e-commerce environment, these will be Debit and or Credit cards, but they can also be alternate mechanisms such as bank accounts or money transfers.

For any reusable payment source, we provide a payment sources API that captures the details of that payment source and provides an identifier paymentSourceId that can be used as a proxy in future payments. This API captures raw funding details such as credit card numbers.

Supported payment sources

Currently only credit and debit cards can be saved as re-usable payment sources. In future support for other sources will be added.

A special case regarding payment sources are bank transfers since no source is required because the payment is initiated completely on the customer side.
In the case of orders paid via bank transfer we have to make sure we can reconcile incoming credits with payment-pending orders, the way that works is by assigning a reference number to the order and asking the customer to provide said reference number when they perform the transfer using their banking app. On the API integration side the relevant endpoint are:

• Create pay plan to specify a reference or get an auto-generated one.
• Create payment token ( CreateBankTransferToken body option) to specify a reference or get an auto-generated one in the context of a pay-in-full.
• Pay for an order ( PayByBankTransfer body option) to use the obtained payment token (for a plan or pay-in-full).

Pay in full API

As described above to pay for an order you require a payment token. One way to create a token is to use the tokens API. This API takes the details of the funding source directly or a previously saved funding source (created using the payment source API) to create a payment token.

Pay plan API

The pay plan API provides a second mechanism to create a payment token. Pay plans, and their corresponding payment tokens can only be created for existing customers that have successfully undergone KYC checks.

Creating a pay plan

1. If the customer doesn't exist in the system, or if you wish to update the details of an existing customer, you can use the Upsert Customer endpoint. There are variants on this endpoint for B2B and B2C customers.
2. See the KYC API Integration guide for how to perform KYC on the customer.
3. Create a pay plan offer . This is where you specify the pay plan variant, pay plan amount, and what the customer wishes to pay up front. The call performs an eligibility check on the customer determining if the system is willing to extend a loan for the requested amount. There are three possible outcomes
   1. The request is accepted as is
   2. A counter-offer is made typically where some portion of the plan needs to be paid up-front
   3. The request is rejected outright. From the time the offer is made, you have 10 minutes to create the pay plan after which you need to request a new offer.
4. Create a pay plan from the offer generated in the previous step and a payment source identifier. See the Supported payment sources section below for options on selecting a payment source. If successful, this you provide you with a payment token you can use to pay for the order in the final step.
5. Create an order indicating details of what the customer is purchasing, customer details and billing and shipping address.
6. Pay order is where we link the payment token to the order and the initial payment, if any, is performed to complete the purchase. Make sure you read the Error Handling page as you will need to add some logic to handle a 3DS challenge.