Process payments with Ryft: authorizations, voids, captures, refunds etc.
- Retrieve a payment session by Id
Create a new payment session
Retrieve payment sessions between timestamps
Update a payment session by Id
Initiate a payment attempt
Continue taking payment after the initial attempt.
List payment transaction(s)
Retrieve a payment transaction
Manually capture a payment session
Void a payment session
Refund a payment
Retrieve a payment sessio...
Ryft Payment API (1.1.0)
Ryft provides a collection of APIs that you can use to accept and process payments + marketplace functionality (payouts). We have a testing environment called sandbox, which you can sign up for to test API calls without affecting live data.
When you sign up for an account, you are given a secret and public API key pair. You authenticate with our API by providing the appropriate key in the request Authorization header. Never share your secret keys. Keep them guarded and secure.
Public keys should only be used in JavaScript or native applications. This key is solely used to identify the partner making requests. Supply this key in the Authorization header.
Your secret key should always be supplied in the Authorization header. Make sure this key is stored securely on your backend and never surfaced client-side.
We use rate limiting on a per-user basis to protect our APIs against abuse. Our Sandbox environment is limited to 5 requests per second. Our production environment is limited to 50 requests per second.
We also allow a brief burst above this limit to accommodate a sudden increase in traffic.
If you exceed the above quota then the API will respond with a 429 status code and you will need to retry the API call (we recommend implementing a retry policy with an exponential back-off).
Download OpenAPI description
Overview
Languages
Servers
Sandbox environmment
https://sandbox-api.ryftpay.com/v1/
Production environment
https://api.ryftpay.com/v1/
Bodyapplication/json
The amount of the sale/purchase in minor digits
Example: 500
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
Example: "example@mail.com"
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
Example: 50
Use this field to facilitate split-payments. This will divide up the amount as specified in the forms of split-payments to each sub account once payment is successfully captured. The total of all items must be <= to the amount on the payment session. Cannot be used in conjunction with platformFee or passThroughProcessingFee. You must also not specify a sub account ID in the Account header. Note that any splits provided as part of a capture request will overwrite those that were given during authorization. Howver, if you are using multi-capture (i.e. NotFinal) then any subsequent splits will not be written to the PaymentSession. Instead you need to store the Id of the capture transaction and refer to that to track each capture.
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.
Enum"Automatic""Manual"
Example: "Automatic"
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.
Default "Standard"
Enum"Standard""Unscheduled""MOTO""Recurring"
Example: "Standard"
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.
Enum"Online""MOTO"
For recurring/unscheduled payments - details of the initial payment in the series. Required for:
- partners who want to externally schedule
Recurringpayments. - partners who process
Unscheduledpayments
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:
CaptureFlowwill default toManual, do not passAutomaticotherwise the request will be rejected.platformFeecannot be provided in your request - sub accounts cannot be charged for these payments.splitscannot be provided in your request - there is no amount to split.
Example: null
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.
Example: {"orderId":"1","customerId":"123"}
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: "https://ryftpay.com/checkout?orderId=123"
Use to immediately attempt payment at the time of creating the PaymentSession.
Allows for customisation of various payment settings.
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.
Example: false
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions
- cURL
- Node
- Python
curl -i -X POST \
https://sandbox-api.ryftpay.com/v1/payment-sessions \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"amount": 150,
"currency": "GBP",
"customerEmail": "test@ryftpay.com"
}'payment session successfully created
The unique identifier for the payment
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
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.
Default "Standard"
Enum"Standard""Unscheduled""MOTO""Recurring"
Example: "Standard"
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 phoneInPerson- 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.
Enum"Online""MOTO""InPerson"
Example: "Online"
(CredentialOnFileUsage (object or null))
For recurring/unscheduled payments - details of the initial payment in the series. Required for:
- partners who want to externally schedule recurring payments.
- partners who process
Unscheduledpayments
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.
Default ["Card"]
Items Value"Card"
The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the "amount" property
Example: 50
Enum"PendingPayment""PendingAction""Processing""Approved""Captured""Voided"
Example: "PendingPayment"
use this parameter to attach key-value data to the payment. These will be sent with any associated payment events on your webhook.
Example: {"orderNumber":"123"}
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
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004"
The most recent error when attempting to Pay.
Note that we may add further values without notice.
Enum"insufficient_funds""declined_do_not_honour""invalid_card_number""cvv2_failure""restricted_card""blacklisted_card""blacklisted_bin""blacklisted_country""blacklisted_ip""risk_declined"
Example: "insufficient_funds"
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.
Example: 120
The action to take (if any) in order to authorise the payment. This will be non-null if the customer's bank challenge the payment (i.e. 3DS)
Example: {"type":"Redirect","url":"https://ryftpay.com/3ds-auth"}
URL to send the customer back to after a redirection (e.g. 3DS). We will always append the paymentSessionId under query param ps.
Example: "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P"
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.
Enum"PreAuth""FinalAuth"
Example: "FinalAuth"
Whether the payment is automatically/manually captured. Defaults to Automatic.
Enum"Automatic""Manual"
Example: "Automatic"
Whether the PaymentSession was used to facilitate an account verification check.
Example: null
Allows for customisation of various payment settings.
The epoch timestamp (seconds) when the payment was created
Example: 1470989538
Response
application/json
{ "id": "ps_01JW95YEAEFGVVGHXT04D0C8B8", "amount": 150, "currency": "GBP", "paymentType": "Standard", "entryMode": "Online", "customerEmail": "test@ryftpay.com", "enabledPaymentMethods": [ "Card" ], "returnUrl": "https://ryftpay.com", "status": "PendingPayment", "refundedAmount": 0, "clientSecret": "ps_01JW95YEAEFGVVGHXT04D0C8B8_secret_0e24c997-7076-4b01-bb22-729864329c2c", "statementDescriptor": { "descriptor": "Ryft Ltd", "city": "Manchester" }, "authorizationType": "FinalAuth", "captureFlow": "Automatic", "createdTimestamp": 1748359919, "lastUpdatedTimestamp": 1748359919 }
Query
The timestamp when to return payment sessions from (inclusive), it must be before the endTimestamp. If not provided it will default to midnight on the current date (UTC).
Example: startTimestamp=1641859200
The timestamp when to return payment sessions up to (inclusive), it must be after the startTimestamp. If not provided it will default to the current time (UTC).
Example: endTimestamp=1641945599
Control the order (newest or oldest) in which the payment sessions are returned. false will arrange the results with newest first, whereas true shows oldest first. The default is false.
Example: ascending=false
Control how many items are return in a given page The max limit we allow is 50. The default is 10.
Example: limit=10
A token to identify the payment session to start querying after. This is most commonly used to get the next page of results after a previous response did not return all payment sessions, due to the imposed limit. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results for that timestamp range.
Example: startsAfter=ps_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions
- cURL
- Node
- Python
curl -i -X GET \
https://sandbox-api.ryftpay.com/v1/payment-sessions \
-H 'Authorization: YOUR_API_KEY_HERE'Response
application/json
{ "items": [ { … } ], "paginationToken": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473" }
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions/{paymentSessionId}
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions/{paymentSessionId}
- cURL
- Node
- Python
curl -i -X GET \
https://sandbox-api.ryftpay.com/v1/payment-sessions/ps_01FCTS1XMKH9FF43CAFA4CXT3P \
-H 'Authorization: YOUR_API_KEY_HERE'Successfully retrieved the given paymentSessionId
The unique identifier for the payment
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
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.
Default "Standard"
Enum"Standard""Unscheduled""MOTO""Recurring"
Example: "Standard"
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 phoneInPerson- 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.
Enum"Online""MOTO""InPerson"
Example: "Online"
(CredentialOnFileUsage (object or null))
For recurring/unscheduled payments - details of the initial payment in the series. Required for:
- partners who want to externally schedule recurring payments.
- partners who process
Unscheduledpayments
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.
Default ["Card"]
Items Value"Card"
The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the "amount" property
Example: 50
Enum"PendingPayment""PendingAction""Processing""Approved""Captured""Voided"
Example: "PendingPayment"
use this parameter to attach key-value data to the payment. These will be sent with any associated payment events on your webhook.
Example: {"orderNumber":"123"}
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
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004"
The most recent error when attempting to Pay.
Note that we may add further values without notice.
Enum"insufficient_funds""declined_do_not_honour""invalid_card_number""cvv2_failure""restricted_card""blacklisted_card""blacklisted_bin""blacklisted_country""blacklisted_ip""risk_declined"
Example: "insufficient_funds"
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.
Example: 120
The action to take (if any) in order to authorise the payment. This will be non-null if the customer's bank challenge the payment (i.e. 3DS)
Example: {"type":"Redirect","url":"https://ryftpay.com/3ds-auth"}
URL to send the customer back to after a redirection (e.g. 3DS). We will always append the paymentSessionId under query param ps.
Example: "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P"
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.
Enum"PreAuth""FinalAuth"
Example: "FinalAuth"
Whether the payment is automatically/manually captured. Defaults to Automatic.
Enum"Automatic""Manual"
Example: "Automatic"
Whether the PaymentSession was used to facilitate an account verification check.
Example: null
Allows for customisation of various payment settings.
The epoch timestamp (seconds) when the payment was created
Example: 1470989538
Response
application/json
{ "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": { … } }, "credentialOnFileUsage": { "initiator": "Customer", "sequence": "Initial" }, "previousPayment": { "id": "ps_01G0EYVFR02KBBVE2YWQ8AKMGJ" }, "rebillingDetail": { "amountVariance": "Fixed", "numberOfDaysBetweenPayments": 30, "totalNumberOfPayments": 12, "currentPaymentNumber": 1, "expiry": 1776988800 }, "enabledPaymentMethods": [ "Card" ], "paymentMethod": { "type": "Card", "tokenizedDetails": { … }, "card": { … }, "wallet": { … }, "billingAddress": { … }, "checks": { … } }, "platformFee": 50, "splitPaymentDetail": { "items": [ … ] }, "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", "verifyAccount": null, "shippingDetails": { "address": { … } }, "orderDetails": { "reference": "fffd1682-f82b-43e3-a89b-48d9ad7d55d9", "items": [ … ] }, "paymentSettings": { "paymentMethodOptions": { … }, "platform": { … } }, "createdTimestamp": 1470989538, "lastUpdatedTimestamp": 1470989538 }
Bodyapplication/jsonrequired
A request to update a payment session
The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the "amount" property
Example: 50
Use this field to facilitate split-payments. This will divide up the amount as specified in the forms of split-payments to each sub account once payment is successfully captured. The total of all items must be <= to the amount on the payment session. Cannot be used in conjunction with platformFee or passThroughProcessingFee. You must also not specify a sub account ID in the Account header. Note that any splits provided as part of a capture request will overwrite those that were given during authorization. Howver, if you are using multi-capture (i.e. NotFinal) then any subsequent splits will not be written to the PaymentSession. Instead you need to store the Id of the capture transaction and refer to that to track each capture.
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.
Example: {"orderId":"2"}
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.
Enum"Automatic""Manual"
Example: "Automatic"
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions/{paymentSessionId}
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions/{paymentSessionId}
- cURL
- Node
- Python
curl -i -X PATCH \
https://sandbox-api.ryftpay.com/v1/payment-sessions/ps_01FCTS1XMKH9FF43CAFA4CXT3P \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"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,
"productUrl": null,
"imageUrl": null
}
]
},
"paymentSettings": {
"paymentMethodOptions": {
"disabled": [
"Amex"
]
}
}
}'Successfully retrieved the given paymentSessionId
The unique identifier for the payment
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
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.
Default "Standard"
Enum"Standard""Unscheduled""MOTO""Recurring"
Example: "Standard"
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 phoneInPerson- 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.
Enum"Online""MOTO""InPerson"
Example: "Online"
(CredentialOnFileUsage (object or null))
For recurring/unscheduled payments - details of the initial payment in the series. Required for:
- partners who want to externally schedule recurring payments.
- partners who process
Unscheduledpayments
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.
Default ["Card"]
Items Value"Card"
The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the "amount" property
Example: 50
Enum"PendingPayment""PendingAction""Processing""Approved""Captured""Voided"
Example: "PendingPayment"
use this parameter to attach key-value data to the payment. These will be sent with any associated payment events on your webhook.
Example: {"orderNumber":"123"}
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
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004"
The most recent error when attempting to Pay.
Note that we may add further values without notice.
Enum"insufficient_funds""declined_do_not_honour""invalid_card_number""cvv2_failure""restricted_card""blacklisted_card""blacklisted_bin""blacklisted_country""blacklisted_ip""risk_declined"
Example: "insufficient_funds"
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.
Example: 120
The action to take (if any) in order to authorise the payment. This will be non-null if the customer's bank challenge the payment (i.e. 3DS)
Example: {"type":"Redirect","url":"https://ryftpay.com/3ds-auth"}
URL to send the customer back to after a redirection (e.g. 3DS). We will always append the paymentSessionId under query param ps.
Example: "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P"
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.
Enum"PreAuth""FinalAuth"
Example: "FinalAuth"
Whether the payment is automatically/manually captured. Defaults to Automatic.
Enum"Automatic""Manual"
Example: "Automatic"
Whether the PaymentSession was used to facilitate an account verification check.
Example: null
Allows for customisation of various payment settings.
The epoch timestamp (seconds) when the payment was created
Example: 1470989538
Response
application/json
{ "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": { … } }, "credentialOnFileUsage": { "initiator": "Customer", "sequence": "Initial" }, "previousPayment": { "id": "ps_01G0EYVFR02KBBVE2YWQ8AKMGJ" }, "rebillingDetail": { "amountVariance": "Fixed", "numberOfDaysBetweenPayments": 30, "totalNumberOfPayments": 12, "currentPaymentNumber": 1, "expiry": 1776988800 }, "enabledPaymentMethods": [ "Card" ], "paymentMethod": { "type": "Card", "tokenizedDetails": { … }, "card": { … }, "wallet": { … }, "billingAddress": { … }, "checks": { … } }, "platformFee": 50, "splitPaymentDetail": { "items": [ … ] }, "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", "verifyAccount": null, "shippingDetails": { "address": { … } }, "orderDetails": { "reference": "fffd1682-f82b-43e3-a89b-48d9ad7d55d9", "items": [ … ] }, "paymentSettings": { "paymentMethodOptions": { … }, "platform": { … } }, "createdTimestamp": 1470989538, "lastUpdatedTimestamp": 1470989538 }
Request
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.
Security
publicApiKeyAuth
The client secret of the payment session.
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004"
The type of the payment method the customer has opted to pay with.
Default "Card"
Value"Card"
Example: "Card"
Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"},"phoneNumber":"+447900000000"}
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions/attempt-payment
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions/attempt-payment
- cURL
- Node
- Python
curl -i -X POST \
https://sandbox-api.ryftpay.com/v1/payment-sessions/attempt-payment \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
"cardDetails": {
"number": "4444333322221111",
"expiryMonth": "10",
"expiryYear": "2024",
"cvc": "100"
}
}'Request ok, check the 'status' field to determine if the payment was successful
The unique identifier for the payment
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
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.
Default "Standard"
Enum"Standard""Unscheduled""MOTO""Recurring"
Example: "Standard"
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 phoneInPerson- 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.
Enum"Online""MOTO""InPerson"
Example: "Online"
(CredentialOnFileUsage (object or null))
For recurring/unscheduled payments - details of the initial payment in the series. Required for:
- partners who want to externally schedule recurring payments.
- partners who process
Unscheduledpayments
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.
Default ["Card"]
Items Value"Card"
The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the "amount" property
Example: 50
Enum"PendingPayment""PendingAction""Processing""Approved""Captured""Voided"
Example: "PendingPayment"
use this parameter to attach key-value data to the payment. These will be sent with any associated payment events on your webhook.
Example: {"orderNumber":"123"}
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
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004"
The most recent error when attempting to Pay.
Note that we may add further values without notice.
Enum"insufficient_funds""declined_do_not_honour""invalid_card_number""cvv2_failure""restricted_card""blacklisted_card""blacklisted_bin""blacklisted_country""blacklisted_ip""risk_declined"
Example: "insufficient_funds"
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.
Example: 120
The action to take (if any) in order to authorise the payment. This will be non-null if the customer's bank challenge the payment (i.e. 3DS)
Example: {"type":"Redirect","url":"https://ryftpay.com/3ds-auth"}
URL to send the customer back to after a redirection (e.g. 3DS). We will always append the paymentSessionId under query param ps.
Example: "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P"
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.
Enum"PreAuth""FinalAuth"
Example: "FinalAuth"
Whether the payment is automatically/manually captured. Defaults to Automatic.
Enum"Automatic""Manual"
Example: "Automatic"
Whether the PaymentSession was used to facilitate an account verification check.
Example: null
Allows for customisation of various payment settings.
The epoch timestamp (seconds) when the payment was created
Example: 1470989538
Response
application/json
{ "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": { … } }, "credentialOnFileUsage": { "initiator": "Customer", "sequence": "Initial" }, "previousPayment": { "id": "ps_01G0EYVFR02KBBVE2YWQ8AKMGJ" }, "rebillingDetail": { "amountVariance": "Fixed", "numberOfDaysBetweenPayments": 30, "totalNumberOfPayments": 12, "currentPaymentNumber": 1, "expiry": 1776988800 }, "enabledPaymentMethods": [ "Card" ], "paymentMethod": { "type": "Card", "tokenizedDetails": { … }, "card": { … }, "wallet": { … }, "billingAddress": { … }, "checks": { … } }, "platformFee": 50, "splitPaymentDetail": { "items": [ … ] }, "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", "verifyAccount": null, "shippingDetails": { "address": { … } }, "orderDetails": { "reference": "fffd1682-f82b-43e3-a89b-48d9ad7d55d9", "items": [ … ] }, "paymentSettings": { "paymentMethodOptions": { … }, "platform": { … } }, "createdTimestamp": 1470989538, "lastUpdatedTimestamp": 1470989538 }
Bodyapplication/jsonrequired
The client secret of the payment session.
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004"
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions/continue-payment
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions/continue-payment
- cURL
- Node
- Python
curl -i -X POST \
https://sandbox-api.ryftpay.com/v1/payment-sessions/continue-payment \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
"threeDs": {
"fingerprint": "ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ICI4ZjAxNzdhNC0yY2VkLTQ4NjUtODViNy1iYWQ5YmZhMzk4ZDIiLAogICJ0aHJlZURTQ29tcEluZCI6IlkiCn0="
}
}'Request ok, check the 'status' field to determine if the payment was successful. If status remains in PendingAction then further action is required before the payment can be authorized. Check the requiredAction field for the next step.
The unique identifier for the payment
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
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.
Default ["Card"]
Items Value"Card"
Enum"PendingPayment""PendingAction""Processing""Approved""Captured""Voided"
Example: "PendingPayment"
The most recent error when attempting to Pay.
Note that we may add further values without notice.
Enum"insufficient_funds""declined_do_not_honour""invalid_card_number""cvv2_failure""restricted_card""blacklisted_card""blacklisted_bin""blacklisted_country""blacklisted_ip""risk_declined"
Example: "insufficient_funds"
The action to take (if any) in order to authorise the payment. This will be non-null if the customer's bank challenge the payment (i.e. 3DS)
Example: {"type":"Redirect","url":"https://ryftpay.com/3ds-auth"}
URL to send the customer back to after a redirection (e.g. 3DS). We will always append the paymentSessionId under query param ps.
Example: "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P"
The epoch timestamp (seconds) when the payment was created
Example: 1470989538
Response
application/json
{ "id": "ps_01FCTS1XMKH9FF43CAFA4CXT3P", "amount": 500, "currency": "GBP", "customerEmail": "example@mail.com", "enabledPaymentMethods": [ "Card" ], "paymentMethod": { "type": "Card", "tokenizedDetails": { … }, "card": { … }, "wallet": { … }, "billingAddress": { … }, "checks": { … } }, "status": "PendingPayment", "lastError": "insufficient_funds", "requiredAction": { "type": "Redirect", "url": "https://ryftpay.com/3ds-auth" }, "returnUrl": "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P", "createdTimestamp": 1470989538, "lastUpdatedTimestamp": 1470989538 }
Query
Control the order (newest or oldest) in which the transactions are returned. false will arrange the results with newest first, whereas true shows oldest first. The default is false.
Example: ascending=false
Control how many items are return in a given page The max limit we allow is 50. The default is 10.
Example: limit=10
A token to identify the item to start querying after. This is most commonly used to get the next page of results after a previous response did not return all items, due to the imposed limit. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results for that timestamp range.
Example: startsAfter=txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/transactions
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/transactions
- cURL
- Node
- Python
curl -i -X GET \
'https://sandbox-api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/transactions' \
-H 'Authorization: YOUR_API_KEY_HERE'Response
application/json
{ "items": [ { … } ], "paginationToken": "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P" }
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/transactions/{paymentTransactionId}
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/transactions/{paymentTransactionId}
- cURL
- Node
- Python
curl -i -X GET \
'https://sandbox-api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/transactions/{paymentTransactionId}' \
-H 'Authorization: YOUR_API_KEY_HERE'Request Ok
The unique identifier for the transaction
Example: "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P"
The unique paymentSessionId that this transaction relates to
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
Enum"Authorization""Void""Capture""Refund""Chargeback""ChargebackReversal"
Example: "Capture"
The amount of the transaction that has been refunded, in minor digits.
Example: 50
Only supplied for 'capture' transactions. The amount of the capture that will be taken and applied to the platform account, in minor digits.
Example: 50
Only supplied for 'capture' transactions. The amount of the capture that has been refunded to the platform account, in minor digits.
Example: 50
An optional reason to describe this transaction. Typically used for refunds whereby the reason for the refund is recorded.
Example: "Requested by the customer"
Only supplied for 'capture' transactions. The type of capture. Typically only used for payments that support multi-capture. Once Final, any remaining uncaptured amount will be marked as void within 7 days.
Enum"Final""NotFinal"
Example: "Final"
The epoch timestamp (seconds) when the transaction was initiated
Example: 1470989538
The epoch timestamp (seconds) when the transaction was last updated
Example: 1470989538
Response
application/json
{ "id": "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P", "paymentSessionId": "ps_01FCTS1XMKH9FF43CAFA4CXT3P", "amount": 250, "currency": "GBP", "type": "Capture", "status": "Succeeded", "refundedAmount": 50, "platformFee": 50, "platformFeeRefundedAmount": 50, "processingFee": 7, "reason": "Requested by the customer", "captureType": "Final", "paymentMethod": { "type": "Card", "tokenizedDetails": { … }, "card": { … }, "wallet": { … }, "billingAddress": { … }, "checks": { … } }, "splitPaymentDetail": { "items": [ … ] }, "inPersonDetail": { "terminalDetail": { … } }, "createdTimestamp": 1470989538, "lastUpdatedTimestamp": 1470989538 }
Bodyapplication/jsonrequired
The amount to capture in minor digits. This must be <= to the amount already authorised on the payment. If you don't supply this then we will capture the full amount. Note: typically any remainder will be reversed/refunded to the customer on the same day, however not all acquirers support this and will instead return the remainder once the initial authorization has expired (e.g. after 7 days).
Example: 500
The type of capture. Typically only used for payments that support multi-capture. Once Final, any remaining uncaptured amount will be marked as void within 7 days. Note that if your account or the chosen payment does not support multi-capture then this field will be ignored.
Default "Final"
Enum"Final""NotFinal"
Example: "Final"
The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the amount to capture. Supply this if you also are supplying the "Account" header and want to take a fee from that account as part of this capture. If not supplied this defaults to the platformFee used when creating the payment session (if any) but still cannot be greater than the amount to capture here.
Example: 50
Use this field to facilitate split-payments. This will divide up the amount as specified in the forms of split-payments to each sub account once payment is successfully captured. The total of all items must be <= to the amount on the payment session. Cannot be used in conjunction with platformFee or passThroughProcessingFee. You must also not specify a sub account ID in the Account header. Note that any splits provided as part of a capture request will overwrite those that were given during authorization. Howver, if you are using multi-capture (i.e. NotFinal) then any subsequent splits will not be written to the PaymentSession. Instead you need to store the Id of the capture transaction and refer to that to track each capture.
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/captures
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/captures
- cURL
- Node
- Python
curl -i -X POST \
https://sandbox-api.ryftpay.com/v1/payment-sessions/ps_01FCTS1XMKH9FF43CAFA4CXT3P/captures \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"amount": 50
}'Capture request successfully accepted (Pending / Succeeded / Failed). If the status is Pending then the transaction will be completed asynchronously. Listen to the PaymentSession.captured event on your webhook to be notified of the outcome.
The unique identifier for the transaction
Example: "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P"
The unique paymentSessionId that this transaction relates to
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
Enum"Authorization""Void""Capture""Refund""Chargeback""ChargebackReversal"
Example: "Capture"
The amount of the transaction that has been refunded, in minor digits.
Example: 50
Only supplied for 'capture' transactions. The amount of the capture that will be taken and applied to the platform account, in minor digits.
Example: 50
Only supplied for 'capture' transactions. The amount of the capture that has been refunded to the platform account, in minor digits.
Example: 50
An optional reason to describe this transaction. Typically used for refunds whereby the reason for the refund is recorded.
Example: "Requested by the customer"
Only supplied for 'capture' transactions. The type of capture. Typically only used for payments that support multi-capture. Once Final, any remaining uncaptured amount will be marked as void within 7 days.
Enum"Final""NotFinal"
Example: "Final"
The epoch timestamp (seconds) when the transaction was initiated
Example: 1470989538
The epoch timestamp (seconds) when the transaction was last updated
Example: 1470989538
Response
application/json
{ "id": "txn_01J8HRF1FBEGYFFXNJMRZ704R6_01J8HRF73YD8VTP247ZRMT6E0B", "paymentSessionId": "ps_01J8HRF1FBEGYFFXNJMRZ704R6", "amount": 30, "currency": "GBP", "type": "Capture", "status": "Pending", "refundedAmount": 0, "captureType": "Final", "createdTimestamp": 1727172977, "lastUpdatedTimestamp": 1727172977 }
Request
Call this endpoint to void a payment session currently awaiting manual capture. This will reverse the amount authorized on the payment and return it to the customer. If voided on the same-day, the transaction will not show up on the customer's card statement(s). You can only call this endpoint when the payment session is in status Approved and its captureFlow value is Manual.
Security
secretApiKeyAuth
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/voids
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/voids
- cURL
- Node
- Python
curl -i -X POST \
https://sandbox-api.ryftpay.com/v1/payment-sessions/ps_01FCTS1XMKH9FF43CAFA4CXT3P/voids \
-H 'Authorization: YOUR_API_KEY_HERE'Void request successfully accepted (Pending / Succeeded / Failed). If the status is Pending then the transaction will be completed asynchronously. Listen to the PaymentSession.voided event on your webhook to be notified of the outcome.
The unique identifier for the transaction
Example: "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P"
The unique paymentSessionId that this transaction relates to
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
Enum"Authorization""Void""Capture""Refund""Chargeback""ChargebackReversal"
Example: "Capture"
The amount of the transaction that has been refunded, in minor digits.
Example: 50
Only supplied for 'capture' transactions. The amount of the capture that will be taken and applied to the platform account, in minor digits.
Example: 50
Only supplied for 'capture' transactions. The amount of the capture that has been refunded to the platform account, in minor digits.
Example: 50
An optional reason to describe this transaction. Typically used for refunds whereby the reason for the refund is recorded.
Example: "Requested by the customer"
Only supplied for 'capture' transactions. The type of capture. Typically only used for payments that support multi-capture. Once Final, any remaining uncaptured amount will be marked as void within 7 days.
Enum"Final""NotFinal"
Example: "Final"
The epoch timestamp (seconds) when the transaction was initiated
Example: 1470989538
The epoch timestamp (seconds) when the transaction was last updated
Example: 1470989538
Response
application/json
{ "id": "txn_01J8HRF1FBEGYFFXNJMRZ704R6_01J8HRF73YD8VTP247ZRMT6E0B", "paymentSessionId": "ps_01J8HRF1FBEGYFFXNJMRZ704R6", "amount": 30, "currency": "GBP", "type": "Void", "status": "Pending", "refundedAmount": 0, "createdTimestamp": 1727172977, "lastUpdatedTimestamp": 1727172977 }
Bodyapplication/json
The amount to refund in minor digits. Can be omitted when not using partial captures or splits; the remaining amount will be refunded.
Example: 500
A flag to indicate whether the platform fee should be refunded. If the payment amount is fully refunded, the platform fee will be too. If this is a partial refund then the platform fee will be refunded proportionally to the amount being refunded. By default this flag is false.
Example: false
Required if you have actioned multiple captures against a single PaymentSession. This must match the Id of a particular capture transaction as returned from the /captures endpoint. Note that the amount to refund cannot exceed the amount you captured for that /captures request.
- Sandbox environmmenthttps://sandbox-api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/refunds
- Production environmenthttps://api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/refunds
- cURL
- Node
- Python
curl -i -X POST \
'https://sandbox-api.ryftpay.com/v1/payment-sessions/{paymentSessionId}/refunds' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"amount": 250
}'Refund request successfully accepted (Pending / Succeeded / Failed). If the status is Pending then the transaction will be completed asynchronously. Listen to the PaymentSession.refunded event on your webhook to be notified of the outcome.
The unique identifier for the transaction
Example: "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P"
The unique paymentSessionId that this transaction relates to
Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
Enum"Authorization""Void""Capture""Refund""Chargeback""ChargebackReversal"
Example: "Capture"
The amount of the transaction that has been refunded, in minor digits.
Example: 50
Only supplied for 'capture' transactions. The amount of the capture that will be taken and applied to the platform account, in minor digits.
Example: 50
Only supplied for 'capture' transactions. The amount of the capture that has been refunded to the platform account, in minor digits.
Example: 50
An optional reason to describe this transaction. Typically used for refunds whereby the reason for the refund is recorded.
Example: "Requested by the customer"
Only supplied for 'capture' transactions. The type of capture. Typically only used for payments that support multi-capture. Once Final, any remaining uncaptured amount will be marked as void within 7 days.
Enum"Final""NotFinal"
Example: "Final"
The epoch timestamp (seconds) when the transaction was initiated
Example: 1470989538
The epoch timestamp (seconds) when the transaction was last updated
Example: 1470989538
Response
application/json
{ "id": "txn_01J8HRF1FBEGYFFXNJMRZ704R6_01J8HRF73YD8VTP247ZRMT6E0B", "paymentSessionId": "ps_01J8HRF1FBEGYFFXNJMRZ704R6", "amount": 30, "currency": "GBP", "type": "Refund", "status": "Pending", "reason": "Reduction due to missing / damaged item in transit", "createdTimestamp": 1727172977, "lastUpdatedTimestamp": 1727172977 }
Events
Events are persisted throughout the lifecycle of a payment/action as you use our API. We use events to notify you when something important happens in your account (or a linked sub account). The most commonly used event occurs when a payment is captured, in which case we persist a PaymentSession.captured event and then (optionally) send it to any webhooks you have registered that are listening for that event type.
Note that if you are taking payments as a platform (for sub accounts), events are saved against the sub account accountId, but will be sent to any webhooks that your account has configured.
Operations
Payouts
A payout represents the transfer of money from Ryft to a connected payout method (bank account), i.e. when we send money you're owed. Typically this is automated.
However, the payouts API allows you to explicitly create payouts for your sub accounts. Generally we'd recommend this if you are a marketplace who wants to control exactly when payouts should be sent out.
Operations
Transfers
A Transfer represents the movement of money between Ryft accounts.
This API allows platforms/marketplaces to transfer money from/to particular sub accounts, useful when:
- you owe a sub account money from a particular transaction and want to explicitly send it after the fact
- you want to recoup funds from a sub account, such as when dealing with disputes
- you want to collect additional/new commission from the sub account
Operations
Subscriptions
The subscriptions API allows you to automatically have Ryft schedule and charge recurring payments for a specific day and time. This API is not required to process recurring payments. After additional configuration, you can use our payment-sessions API to create and charge the recurring payments yourself.
Operations