Sign in

v1

latestOpenAPI 3.0.02026-08-0696238481.7 KB
Payments

Update a payment session by Id

This is used to update a payment session by its Id. Note that this can only be used prior to a successful payment. Once payment has been approved, you cannot update a PaymentSession.

patch/payment-sessions/{paymentSessionId}

Path parameters

paymentSessionIdstring required
Example:ps_01FCTS1XMKH9FF43CAFA4CXT3P

Payment Id to update

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

amountinteger

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

customerEmailstring

The email address of the customer

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. 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.

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.

Example request

{
  "amount": 500,
  "customerEmail": "example@mail.com",
  "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"
        }
      }
    ]
  },
  "metadata": {
    "orderId": "2"
  },
  "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": {
    "threeDs": {
      "challengeIndicator": "NoPreference"
    }
  }
}

Response

Successfully retrieved the given paymentSessionId

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
}