This section describes some additional settings that can be applied when creating Payment Sessions.
Authorisation is the process by which the card issuer verifies the cardholder’s payment details and, if there are no reasons to decline (e.g. insufficient funds), reserves the amount for a set period.
An authorised payment can usually be handled in one of two ways:
- Voided: the hold is cancelled and the funds are released back to the cardholder.
- Captured: the funds are submitted for clearing and claimed from the cardholder’s account.
The example shown below demonstrates a Payment Session creation request that will automatically capture funds once the payment is authorised. This is the default behaviour.
{
"amount": 54550,
"currency": "GBP",
"customerEmail": "test@mail.com",
"captureFlow": "Automatic" // Or omit this field entirely as Automatic is the default
}However, for certain business models, it may be preferable, or necessary, to delay capture.
When a payment is authorised but not yet captured, the funds remain in the cardholder’s account. This offers greater flexibility to address scenarios such as fraud, stock issues, or order cancellations.
To create an authorise-only Payment Session, set captureFlow to Manual via the paymentSessionCreate endpoint as shown below:
{
"amount": 54550,
"currency": "GBP",
"customerEmail": "test@mail.com",
"captureFlow": "Manual"
}The duration for which funds remain reserved depends on the card scheme involved. The following table shows how this varies per scheme:
| Card Scheme | Authorization validity |
|---|---|
| Visa | 7 days / 5 days for Merchant-initiated transactions |
| Mastercard | 7 Days |
| American Express | 7 Days |
If the payment is not captured within this timeframe, the authorisation will expire, and the reserved funds will be released back to the cardholder.
- To process an authorise-only payment, you can follow the steps outlined in the Initial Setup guide. Authorising payments does not require any particular SDK configuration.
- To capture an authorised payment, you can follow the steps outlined in the Capture guide.
- To void an authorised payment, you can follow the steps outlined in the Void guide.
Account Verification, also known as zero-value authentication, lets you process a cardholder's details without charging them. This feature is typically used when you need to collect, verify, and store a customer's card details on an initial transaction to charge them at a later date.
You must get consent from the cardholder to store their card on file, regardless of how you intend to use those stored credentials for future transactions.
The first step requires you to set the following fields when creating a Payment Session via the paymentSessionCreate endpoint:
Request Example:
{
... (fields omitted for brevity)
"amount": 0,
"verifyAccount": true
}After setting these fields, you can process the Payment Session by sending the customer's card information through one of our integration methods. If successful, the card details will be securely stored against the customer.
Please Note: 3D-Secure is required for this initial transaction.
To process a Zero-Value Authentication payment, you can follow the steps outlined in this section.
Account-Verification payments requires a specific SDK configuration.
If you want to block or prevent particular payment methods from being used to complete a payment, you can explicitly disable them when creating payment sessions via the paymentSessionCreate endpoint by specifying the settings.paymentMethodOptions field as shown below.
{
"amount": 54550,
"currency": "GBP",
"customerEmail": "test@mail.com",
"settings": {
"paymentMethodOptions": {
"disabled": ["Amex"]
}
}
}The Payment Session created above will ensure that Amex payments are disabled when processing the payment. If the customer attempts to pay with Amex, the payment session will be marked as failed.
This feature is not enabled by default. Please contact support if you want to make use of them.
- To process a payment with specific payment methods disabled, you can follow the steps outlined in the Initial Setup guide. No special SDK configuration is required.
- Additionally, have a look at the error codes on this page to handle scenarios where a customer attempts to use a disabled payment method.
As described in the Fees section, Main Account holders can choose to pass on their Processing Fees to their Sub-Account holders. This means that when a transaction occurs, the fees associated with that transaction can be charged to the Sub-Account holder instead of the Main Account holder.
This feature is not enabled by default. Please contact support if you want to make use of them.
There are various fees associated with processing a payment that can be passed on to Sub-Accounts, depending on the chosen pricing model.
| Fee | Description | Pricing Model |
|---|---|---|
| gatewayFee | Any fixed cost incurred by Ryft for processing the transaction with the payment gateway | Blended, ICC++ |
| processor | The Ryft's processing fee markup | Blended, ICC++ |
| interchange | The fee paid to the card issuer for each transaction within the card network | ICC++ |
| network | The fee paid to the card scheme (e.g. Visa or Mastercard) for using their network | ICC++ |
| miscPassThrough | The various miscellaneous fees that are passed through from third parties | ICC++ |
| combined | An aggregate field which refers to all of the above. This can be used to request that all fees be charged to a given sub account | ICC++ |
When using the Platform Fee model, you can choose to pass on the Processing fees to the Sub-Account by setting the paymentSettings.platform.paymentFees.<any_of_the_above_fee_type>.bookTo.<sub_account_id> field when creating a Payment Session as shown below:
{
// Same as previous Platform Fee example
"amount": 2050,
"currency": "GBP",
"customerEmail": "customer@mail.com",
"platformFee": 205,
// Pass Processing Fees to Sub-Account
{
"paymentSettings": {
"platform": {
"paymentFees": {
"combined": {"bookTo": "ac_XXXXXXX"} // Sub-Account ID
}
}
}
}In the example above, any Processing fee (set by the combined keyword) will be passed on to the Sub-Account, which will receive the total amount for their food order (£20.50), minus the Platform Fee (£2.05), minus any Processing Fee.
With this set-up, the Main Account will receive the total amount of Platform Fee of £2.05 without any other deductions.
When using the Split Payment model, you can choose to pass on the Processing fees to the Sub-Account(s) by setting the paymentSettings.platform.paymentFees.<any_of_the_above_fee_type>.bookTo.<sub_account_id> field when creating a Payment Session as shown below:
{
// Same as previous Split Payment example
"amount": 7100,
"currency": "GBP",
"customerEmail": "customer@mail.com",
"splits": {
"items": [
{
"accountId": "ac_123456789", // Restaurant A
"amount": 2800,
"fee": {"amount": 280}
},
{
"accountId": "ac_246810121", // Restaurant B
"amount": 2900,
"fee": {"amount": 290}
},
{
"accountId": "ac_369121518", // Restaurant C
"amount": 1400,
"fee": {"amount": 140}
}
]
},
// Pass Processing Fees to Sub-Account
{
"paymentSettings": {
"platform": {
"paymentFees": {
"combined": {"bookTo": "ac_123456789"} // Restaurant A
}
}
}
}
}In the example above, the processor fee will be passed on to the Sub-Account related to Restaurant A, which will receive the total amount for their food order (£14.00), minus the Platform Fee (£1.40), minus any Processing Fee.
With this set-up, the Main Account will receive the total amount of Platform Fee of £7.10 without any other deductions.
To process a payment with Processing Fees passed to Sub-Accounts, no special SDK configuration is required. You can follow the steps outlined in the Process Payments guide.