Sign in

v1

latestOpenAPI 3.0.02026-08-0696238481.7 KB
Payments

Create a new payment session

The start of the payment flow. Call this request once the customer has proceeded to checkout. Payment Sessions will auto-expire after several days if you don't take payment via the attempt-payment endpoint.

post/payment-sessions

Headers

Accountstring

The linked accountId (use this when operating on payments related to a linked account)

Request body

amountinteger required

The amount of the sale/purchase in minor digits. Minimum and maximum amounts vary by currency.

currencystring required

The ISO currency code

customerEmailstring nullable

The email address of the customer This is required for a payment to be taken and must be provided either here or when attempting payment. We recommend providing the email here when payment is being taken via your checkout page or the user is logged in, otherwise request it when attempting payment. This can be omitted if you supply a customerId instead, in which case we will use the email stored against the customer. If you don't supply a 'customerId' we will implicitly create a customer using this email

platformFeeinteger nullable

The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the "amount" property Supply this if you also are supplying the "Account" header and want to take a fee from that account

passThroughProcessingFeeboolean nullable

Use this flag to control which account pays our processing fee. Use of this feature is disabled by default, please contact our support team if you wish to use it.

This field is no longer supported. Please refer to the platformSettings.paymentFees field instead.

captureFlow'Automatic' | 'Manual' nullable

By default we will automatically capture payment once the customer authorizes the payment. If you want to manually capture a payment yourself then set this to Manual. Typically this is recommended if you wish to authorize a particular amount from a customer for up to 7 days and then capture the funds once you can fulfil the order.

paymentType'Standard' | 'Unscheduled' | 'MOTO' | 'Recurring' nullable

The type of the payment. Use this to control whether the payment is classified as a Customer-Initiated Transaction (CIT) or Merchant-Initiated Transaction (MIT). (MIT) - customer is not actively participating in the transaction and has instead given consent for you to charge their stored card off session. (CIT) - customer is actively in your checkout flow and is on hand to react to and complete any supplementary steps to complete the payment (e.g. 3DS). CIT values:

  • Standard - A regular one-off e-commerce payment, made by a customer on your website/app

MIT values:

  • Unscheduled (subsequent) - Uses an already stored card on file for a fixed or variable amount that does not occur on a scheduled or regular basis such as recurring payments/subcriptions.

Recurring or Unscheduled are classified as CIT if it is the initial payment in the series and MIT if it is a subsequent (follow up) payment in the series.

MOTO has now been deprecated in favour of the entryMode (MOTO) field.

entryMode'Online' | 'MOTO' nullable

Indicates how the payment method details were (or will be) obtained by the merchant for this payment.

  • Online - when the payment method is collected with the customer present (e.g. an e-commerce payment within a browser)
  • MOTO - when the payment method is collected via mail order (not e-email) or over the phone

MOTO is subject to additional approval, contact us if you require this functionality.

verifyAccountboolean nullable

Set this field to true and amount: 0 to perform an account verification payment (no financial impact on the customer). In this flow, you should have the customer complete the payment on the client. We recommend always using our iOS/Android/Web SDKs to handle any required actions (e.g. 3DS). Note that:

  • CaptureFlow will default to Manual, do not pass Automatic otherwise the request will be rejected.
  • platformFee cannot be provided in your request - sub accounts cannot be charged for these payments.
  • splits cannot be provided in your request - there is no amount to split.
metadataobject nullable

Use this parameter to attach key-value data to the payment. These will be sent with any associated payment events on your webhooks. You can have a maximum of 10 pieces of metadata.

Keys must be between 1 and 30 characters in length.

Values must be between 1 and 250 characters in length.

returnUrlstring nullable

URL to send the customer back to after a redirection (e.g. 3DS). This field is optional and if not specified we will use the URL setup against your account. For Web The URL should use protocol https:// We recommend you include your own query parameters on this URL so you can identify the transaction that the payment relates too, e.g. ?orderId=123. We will append the payment session id onto the URL under param ps.

Example request

{
  "amount": 500,
  "currency": "GBP",
  "customerEmail": "example@mail.com",
  "customerDetails": {
    "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ",
    "firstName": "Isaac",
    "lastName": "Clarke",
    "homePhoneNumber": "+447900000000",
    "mobilePhoneNumber": "+447900000000",
    "metadata": {
      "customerId": "123"
    }
  },
  "platformFee": 50,
  "splits": {
    "items": [
      {
        "accountId": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
        "amount": 50,
        "description": "2 x The Selfish Gene",
        "fee": {
          "amount": 50
        },
        "metadata": {
          "productId": "123",
          "productTitle": "The Selfish Gene"
        }
      }
    ]
  },
  "captureFlow": "Automatic",
  "paymentType": "Standard",
  "entryMode": "Online",
  "previousPayment": {
    "id": "ps_01JW8YG06VVT1AK044C9J1C0YZ"
  },
  "rebillingDetail": {
    "amountVariance": "Fixed",
    "numberOfDaysBetweenPayments": 30,
    "totalNumberOfPayments": 12,
    "currentPaymentNumber": 4,
    "expiry": 1776988800
  },
  "shippingDetails": {
    "address": {
      "firstName": "Fox",
      "lastName": "Mulder",
      "lineOne": "Stonehenge",
      "postalCode": "SP4 7DE",
      "city": "Salisbury",
      "country": "GB"
    },
    "phoneNumber": "+447900000000"
  },
  "orderDetails": {
    "reference": "fffd1682-f82b-43e3-a89b-48d9ad7d55d9",
    "items": [
      {
        "reference": "product123",
        "name": "The Big Gundown (Blu-ray)",
        "quantity": 2,
        "unitPrice": 250,
        "taxAmount": 50,
        "totalAmount": 540,
        "discountAmount": 10
      }
    ]
  },
  "metadata": {
    "orderId": "1",
    "customerId": "123"
  },
  "statementDescriptor": {
    "descriptor": "Ryft Ltd",
    "city": "London"
  },
  "returnUrl": "https://ryftpay.com/checkout?orderId=123",
  "attemptPayment": {
    "paymentMethod": {
      "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ",
      "cvc": "100"
    }
  },
  "paymentSettings": {
    "platform": {
      "paymentFees": {
        "interchange": {
          "bookTo": "ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327"
        },
        "network": {
          "bookTo": "ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327"
        },
        "miscPassThrough": {
          "bookTo": "ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327"
        }
      }
    },
    "threeDs": {
      "challengeIndicator": "NoPreference"
    }
  }
}

Response

payment session successfully created

idstring

The unique identifier for the payment

amountinteger

The amount of the sale/purchase in minor digits

currencystring

The ISO currency code

paymentType'Standard' | 'Unscheduled' | 'MOTO' | 'Recurring' nullable

The type of the payment. Use this to control whether the payment is classified as a Customer-Initiated Transaction (CIT) or Merchant-Initiated Transaction (MIT). (MIT) - customer is not actively participating in the transaction and has instead given consent for you to charge their stored card off session. (CIT) - customer is actively in your checkout flow and is on hand to react to and complete any supplementary steps to complete the payment (e.g. 3DS). CIT values:

  • Standard - A regular one-off e-commerce payment, made by a customer on your website/app

MIT values:

  • Unscheduled - Uses an already stored card on file for a fixed or variable amount that does not occur on a scheduled or regular basis such as recurring payments/subcriptions.

Recurring is classified as CIT if it is the initial payment in the series and MIT if it is a subsequent (follow up) payment in the series. MOTO has now been deprecated in favour of the entryMode (MOTO) field.

entryMode'Online' | 'MOTO' | 'InPerson' nullable

Indicates how the payment method details were (or will be) obtained by the merchant for this payment.

  • Online - when the payment method is collected with the customer present (e.g. an e-commerce payment within a browser)
  • MOTO - when the payment method is collected via mail order (not e-email) or over the phone
  • InPerson - when the payment is collected in-person over a physical medium (such as card terminal)

MOTO is subject to additional approval, contact us if you require this functionality.

customerEmailstring nullable

The email address of the customer

enabledPaymentMethodsstring[]

List of payment method types that can be used to complete payment for this PaymentSession. Card is the default and will allow all card schemes configured on your account (Visa, Mastercard etc.). Apple Pay & Google Pay are classified as Card types and will be displayed provided you have confogured them properly.

platformFeeinteger nullable

The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the "amount" property

status'PendingPayment' | 'PendingAction' | 'Processing' | 'Approved' | 'Captured' | 'Voided'
metadataobject nullable

use this parameter to attach key-value data to the payment. These will be sent with any associated payment events on your webhook.

clientSecretstring nullable

The client secret is used to complete a payment from your frontend. Do NOT store/log/embed anywhere and ensure it is only surfaced on pages served over TSL

lastError'insufficient_funds' | 'declined_do_not_honour' | 'invalid_card_number' | 'cvv2_failure' | 'restricted_card' | 'blacklisted_card' | 'blacklisted_bin' | 'blacklisted_country' | 'blacklisted_ip' | 'risk_declined' | 'security_violation' | 'expired_card' | 'gateway_reject' | 'suspected_fraud' | 'contact_issuer' | 'not_permitted' | 'invalid_account' | 'pickup_card' | 'stolen_card' | 'issuer_decline' | 'closed_account' | 'account_not_activated' | 'limit_exceeded' | 'withdrawal_limit_exceeded' | 'blocked_by_cardholder' | '3ds_authentication_failure' | '3ds_cardholder_not_participating' | '3ds_authentication_required' | 'payment_method_option_amex_disabled' | 'cvc_required' | 'payment_method_not_available' | 'payment_method_option_amex_not_available' | 'credit_card_not_permitted' | 'issuer_error' | 'system_error' | 'unknown_error' nullable

The most recent error when attempting to Pay.

Note that we may add further values without notice.

refundedAmountinteger

The total amount refunded thus far against the payment-session. Refunds can only be actioned once the payment-session is Captured. You can only have one refund in-flight at a time.

returnUrlstring

URL to send the customer back to after a redirection (e.g. 3DS). We will always append the paymentSessionId under query param ps.

authorizationType'PreAuth' | 'FinalAuth' nullable

Specifies the type of authorization. PreAuth - Used to authorize a non-final amount, where you may want to later capture a different amount or adjust the initial authorized amount. FinalAuth - When the amount authorized is final and identical to the amount later captured. By default we will always use FinalAuth. Note that PreAuth is restricted to particular MCC values for Visa, contact us to verify and enable PreAuth if you believe your business is eligible.

captureFlow'Automatic' | 'Manual' nullable

Whether the payment is automatically/manually captured. Defaults to Automatic.

verifyAccountboolean nullable

Whether the PaymentSession was used to facilitate an account verification check.

createdTimestampinteger

The epoch timestamp (seconds) when the payment was created

lastUpdatedTimestampinteger

The epoch timestamp (seconds) when the payment was last updated

Example response

{
  "id": "ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  "amount": 500,
  "currency": "GBP",
  "paymentType": "Standard",
  "entryMode": "Online",
  "customerEmail": "example@mail.com",
  "customerDetails": {
    "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ",
    "firstName": "Fred",
    "lastName": "Jones",
    "homePhoneNumber": "+447900000000",
    "mobilePhoneNumber": "+447900000000",
    "metadata": {
      "customerId": "123"
    }
  },
  "credentialOnFileUsage": {
    "initiator": "Customer",
    "sequence": "Initial"
  },
  "previousPayment": {
    "id": "ps_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "rebillingDetail": {
    "amountVariance": "Fixed",
    "numberOfDaysBetweenPayments": 30,
    "totalNumberOfPayments": 12,
    "currentPaymentNumber": 1,
    "expiry": 1776988800
  },
  "paymentMethod": {
    "type": "Card",
    "tokenizedDetails": {
      "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ",
      "stored": true
    },
    "card": {
      "scheme": "Mastercard",
      "last4": "4242",
      "binDetails": {
        "issuer": "Ryft Bank Ltd",
        "issuerCountry": "GB",
        "fundingType": "Debit",
        "productType": "Consumer"
      }
    },
    "wallet": {
      "type": "ApplePay"
    },
    "billingAddress": {
      "firstName": "Nathan",
      "lastName": "Jones",
      "lineOne": "123 Test Street",
      "lineTwo": "456 Lane",
      "city": "Manchester",
      "country": "GB",
      "postalCode": "SP4 7DE",
      "region": "NY"
    },
    "checks": {
      "avsResponseCode": "Y",
      "cvvResponseCode": "M"
    }
  },
  "platformFee": 50,
  "splitPaymentDetail": {
    "items": [
      {
        "id": "sp_01FCTS1XMKH9FF43CAFA4CXT3P",
        "accountId": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
        "amount": 50,
        "fee": {
          "amount": 50
        },
        "description": "2 x The Selfish Gene",
        "metadata": {
          "productId": "123",
          "productDescription": "The Selfish Gene"
        }
      }
    ]
  },
  "status": "PendingPayment",
  "metadata": {
    "orderNumber": "123"
  },
  "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
  "lastError": "insufficient_funds",
  "refundedAmount": 120,
  "statementDescriptor": {
    "descriptor": "Ryft Ltd",
    "city": "London"
  },
  "requiredAction": {
    "type": "Redirect",
    "url": "https://ryftpay.com/3ds-auth"
  },
  "returnUrl": "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  "authorizationType": "FinalAuth",
  "captureFlow": "Automatic",
  "shippingDetails": {
    "address": {
      "firstName": "Fox",
      "lastName": "Mulder",
      "lineOne": "Stonehenge",
      "postalCode": "SP4 7DE",
      "city": "Salisbury",
      "country": "GB"
    }
  },
  "orderDetails": {
    "reference": "fffd1682-f82b-43e3-a89b-48d9ad7d55d9",
    "items": [
      {
        "reference": "product123",
        "name": "The Big Gundown (Blu-ray)",
        "quantity": 2,
        "unitPrice": 250,
        "taxAmount": 50,
        "totalAmount": 540,
        "discountAmount": 10
      }
    ]
  },
  "paymentSettings": {
    "platform": {
      "paymentFees": {
        "interchange": {
          "bookTo": "ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327"
        },
        "network": {
          "bookTo": "ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327"
        },
        "miscPassThrough": {
          "bookTo": "ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327"
        }
      }
    },
    "threeDs": {
      "challengeIndicator": "NoPreference"
    }
  },
  "createdTimestamp": 1470989538,
  "lastUpdatedTimestamp": 1470989538
}