General Concepts
To fully leverage the power of the payments API, the following concepts should be understood.
Primary and Secondary Transactions
A primary transaction (performed via this endpoint or via our hosted solutions) is a new initiating payment transaction. A few examples of different primary transactions would be:
- A standard one-time transaction (sale) is made when someone purchases their shopping at the supermarket
- A 'pre-authorisation' transaction is made when a person uses the pay-at-pump gas station before any payment is taken
A secondary transaction (performed using either the transaction id or the order id) is one that serves to follow up a previous primary transaction. A few examples of different secondary transactions would be:
- A 'void' is performed on a primary transaction to cancel the payment on the same day before any money is actually moved
- A 'return' is performed on a primary transaction to refund the payment on a following day
- A 'completion' is made to a primary 'pre-authorisation' when the person completes their use of the pay-at-pump gas station
PCI DSS
The Payment Card Industry Data Security Standard (PCI DSS) is an information security standard for organisations that handle payment information such as credit card details.
Please note that if you plan to collect your customer's card details within your environment and send it to our API, you must ensure that your system components are PCI DSS compliant. This is particularly important if you plan to store any of the information.
To avoid the need to worry about PCI DSS, we recommend taking a look at our Checkout product which is a hosted solution for processing payments without you needing to process or store payment information.
Orders
Orders are a concept that create a through-line for the lifetime of a payment, grouping relating primary and secondary transactions. When using the payment API, it is useful to keep track of orders using the order inquiry endpoint to ensure that the full picture of a payment can be recorded.
In the pay-at-pump example above, retrieving the order would include reference to both the primary pre-auth transaction as well as the secondary pre-auth completion transaction
Payment Methods
The payment method (also known as payment instrument) is the item used to make the payment. This might be a debit card, a digital wallet, or a SEPA bank transfer.
In the Payments API this is controlled by the requestType (detailed above) as well as the resulting information provided as part of the polymorphic model.
For more detail on the different types of instruments supported by our platform, see the Payment Methods
Request Type
The requestType field is used to define the high-level nature of the payment, such as the type of transaction (pre-auth, sale etc.) and the type of instrument used (card, wallet etc.). This field is used in most POST requests as part of the Payment API such as Submit a Primary Transaction.
The requestType field has an allowable list of values, which also defines which additional fields are required as part of the payment. See the table below for some detail on the different values for primary transaction requestType:
| requestType | Payment Scenario |
|---|---|
PaymentCardSaleTransaction | Execute a normal customer payment transaction with a credit or debit card. |
PaymentCardCreditTransaction | Execute an original credit payment transaction to a customer’s credit or debit card. This means you’ll refund this amount to the customer’s card without a reference to any previous Sale transaction |
PaymentCardPreAuthTransaction | Pre-authorize an amount against a card, for completion at a later point. |
PaymentTerminalSaleTransaction | Initiate a sale transaction from a physical terminal. |
PaymentTerminalPreauthTransaction | Initiate a pre-authorization from a physical terminal. |
PaymentTerminalCreditTransaction | Initiate a naked refund from a physical terminal. |
PaymentTokenSaleTransaction | Execute a normal customer payment transaction with a token generated previously. |
PaymentTokenCreditTransaction | Execute a return to a customer’s credit or debit card using a token generated previously. |
PaymentTokenPreAuthTransaction | Pre-authorise an amount using a token, for completion at a later point. |
SepaSaleTransaction | Take payment from a customer via SEPA. |
SepaCreditTransaction | Take a naked refund from a customer via SEPA. |
WalletSaleTransaction | Execute a normal customer payment transaction with a wallet payment method. |
WalletPreAuthTransaction | Execute a pre-authorization using a Wallet Payment Method. |
ApmSaleTransaction | Initiate a sale transaction via an alternative payment method. |
ApmPreauthTransaction | Initiate a pre-authorization via an alternative payment method. |
And the list of available secondary transaction requestType:
| requestType | Description |
|---|---|
VoidTransaction | Cancel a transaction you submitted earlier the same day |
VoidPreAuthTransactions | Cancel all transaction done under a pre-authorization (same order ID) |
PostAuthTransaction | Complete a pre-authorization Transaction against the same |
ReturnTransaction | Complete a refund against a transaction taken prior to the current day |
PreAuthSecondaryTransaction | Create an incremental or decremental secondary transaction against an existing pre-authorization |
Updated 6 months ago
