Payments

Initiate a payment attempt

Changed on Nov 3, 2026

This is used to supply the card you have collected from the customer to pay for this payment session. Call this endpoint from your front-end with your public API key once you have collected the customer's card details.

You can also call it from your server with your secret API key. Supplying cardDetails from your server requires you to be PCI SAQ-D compliant, see Server-To-Server payments.

With your secret API key you can also send:

authenticationParameters, the result of 3D-Secure you have performed with your own 3DS server (MPI).
walletNetworkToken, an Apple Pay or Google Pay token you have decrypted yourself, together with its cryptogram in authenticationParameters.

See 3DS Configuration.

If you want the lowest PCI burden we recommend using our embedded payment forms in place of this endpoint. This ensures Ryft store & transmit the card details securely from our servers rather than your own. Please contact your account manager if you want to opt for this.

post/payment-sessions/attempt-payment

Request

Base URL
https://sandbox-api.ryftpay.com/v1
URL
https://sandbox-api.ryftpay.com/v1/payment-sessions/attempt-payment
Auth
- API key in header Authorization
- or API key in header Authorization

Headers

Accountstring

Example:ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Request body

clientSecretstring required

The client secret of the payment session.

paymentMethodType'Card' nullable

The type of the payment method the customer has opted to pay with.

Example request

{
  "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
  "paymentMethodType": "Card",
  "cardDetails": {
    "number": "4444333322221111",
    "expiryMonth": "10",
    "expiryYear": "2024",
    "cvc": "100",
    "name": "MR ISAAC CLARKE"
  },
  "walletDetails": {
    "type": "ApplePay",
    "googlePayToken": "{\"signature\":\"MEYCIQCOjFuUGDkyieeJCQkm23qMSsQtGRjjVcWuAEHjdcGtNH+fx9GD342jNa\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEjHIVnhmXEs2OjgvsLYCuiwXttkLpM5EFA3snvzPBUzT9hFeUuPCBTyP+83vbpNo5WFqjObGuVj3EFYRa0bGQ0+4ZYlk16tk4cGqVliuD2VS+ooPiDzztKahTj3tNicjyUjpD7AxiMPf/RHsHTlXs+m79EibjQxyE/CjlqrwfA3qpxJpdkt/ihS8JlVhQP8d/gnV/Get36o02gZc/F9s7kfG6Ur/rZ0Nf5F0yVCfZfgYCIeEPE415sjm0yJehlmVJ+iWrsdoUjrTlDfNqUj8m44vfxyrmTbk2HaAgy+LWyu0DtBFHtQsecZpGyYLGbiTRbL/F6wXEZEcM9W8lFy7pNtyx2FpvGFKPOnM8hAEhJ6OkDHMNmBSZWoqY9PLeVeXvbuW9KdKzHeGkFQmsypKBrkT5XDmP49AFAnaGyVfvtBunLdt4SrPqJgSpvLdBhvOwHNQRSAaaUx6xBQqEecVAZF/fdwpcMXc2Mc\\\",\\\"ephemeralPublicKey\\\":\\\"BEPsTEoiu6nyicBC9EhvTE45t8+IxjiKiifT/tmytIhn+O6d+cGSuiSmzeg1k1X0xZqr...\",\\\"tag\\\":\\\"pDKKl7MBNL+CnyrY6XB8E/T6hbbnEo8q4\\\\u003d\\\"}\"}",
    "applePayToken": "eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiN21Fay9BSGh2OXJzSmM1K0NFbVhRaERHaHZCMjViaDFxb0hTZmVVWHpiNFA5Nk5ieWd6alV3ZnR3RXJUYmRhQ3FFMXFi......"
  },
  "walletNetworkToken": {
    "number": "4444333322221111",
    "expiryMonth": "10",
    "expiryYear": "2028",
    "name": "MR ISAAC CLARKE",
    "walletType": "ApplePay"
  },
  "paymentMethod": {
    "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ",
    "cvc": "100"
  },
  "billingAddress": {
    "firstName": "Nathan",
    "lastName": "Jones",
    "lineOne": "123 Test Street",
    "lineTwo": "456 Lane",
    "city": "Manchester",
    "country": "GB",
    "postalCode": "SP4 7DE",
    "region": "NY"
  },
  "customerDetails": {
    "email": "example@mail.com",
    "homePhoneNumber": "+447900000000",
    "mobilePhoneNumber": "+447900000000"
  },
  "shippingDetails": {
    "address": {
      "firstName": "Fox",
      "lastName": "Mulder",
      "lineOne": "Stonehenge",
      "postalCode": "SP4 7DE",
      "city": "Salisbury",
      "country": "GB"
    },
    "phoneNumber": "+447900000000"
  },
  "threeDsRequestDetails": {
    "deviceChannel": "Browser",
    "browserDetails": {
      "acceptHeader": "application/json,text/plain,text/html,*/*",
      "colorDepth": 24,
      "language": "en-GB",
      "screenHeight": 900,
      "screenWidth": 1440,
      "timeZoneOffset": -120,
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36"
    }
  },
  "authenticationParameters": {
    "eci": "05",
    "authenticationValue": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
    "protocolVersion": "2.2.0",
    "threeDsServerTransactionId": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
    "acsTransactionId": "13c701a3-5a88-4c45-89e9-ef65e50a8bf9",
    "dsTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b"
  }
}

Response

Request ok, check the 'status' field to determine if the payment was successful

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

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

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",
      "policy": "Required"
    }
  },
  "createdTimestamp": 1470989538,
  "lastUpdatedTimestamp": 1470989538
}

Changes

Nov 3, 2026b3737947dfab Revision changes
- info
  the endpoint scheme security secretApiKeyAuth was added to the API
- info
  added the new optional request property
- info
  added the new optional request property
Oct 29, 2026d73b6f121d8a Revision changes
- warning
  added the new 3ds_authentication_not_supported enum value to the response property for the response status
- warning
  added the new authorisation_denied enum value to the response property for the response status
- warning
  added the new in_person_terminal_action_cancelled enum value to the response property for the response status
- warning
  added the new in_person_terminal_action_timeout enum value to the response property for the response status
- warning
  added the new in_person_terminal_busy enum value to the response property for the response status
- warning
  added the new in_person_terminal_not_available enum value to the response property for the response status
- warning
  added the new payment_cancelled enum value to the response property for the response status
- warning
  added the new recurring_series_terminated enum value to the response property for the response status

Operation history (3 revisions)