Sign in

v1

latestOpenAPI 3.0.02026-08-0696238481.7 KB
Payments

Initiate a payment attempt

This is used to supply the card you have collected from the customer to pay for this payment session. Only call this endpoint from your front-end once you have collected the customer's card details.

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

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......"
  },
  "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"
    }
  }
}

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

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
}