API docs by Redocly

Ryft Payment API (1.1.0)

Download OpenAPI specification:Download

Ryft: support@ryftpay.com

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.

Embedded solutions

We also offer embedded payment forms to support businesses who want the lowest PCI burden. Our embedded card form allows you to collect card details and have Ryft securely store and transmit the card details to action payment. Please contact your account manager for this when you are planning to integrate.

Authentication

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 API key

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.

Secret API key

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.

Rate Limiting

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

Payments

Process payments with Ryft: authorizations, voids, captures, refunds etc.

Testing

Testing various payment flows is detailed in our Developer documentation

Create a new payment session

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

Authorizations:
secretApiKeyAuth
header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Request Body schema: application/json
amount
required
integer <int32> [ 30 .. 2000000 ]

The amount of the sale/purchase in minor digits

currency
required
string

The ISO currency code

customerEmail
string or null

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

object
platformFee
integer or null <int32> [ 0 .. 2000000 ]

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

passThroughProcessingFee
boolean or null
Deprecated

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. Setting this to true means the linked account will pay the fee. Setting this to false (default) means you pay the processing fee (which is deducted from your own platformFee once the payment is captured)

object or null (SplitPaymentRequestDetail)

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

captureFlow
string or null
Enum: "Automatic" "Manual"

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

paymentType
string
Default: "Standard"
Enum: "Standard" "Unscheduled" "MOTO" "Recurring"

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

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

MIT values:

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

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

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

entryMode
string or null (EntryMode)
Enum: "Online" "MOTO"

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.

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 Unscheduled payments
(RebillingDetailRequest (object or null))

Details the parameters specific to recurring payments (e.g. Subscriptions). Required if:

  • this is the initial transaction in the recurring series.
  • you are creating the Recurring transactions (paymentType: Recurring)
verifyAccount
boolean or null

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

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

The shipping details for the purchase/payment. This is optional but recommended to reduce fraudulent payments.

(OrderDetails (object or null))

The details of the customer's order. Currently includes line item information.

metadata
object

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.

object or null
returnUrl
string or null

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.

(CreatePaymentSessionAttemptPaymentRequest (object or null))

Use to immediately attempt payment at the time of creating the PaymentSession.

(PaymentSettingsRequest (object or null))

Responses

Request samples

Content type
application/json
{
  • "amount": 500,
  • "currency": "GBP",
  • "customerEmail": "example@mail.com",
  • "customerDetails": {
    },
  • "platformFee": 50,
  • "passThroughProcessingFee": false,
  • "splits": {
    },
  • "captureFlow": "Automatic",
  • "paymentType": "Standard",
  • "entryMode": "Online",
  • "previousPayment": {
    },
  • "rebillingDetail": {
    },
  • "verifyAccount": true,
  • "shippingDetails": {
    },
  • "orderDetails": {
    },
  • "metadata": {
    },
  • "statementDescriptor": {
    },
  • "returnUrl": "https://ryftpay.com/checkout?orderId=123",
  • "attemptPayment": {
    },
  • "paymentSettings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "amount": 500,
  • "currency": "GBP",
  • "paymentType": "Standard",
  • "entryMode": "Online",
  • "customerEmail": "example@mail.com",
  • "customerDetails": {
    },
  • "credentialOnFileUsage": {
    },
  • "previousPayment": {
    },
  • "rebillingDetail": {
    },
  • "enabledPaymentMethods": [
    ],
  • "paymentMethod": {
    },
  • "platformFee": 50,
  • "splitPaymentDetail": {
    },
  • "status": "PendingPayment",
  • "metadata": {
    },
  • "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
  • "lastError": "insufficient_funds",
  • "refundedAmount": 120,
  • "statementDescriptor": {
    },
  • "requiredAction": {},
  • "returnUrl": "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "authorizationType": "FinalAuth",
  • "captureFlow": "Automatic",
  • "verifyAccount": true,
  • "shippingDetails": {
    },
  • "orderDetails": {
    },
  • "paymentSettings": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Retrieve payment sessions between timestamps

This is used to fetch payment sessions within a timestamp range, paginated

Authorizations:
secretApiKeyAuth
query Parameters
startTimestamp
integer <int64>
Example: startTimestamp=1641859200

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

endTimestamp
integer <int64>
Example: endTimestamp=1641945599

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

ascending
boolean <boolean>
Example: ascending=false

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.

limit
integer <int32>
Example: limit=10

Control how many items are return in a given page The max limit we allow is 50. The default is 10.

startsAfter
string
Example: startsAfter=ps_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473

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.

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "paginationToken": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"
}

Retrieve a payment session by Id

This is used to fetch a payment session by its paymentSessionId

Authorizations:
secretApiKeyAuth
path Parameters
paymentSessionId
required
string^ps_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: ps_01FCTS1XMKH9FF43CAFA4CXT3P

Payment Id to retrieve

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Responses

Response samples

Content type
application/json
{
  • "id": "ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "amount": 500,
  • "currency": "GBP",
  • "paymentType": "Standard",
  • "entryMode": "Online",
  • "customerEmail": "example@mail.com",
  • "customerDetails": {
    },
  • "credentialOnFileUsage": {
    },
  • "previousPayment": {
    },
  • "rebillingDetail": {
    },
  • "enabledPaymentMethods": [
    ],
  • "paymentMethod": {
    },
  • "platformFee": 50,
  • "splitPaymentDetail": {
    },
  • "status": "PendingPayment",
  • "metadata": {
    },
  • "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
  • "lastError": "insufficient_funds",
  • "refundedAmount": 120,
  • "statementDescriptor": {
    },
  • "requiredAction": {},
  • "returnUrl": "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "authorizationType": "FinalAuth",
  • "captureFlow": "Automatic",
  • "verifyAccount": true,
  • "shippingDetails": {
    },
  • "orderDetails": {
    },
  • "paymentSettings": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

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.

Authorizations:
secretApiKeyAuth
path Parameters
paymentSessionId
required
string^ps_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: ps_01FCTS1XMKH9FF43CAFA4CXT3P

Payment Id to update

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Request Body schema: application/json

A request to update a payment session

amount
integer <int32> [ 30 .. 2000000 ]

The amount of the sale/purchase in minor digits

customerEmail
string

The email address of the customer

platformFee
integer or null <int32> [ 0 .. 2000000 ]

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

object or null (SplitPaymentRequestDetail)

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

metadata
object or null

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
string or null
Enum: "Automatic" "Manual"

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.

(ShippingDetails (object or null))

The shipping details for the purchase/payment. This is optional but recommended to reduce fraudulent payments.

(OrderDetails (object or null))

The details of the customer's order. Currently includes line item information.

(PaymentSettingsRequest (object or null))

Responses

Request samples

Content type
application/json
{
  • "amount": 500,
  • "customerEmail": "example@mail.com",
  • "platformFee": 50,
  • "splits": {
    },
  • "metadata": {
    },
  • "captureFlow": "Automatic",
  • "shippingDetails": {
    },
  • "orderDetails": {
    },
  • "paymentSettings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "amount": 500,
  • "currency": "GBP",
  • "paymentType": "Standard",
  • "entryMode": "Online",
  • "customerEmail": "example@mail.com",
  • "customerDetails": {
    },
  • "credentialOnFileUsage": {
    },
  • "previousPayment": {
    },
  • "rebillingDetail": {
    },
  • "enabledPaymentMethods": [
    ],
  • "paymentMethod": {
    },
  • "platformFee": 50,
  • "splitPaymentDetail": {
    },
  • "status": "PendingPayment",
  • "metadata": {
    },
  • "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
  • "lastError": "insufficient_funds",
  • "refundedAmount": 120,
  • "statementDescriptor": {
    },
  • "requiredAction": {},
  • "returnUrl": "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "authorizationType": "FinalAuth",
  • "captureFlow": "Automatic",
  • "verifyAccount": true,
  • "shippingDetails": {
    },
  • "orderDetails": {
    },
  • "paymentSettings": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Attempts to pay for a payment session (take payment with a payment method) from your front-end

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.

Authorizations:
publicApiKeyAuth
header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Request Body schema: application/json
clientSecret
required
string

The client secret of the payment session.

paymentMethodType
string or null
Default: "Card"
Value: "Card"

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

object (CardDetails)
object (WalletDetails)
object (PaymentRequestPaymentMethod)
object (AttemptPaymentPaymentMethodOptions)
object (CustomerAddress)
object (CustomerDetails)
object (ThreeDsRequestDetails)

Responses

Request samples

Content type
application/json
Example
{
  • "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
  • "cardDetails": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "amount": 500,
  • "currency": "GBP",
  • "paymentType": "Standard",
  • "entryMode": "Online",
  • "customerEmail": "example@mail.com",
  • "customerDetails": {
    },
  • "credentialOnFileUsage": {
    },
  • "previousPayment": {
    },
  • "rebillingDetail": {
    },
  • "enabledPaymentMethods": [
    ],
  • "paymentMethod": {
    },
  • "platformFee": 50,
  • "splitPaymentDetail": {
    },
  • "status": "PendingPayment",
  • "metadata": {
    },
  • "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
  • "lastError": "insufficient_funds",
  • "refundedAmount": 120,
  • "statementDescriptor": {
    },
  • "requiredAction": {},
  • "returnUrl": "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "authorizationType": "FinalAuth",
  • "captureFlow": "Automatic",
  • "verifyAccount": true,
  • "shippingDetails": {
    },
  • "orderDetails": {
    },
  • "paymentSettings": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Continue taking payment after the initial attempt.

Submit additional data for payment sessions that require further action after using attempt-payment. Note that our SDKs handle this step automatically.

Authorizations:
publicApiKeyAuth
header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Request Body schema: application/json
clientSecret
required
string

The client secret of the payment session.

object (ContinueThreeDsRequest)

Supply the result of a 3ds fingerprint/challenge step. One of fingerprint or challengeResult must be provided.

Responses

Request samples

Content type
application/json
Example
{
  • "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
  • "threeDs": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "amount": 500,
  • "currency": "GBP",
  • "customerEmail": "example@mail.com",
  • "enabledPaymentMethods": [
    ],
  • "paymentMethod": {
    },
  • "status": "PendingPayment",
  • "lastError": "insufficient_funds",
  • "requiredAction": {},
  • "returnUrl": "https://ryftpay.com/checkout?orderId=123&ps=ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

List payment transaction(s)

List the transaction(s) for a particular payment

Authorizations:
secretApiKeyAuth
path Parameters
paymentSessionId
required
string

Payment Id to list transactions for

query Parameters
ascending
boolean <boolean>
Example: ascending=false

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.

limit
integer <int32>
Example: limit=10

Control how many items are return in a given page The max limit we allow is 50. The default is 10.

startsAfter
string
Example: startsAfter=txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P

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.

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "paginationToken": "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P"
}

Retrieve a payment transaction

Retrieve the transaction for a particular payment

Authorizations:
secretApiKeyAuth
path Parameters
paymentSessionId
required
string

Payment Id that the transaction is under

paymentTransactionId
required
string

Payment transaction Id to retrieve

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Responses

Response samples

Content type
application/json
{
  • "id": "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "paymentSessionId": "ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "amount": 250,
  • "currency": "GBP",
  • "type": "Authorization",
  • "status": "Succeeded",
  • "refundedAmount": 50,
  • "platformFee": 50,
  • "platformFeeRefundedAmount": 50,
  • "processingFee": 7,
  • "reason": "Requested by the customer",
  • "captureType": "Final",
  • "paymentMethod": {
    },
  • "splitPaymentDetail": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Manually capture a payment session that you have previously authorized.

Call this endpoint to capture funds you have previously authorized on a payment session. You can only call this endpoint when the payment session is in status Approved and its captureFlow value is Manual.

Authorizations:
secretApiKeyAuth
path Parameters
paymentSessionId
required
string^ps_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: ps_01FCTS1XMKH9FF43CAFA4CXT3P

Payment Id to update

header Parameters
Account
string
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Request Body schema: application/json
amount
integer or null <int32> [ 30 .. 2000000 ]

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

captureType
string or null
Default: "Final"
Enum: "Final" "NonFinal"

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.

platformFee
integer or null <int32> [ 0 .. 2000000 ]

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.

object or null (SplitPaymentRequestDetail)

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

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 50
}

Response samples

Content type
application/json
{
  • "id": "txn_01J8HRF1FBEGYFFXNJMRZ704R6_01J8HRF73YD8VTP247ZRMT6E0B",
  • "paymentSessionId": "ps_01J8HRF1FBEGYFFXNJMRZ704R6",
  • "amount": 30,
  • "currency": "GBP",
  • "type": "Capture",
  • "status": "Succeeded",
  • "refundedAmount": 0,
  • "captureType": "Final",
  • "createdTimestamp": 1727172977,
  • "lastUpdatedTimestamp": 1727172977
}

Voids a payment session awaiting manual capture.

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.

Authorizations:
secretApiKeyAuth
path Parameters
paymentSessionId
required
string^ps_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: ps_01FCTS1XMKH9FF43CAFA4CXT3P

Payment Id to void

header Parameters
Account
string
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Responses

Response samples

Content type
application/json
{
  • "id": "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01J8HRD83WBRA473YJ01N4Z19W",
  • "paymentSessionId": "ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "amount": 30,
  • "currency": "GBP",
  • "type": "Void",
  • "status": "Succeeded",
  • "createdTimestamp": 1727172878,
  • "lastUpdatedTimestamp": 1727172878
}

Refund an already captured payment

Use this endpoint to refund an already captured payment session. Unlike voids, which are typically completed in minutes, refunds can take several days to be cleared by the card schemes.

Authorizations:
secretApiKeyAuth
path Parameters
paymentSessionId
required
string

Payment Id to refund

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

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

Request Body schema: application/json
amount
integer <int32> [ 30 .. 2000000 ]

The amount to refund in minor digits. Can be omitted when not using partial captures or splits; the remaining amount will be refunded.

reason
string

The reason for the refund

refundPlatformFee
boolean or null

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.

object or null
object or null

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.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 250
}

Response samples

Content type
application/json
{
  • "id": "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01J8HRF73YD8VTP247ZRMT6E0B",
  • "paymentSessionId": "ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "amount": 30,
  • "currency": "GBP",
  • "type": "Refund",
  • "status": "Succeeded",
  • "reason": "Requested by customer",
  • "createdTimestamp": 1727172977,
  • "lastUpdatedTimestamp": 1727172977
}

Webhooks

Create and manage webhooks.

Signatures

As an additional security measure, you can verify the integrity of any webhook event you receive by checking the signature we provide within the Signature header. To do this simply take the webhook endpoint secret and HMAC-SHA256 the request body. If the signatures are not equal then you may want to discard the message.

Retry Policy

If your webhook URL begins to fail we will start our retry mechanism. For each failing event we immediately retry several times before then retrying with an increasing delay until we've exhausted the maximum number of attempts. Each retry happens after (0, 1, 5, 10, 10, 10 minutes)

Create/Register a webhook endpoint

Create/Register a webhook endpoint to start receiving events

Authorizations:
secretApiKeyAuth
Request Body schema: application/json
url
string

The URL of your webhook endpoint to register

active
boolean

Whether the endpoint is active (receiving events) or not

eventTypes
Array of strings (EventType)
Items Enum: "PaymentSession.approved" "PaymentSession.captured" "PaymentSession.declined" "PaymentSession.voided" "PaymentSession.void_failed" "PaymentSession.refunded" "PaymentSession.refund_failed" "PaymentSession.requires_action" "Account.created" "Account.updated" "Account.verification_status_updated" "Person.created" "Person.updated" "Person.deleted" "PayoutMethod.created" "PayoutMethod.updated" "PayoutMethod.deleted" "Payout.created" "Payout.status_updated" "Customer.created" "Customer.updated" "Customer.deleted" "Subscription.created" "Subscription.updated" "Subscription.cancelled" "Subscription.past_due" "Subscription.ended" "Transfer.created" "Transfer.updated" "Dispute.created" "Dispute.closed" "Dispute.challenged" "PlatformFee.created" "PlatformFee.refunded"

The event types you want the endpoint to receive

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "secret": "whs_0f6b1b5a-aef0-4011-978b-19fd4a4d46ea",
  • "id": "wh_31fba123-0fef-41d6-92ad-fd7089f49f8a",
  • "active": true,
  • "eventTypes": [
    ],
  • "createdTimestamp": 1470989538
}

List your webhook endpoints

Returns a list of your webhook endpoints. They are returned in sorted (by epoch) order (default is newest first).

Authorizations:
secretApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve a webhook endpoint

This is used to fetch a webhook by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
webhookId
required
string
Example: wh_01FCTS1XMKH9FF43CAFA4CXT3P

Webhook Id to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "wh_31fba123-0fef-41d6-92ad-fd7089f49f8a",
  • "active": true,
  • "eventTypes": [
    ],
  • "createdTimestamp": 1470989538
}

Update a webhook endpoint

This is used to update a webhook by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
webhookId
required
string
Example: wh_01FCTS1XMKH9FF43CAFA4CXT3P

Webhook Id to update

Request Body schema: application/json
url
string

The new URL of your webhook endpoint

active
boolean

Whether the endpoint is active (receiving events) or not

eventTypes
Array of strings (EventType)
Items Enum: "PaymentSession.approved" "PaymentSession.captured" "PaymentSession.declined" "PaymentSession.voided" "PaymentSession.void_failed" "PaymentSession.refunded" "PaymentSession.refund_failed" "PaymentSession.requires_action" "Account.created" "Account.updated" "Account.verification_status_updated" "Person.created" "Person.updated" "Person.deleted" "PayoutMethod.created" "PayoutMethod.updated" "PayoutMethod.deleted" "Payout.created" "Payout.status_updated" "Customer.created" "Customer.updated" "Customer.deleted" "Subscription.created" "Subscription.updated" "Subscription.cancelled" "Subscription.past_due" "Subscription.ended" "Transfer.created" "Transfer.updated" "Dispute.created" "Dispute.closed" "Dispute.challenged" "PlatformFee.created" "PlatformFee.refunded"

The event types you want the endpoint to receive

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "wh_31fba123-0fef-41d6-92ad-fd7089f49f8a",
  • "active": true,
  • "eventTypes": [
    ],
  • "createdTimestamp": 1470989538
}

Delete a webhook endpoint

This is used to delete a webhook by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
webhookId
required
string
Example: wh_01FCTS1XMKH9FF43CAFA4CXT3P

Webhook Id to delete

Responses

Response samples

Content type
application/json
{
  • "id": "wh_31fba123-0fef-41d6-92ad-fd7089f49f8a"
}

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.

Retrieves events in sorted (by epoch) order

Retrieves a list of events. They are returned in sorted (by epoch) order (default is newest first). You can query one of your sub-account's events buy using the Account header.

Authorizations:
secretApiKeyAuth
query Parameters
ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the events are returned. false will arrange the results with newest first whereas true shows oldest first.

limit
integer <int32>
Example: limit=20

Control how many items are returned in the result list. The max limit we allow is 50.

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

The linked accountId (use this when you want to fetch events related to a linked account)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve an Event by Id

This is used to fetch an Event by its eventId

Authorizations:
secretApiKeyAuth
path Parameters
eventId
required
string
Example: ev_01FCTS1XMKH9FF43CAFA4CXT3P

Event to retrieve

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

The linked accountId (use this when you want to fetch events related to a linked account)

Responses

Response samples

Content type
application/json
{
  • "id": "ev_01FGNPAY1DB5TKPB35M1MNT6PN",
  • "eventType": "PaymentSession.approved",
  • "data": {
    },
  • "endpoints": [
    ],
  • "accountId": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
  • "createdTimestamp": 1570989538
}

Accounts

Account registration for your sub accounts

Creates a new account that is connected to your account as a 'sub' type

This is for registering new users onto your platform that will act as one of your 'sub' accounts

Authorizations:
secretApiKeyAuth
Request Body schema: application/json
(AccountOnboardingFlow (string or null))

The flow that this account will use to be onboarded. Hosted accounts will be onboarded via the Ryft portal and cannot be updated via the API. NonHosted accounts will be onboarded via the API and will not have access to the Ryft portal. Once defined this value cannot be changed. Defaults to Hosted if not provided.

email
string or null <email> <= 200 characters

The main email address for the sub account.

Required if onboardingFlow is Hosted and you are not supplying the 'entityType', otherwise you can supply this in the 'business'/'individual' block. Not required if onboardingFlow is NonHosted - any value supplied will be ignored.

(AccountEntityType (string or null))

The type of entity that this account is - either a registered business or an individual person (sole trader). Optional if onboardingFlow is Hosted, though certain actions will be restricted until this is provided (creating persons, payout methods and therefore payouts). Optional if onboardingFlow is NonHosted, any values supplied can be updated by the account via the Ryft portal.

(CreateBusinessRequest (object or null))

The details of the business. Required if entityType is Business

(CreateIndividualRequest (object or null))

The details of the person. Required if entityType is Individual

metadata
object or null

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

(AccountSettingsRequest (object or null))

Settings for the account.

(AccountTermsOfServiceRequest (object or null))

Use this parameter to indicate acceptance of our terms & conditions by the sub account.

Responses

Request samples

Content type
application/json
Example
{
  • "email": "test@example.com"
}

Response samples

Content type
application/json
{
  • "id": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
  • "type": "Standard",
  • "status": "ActionRequired",
  • "actionsRequired": [
    ],
  • "frozen": false,
  • "email": "user@example.com",
  • "onboardingFlow": "Hosted",
  • "entityType": "Business",
  • "business": {
    },
  • "individual": {
    },
  • "verification": {
    },
  • "metadata": {
    },
  • "settings": {
    },
  • "capabilities": {
    },
  • "termsOfService": {
    },
  • "createdTimestamp": 1470989538
}

Retrieve a sub account by it's id

This is used to fetch details for one of your sub accounts.

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

Responses

Response samples

Content type
application/json
{
  • "id": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
  • "type": "Standard",
  • "status": "ActionRequired",
  • "actionsRequired": [
    ],
  • "frozen": false,
  • "email": "user@example.com",
  • "onboardingFlow": "Hosted",
  • "entityType": "Business",
  • "business": {
    },
  • "individual": {
    },
  • "verification": {
    },
  • "metadata": {
    },
  • "settings": {
    },
  • "capabilities": {
    },
  • "termsOfService": {
    },
  • "createdTimestamp": 1470989538
}

Updates one of your sub accounts

This is used to update the details of one of your sub accounts. This API can only be accessed for NonHosted sub accounts.

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

Request Body schema: application/json

The request for updating an account

(AccountEntityType (string or null))

The type of entity that this account is - either a registered business or an individual person (sole trader). Can only be supplied on update for 'NonHosted' accounts that were not created with one. This cannot be changed once set.

(UpdateBusinessRequest (object or null))

The details to update if the entityType is Business

(UpdateIndividualRequest (object or null))

The details to update if the entityType is Individual

metadata
object or null

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

(AccountSettingsRequest (object or null))

Settings to update on the account.

(AccountTermsOfServiceRequest (object or null))

Information relating to terms of service.

(AccountCapabilitiesRequest (object or null))

Specific capabilities you want to request for the account. Note that this field can only be used standalone in your request. Specifying other fields (e.g. settings) will cause the request to be rejected.

Responses

Request samples

Content type
application/json
{
  • "entityType": "Business",
  • "business": {
    },
  • "individual": {
    },
  • "metadata": {
    },
  • "settings": {
    },
  • "termsOfService": {
    },
  • "capabilities": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
  • "type": "Standard",
  • "status": "ActionRequired",
  • "actionsRequired": [
    ],
  • "frozen": false,
  • "email": "user@example.com",
  • "onboardingFlow": "Hosted",
  • "entityType": "Business",
  • "business": {
    },
  • "individual": {
    },
  • "verification": {
    },
  • "metadata": {
    },
  • "settings": {
    },
  • "capabilities": {
    },
  • "termsOfService": {
    },
  • "createdTimestamp": 1470989538
}

Submits the sub account details of a `Business` entity for verification

Once you have created all Persons and satisfied all the verification requirements for them and the Business, you submit these details for verification. This endpoint cannot be accessed for Individual sub accounts as this process is done automatically after satisfying the verification requirements.

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

Responses

Response samples

Content type
application/json
{
  • "id": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
  • "type": "Standard",
  • "status": "ActionRequired",
  • "actionsRequired": [
    ],
  • "frozen": false,
  • "email": "user@example.com",
  • "onboardingFlow": "Hosted",
  • "entityType": "Business",
  • "business": {
    },
  • "individual": {
    },
  • "verification": {
    },
  • "metadata": {
    },
  • "settings": {
    },
  • "capabilities": {
    },
  • "termsOfService": {
    },
  • "createdTimestamp": 1470989538
}

Creates a manual payout for the specified sub account

Used to create manual payouts for a specified sub account. This API can only be accessed for NonHosted sub accounts that are configured for manual payouts. Note that the following requirements must be met:

  • the payoutMethodId supplied must have status equal to Valid
  • amount must be greater than or equal to the minimum configured payout amount for the account (e.g. £100)
  • verification.status cannot be Required on the account
  • frozen must not be true on the account
Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

Request Body schema: application/json
amount
required
integer <int32>

The amount (in minor units) to payout

currency
required
string <= 3 characters

The three-letter ISO currency code

payoutMethodId
required
string^pm_[0-7][0-9A-HJKMNP-TV-Z]{25}

The payout method to send the payout amount to

metadata
object or null

Used to attach any custom key-value data to the payout. You can have a maximum of 5 pieces of metadata.

Responses

Request samples

Content type
application/json
{
  • "amount": 5000,
  • "currency": "GBP",
  • "payoutMethodId": "pm_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "po_01FJ1H0023R1AHM77YQ75RMKE7",
  • "paymentsTakenDate": "2021-10-14",
  • "paymentsTakenDateFrom": "2021-10-14",
  • "paymentsTakenDateTo": "2021-10-14",
  • "amount": 9750,
  • "currency": "GBP",
  • "status": "Completed",
  • "scheduleType": "Automatic",
  • "payoutMethod": {
    },
  • "failureReason": "InvalidPayoutMethod",
  • "payoutCalculation": {
    },
  • "scheme": "Ach",
  • "createdTimestamp": 1631696701,
  • "scheduledTimestamp": 1631696701,
  • "completedTimestamp": 1631696701,
  • "metadata": {
    }
}

Gets payouts for the sub account

Used to fetch a paginated list of payouts for the given sub account

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

query Parameters
ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the payouts are returned. false will arrange the results with newest first whereas true shows oldest first.

limit
integer <int32>
Default: 20
Example: limit=20

Control how many payouts are returned in the result list. The max limit we allow is 50.

startsAfter
string
Example: startsAfter=po_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here in order to retrieve the next page of results.

startDate
string <date>
Deprecated

The date when payments were taken to search for payouts from (inclusive), in the format yyyy-MM-dd

endDate
string <date>
Deprecated

The date when payments were taken to search for payouts to (inclusive), in the format yyyy-MM-dd

startTimestamp
integer <int64>
Example: startTimestamp=1641859200

The start timestamp (inclusive), it must be before the endTimestamp.

endTimestamp
integer <int64>
Example: endTimestamp=1641945599

The timestamp when to return payouts up to (inclusive), it must be after the startTimestamp.

Responses

Response samples

Content type
application/json
{
  • "payouts": [
    ],
  • "paginationToken": "po_01FCTS1XMKH9FF43CAFA4CXT3P"
}

Retrieve a payout by Id

This is used to fetch a payout by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

payoutId
required
string^po_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: po_01FCTS1XMKH9FF43CAFA4CXT3P

Payout to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "po_01FJ1H0023R1AHM77YQ75RMKE7",
  • "paymentsTakenDate": "2021-10-14",
  • "paymentsTakenDateFrom": "2021-10-14",
  • "paymentsTakenDateTo": "2021-10-14",
  • "amount": 9750,
  • "currency": "GBP",
  • "status": "Completed",
  • "scheduleType": "Automatic",
  • "payoutMethod": {
    },
  • "failureReason": "InvalidPayoutMethod",
  • "payoutCalculation": {
    },
  • "scheme": "Ach",
  • "createdTimestamp": 1631696701,
  • "scheduledTimestamp": 1631696701,
  • "completedTimestamp": 1631696701,
  • "metadata": {
    }
}

Creates a link at which the user can sign in to their existing Ryft account to authorize with your platform.

We recommend calling this endpoint first when you onboard your users to cater for those that may already have Ryft accounts. If the email supplied is not registered with Ryft then you should instead use our account-links API to register a new user. This API can only be accessed for Hosted sub accounts.

Authorizations:
secretApiKeyAuth
Request Body schema: application/json
email
string <email> <= 200 characters

The main email address for the account

redirectUrl
string

The URL to redirect back to once the customer has authenticated (success/fail). We will append the accountId under query parameter account for the customer onto your redirectUrl once they successfully authenticate. You should check for this parameter once the customer returns and store it for future use.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Persons

The Persons API allows the creation and management of one or more persons for the purpose of verification for Business sub accounts. Recommended if you wish to implement verification programmatically for your sub accounts. This API cannot be accessed for Individual sub accounts.

Creates a new person under the account, for verification of Businesses

This is for creating persons under your or your sub accounts account, required for verification of businesses. The following limits apply: - Maximum of 9 persons - Maximum of 5 persons with a role of Director - Maximum of 4 persons with a role of UltimateBeneficialOwner - Maximum of 1 person with a role of BusinessContact

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

Request Body schema: application/json
firstName
string [ 1 .. 50 ] characters

The first name of the person

middleNames
string or null [ 1 .. 50 ] characters

The middle names of the person

lastName
string [ 1 .. 50 ] characters

The last name / surname of the person

email
string <email> [ 1 .. 100 ] characters

The email address of the person

dateOfBirth
string = 10 characters

The date of birth of the person, in format YYYY-MM-DD

countryOfBirth
string or null = 2 characters

The two-character ISO 3166 country code of birth of the person

gender
string
Enum: "Female" "Male"

The gender of the person. International regulations require either Female or Male

nationalities
Array of strings[ items = 2 characters ]

The countries of citizenship or nationality of the person

AccountAddress (object)

The address of the person

phoneNumber
string [ 1 .. 17 ] characters

The phone number of the person, in E.164 format

businessRoles
Array of strings (BusinessRole)
Items Enum: "BusinessContact" "Director" "UltimateBeneficialOwner"

The role(s) in the business that the person performs. This must contain at least one value.

Array of AccountDocumentRequest (object) or null

The KYC documents. Note that a maximum of 1 of each document type can exist at any time, if you add a new document of a type that already exists then it will be replaced, regardless of it's status.

metadata
object or null

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

Responses

Request samples

Content type
application/json
{
  • "firstName": "Fred",
  • "middleNames": "David",
  • "lastName": "Jones",
  • "email": "fred.jones@example.com",
  • "dateOfBirth": "1990-01-20",
  • "countryOfBirth": "GB",
  • "gender": "Male",
  • "nationalities": [
    ],
  • "address": {
    },
  • "phoneNumber": "string",
  • "businessRoles": [
    ],
  • "documents": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "per_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "firstName": "Fred",
  • "middleNames": "David",
  • "lastName": "Jones",
  • "email": "fred.jones@example.com",
  • "dateOfBirth": "1990-01-20",
  • "countryOfBirth": "GB",
  • "gender": "Male",
  • "nationalities": [
    ],
  • "address": {
    },
  • "phoneNumber": "string",
  • "businessRoles": [
    ],
  • "verification": {
    },
  • "documents": [
    ],
  • "metadata": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Retrieves persons in sorted (by epoch) order

Retrieves a list of the persons you've created for one of your sub accounts They are returned in sorted (by epoch) order (default is newest first)

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

query Parameters
ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the persons are returned. false will arrange the results with newest first whereas true shows oldest first.

limit
integer <int32>
Example: limit=20

Control how many persons are returned in the result list. The max limit we allow is 50.

startsAfter
string
Example: startsAfter=per_01FCTS1XMKH9FF43CAFA4CXT3P

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "paginationToken": "per_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"
}

Retrieve a person by Id

This is used to fetch a person by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

personId
required
string^per_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: per_01FCTS1XMKH9FF43CAFA4CXT3P

Person to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "per_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "firstName": "Fred",
  • "middleNames": "David",
  • "lastName": "Jones",
  • "email": "fred.jones@example.com",
  • "dateOfBirth": "1990-01-20",
  • "countryOfBirth": "GB",
  • "gender": "Male",
  • "nationalities": [
    ],
  • "address": {
    },
  • "phoneNumber": "string",
  • "businessRoles": [
    ],
  • "verification": {
    },
  • "documents": [
    ],
  • "metadata": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Update a person by Id

This is used to update an existing person

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

personId
required
string^per_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: per_01FCTS1XMKH9FF43CAFA4CXT3P

Person to update

Request Body schema: application/json
firstName
string or null [ 1 .. 50 ] characters

The first name of the person

middleNames
string or null [ 1 .. 50 ] characters

The middle names of the person

lastName
string or null [ 1 .. 50 ] characters

The last name / surname of the person

email
string or null <email> [ 1 .. 100 ] characters

The email address of the person

dateOfBirth
string or null = 10 characters

The date of birth of the person, in format YYYY-MM-DD

countryOfBirth
string or null = 2 characters

The two-character ISO 3166 country code of birth of the person

gender
string or null
Enum: "Female" "Male"

The gender of the person. International regulations require either Female or Male

nationalities
Array of strings or null

The countries of citizenship or nationality of the person

(AccountAddress (object or null))

The address of the person

phoneNumber
string or null [ 1 .. 17 ] characters

The phone number of the person, in E.164 format

businessRoles
Array of strings (BusinessRole)
Items Enum: "BusinessContact" "Director" "UltimateBeneficialOwner"

The role(s) in the business that the person performs. This must contain at least one value.

Array of AccountDocumentRequest (object) or null

The KYC documents. Note that a maximum of 1 of each document type can exist at any time, if you add a new document of a type that already exists then it will be replaced, regardless of it's status.

metadata
object or null

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

Responses

Request samples

Content type
application/json
{
  • "firstName": "Fred",
  • "middleNames": "David",
  • "lastName": "Jones",
  • "email": "fred.jones@example.com",
  • "dateOfBirth": "1990-01-20",
  • "countryOfBirth": "GB",
  • "gender": "Male",
  • "nationalities": [
    ],
  • "address": {
    },
  • "phoneNumber": "+447900000000",
  • "businessRoles": [
    ],
  • "documents": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "per_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "firstName": "Fred",
  • "middleNames": "David",
  • "lastName": "Jones",
  • "email": "fred.jones@example.com",
  • "dateOfBirth": "1990-01-20",
  • "countryOfBirth": "GB",
  • "gender": "Male",
  • "nationalities": [
    ],
  • "address": {
    },
  • "phoneNumber": "string",
  • "businessRoles": [
    ],
  • "verification": {
    },
  • "documents": [
    ],
  • "metadata": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Deletes a person by Id

Deletes a person under the account. This will also delete any files currently attached to the person. Note that you can only delete a person if verification.status is NotRequired or Required

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

personId
required
string^per_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: per_01FCTS1XMKH9FF43CAFA4CXT3P

Person to delete

Responses

Response samples

Content type
application/json
{
  • "id": "per_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "firstName": "Fred",
  • "middleNames": "David",
  • "lastName": "Jones",
  • "email": "fred.jones@example.com",
  • "dateOfBirth": "1990-01-20",
  • "countryOfBirth": "GB",
  • "gender": "Male",
  • "nationalities": [
    ],
  • "address": {
    },
  • "phoneNumber": "string",
  • "businessRoles": [
    ],
  • "verification": {
    },
  • "documents": [
    ],
  • "metadata": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Payout Methods

The Payout Methods API allows the creation and management of payout methods for use when receiving payouts, e.g. bank accounts. Recommended if you wish to implement payouts programmatically for your sub accounts.

Creates a new payout method for a sub account

This is for creating payout methods for one of your sub accounts, so they can receive payouts. You can only create 1 payout method per currency

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

Request Body schema: application/json
type
string (PayoutMethodType)
Value: "BankAccount"
displayName
string or null

A friendly name for the payout method, for display only

currency
string = 3 characters

The three-character ISO 4217 currency code of the payout method. The currencies available here are the same as are available for making payments.

country
string = 2 characters

The two-character ISO 3166 country code of the payout method. Only certain countries are supported for a given currency

object (BankAccountRequest)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "BankAccount",
  • "currency": "GBP",
  • "country": "GB",
  • "bankAccount": {
    }
}

Response samples

Content type
application/json
{
  • "id": "pm_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "type": "BankAccount",
  • "displayName": "string",
  • "status": "Valid",
  • "invalidReason": "string",
  • "currency": "GBP",
  • "country": "GB",
  • "bankAccount": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Retrieves payout methods in sorted (by epoch) order

Retrieves a list of the payout methods you've created for one of your sub accounts They are returned in sorted (by epoch) order (default is newest first)

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

query Parameters
ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the payout methods are returned. false will arrange the results with newest first whereas true shows oldest first

limit
integer <int32>
Example: limit=10

Control how many items are return in a given page The max limit we allow is 25. The default is 10.

startsAfter
string
Example: startsAfter=pm_01FCTS1XMKH9FF43CAFA4CXT3P

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve a payout method by Id

This is used to fetch a payout method by its unique Id for one of your sub accounts

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

payoutMethodId
required
string^pm_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: pm_01FCTS1XMKH9FF43CAFA4CXT3P

Payout method to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "pm_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "type": "BankAccount",
  • "displayName": "string",
  • "status": "Valid",
  • "invalidReason": "string",
  • "currency": "GBP",
  • "country": "GB",
  • "bankAccount": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Update a payout method by Id

This is used to update an existing payout method for one of your sub accounts

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

payoutMethodId
required
string^pm_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: pm_01FCTS1XMKH9FF43CAFA4CXT3P

Payout method to retrieve

Request Body schema: application/json
displayName
string or null

A friendly name for the payout method, for display only

(BankAccountRequest (object or null))

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "bankAccount": {
    }
}

Response samples

Content type
application/json
{
  • "id": "pm_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "type": "BankAccount",
  • "displayName": "string",
  • "status": "Valid",
  • "invalidReason": "string",
  • "currency": "GBP",
  • "country": "GB",
  • "bankAccount": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Delete a payout method

This is used to delete a payout method by its unique Id for one of your sub accounts

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

payoutMethodId
required
string^pm_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: pm_01FCTS1XMKH9FF43CAFA4CXT3P

Payout method to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "pm_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "type": "BankAccount",
  • "displayName": "string",
  • "status": "Valid",
  • "invalidReason": "string",
  • "currency": "GBP",
  • "country": "GB",
  • "bankAccount": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

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.

Creates a manual payout for the specified sub account

Used to create manual payouts for a specified sub account. This API can only be accessed for NonHosted sub accounts that are configured for manual payouts. Note that the following requirements must be met:

  • the payoutMethodId supplied must have status equal to Valid
  • amount must be greater than or equal to the minimum configured payout amount for the account (e.g. £100)
  • verification.status cannot be Required on the account
  • frozen must not be true on the account
Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

Request Body schema: application/json
amount
required
integer <int32>

The amount (in minor units) to payout

currency
required
string <= 3 characters

The three-letter ISO currency code

payoutMethodId
required
string^pm_[0-7][0-9A-HJKMNP-TV-Z]{25}

The payout method to send the payout amount to

metadata
object or null

Used to attach any custom key-value data to the payout. You can have a maximum of 5 pieces of metadata.

Responses

Request samples

Content type
application/json
{
  • "amount": 5000,
  • "currency": "GBP",
  • "payoutMethodId": "pm_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "po_01FJ1H0023R1AHM77YQ75RMKE7",
  • "paymentsTakenDate": "2021-10-14",
  • "paymentsTakenDateFrom": "2021-10-14",
  • "paymentsTakenDateTo": "2021-10-14",
  • "amount": 9750,
  • "currency": "GBP",
  • "status": "Completed",
  • "scheduleType": "Automatic",
  • "payoutMethod": {
    },
  • "failureReason": "InvalidPayoutMethod",
  • "payoutCalculation": {
    },
  • "scheme": "Ach",
  • "createdTimestamp": 1631696701,
  • "scheduledTimestamp": 1631696701,
  • "completedTimestamp": 1631696701,
  • "metadata": {
    }
}

Gets payouts for the sub account

Used to fetch a paginated list of payouts for the given sub account

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

query Parameters
ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the payouts are returned. false will arrange the results with newest first whereas true shows oldest first.

limit
integer <int32>
Default: 20
Example: limit=20

Control how many payouts are returned in the result list. The max limit we allow is 50.

startsAfter
string
Example: startsAfter=po_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here in order to retrieve the next page of results.

startDate
string <date>
Deprecated

The date when payments were taken to search for payouts from (inclusive), in the format yyyy-MM-dd

endDate
string <date>
Deprecated

The date when payments were taken to search for payouts to (inclusive), in the format yyyy-MM-dd

startTimestamp
integer <int64>
Example: startTimestamp=1641859200

The start timestamp (inclusive), it must be before the endTimestamp.

endTimestamp
integer <int64>
Example: endTimestamp=1641945599

The timestamp when to return payouts up to (inclusive), it must be after the startTimestamp.

Responses

Response samples

Content type
application/json
{
  • "payouts": [
    ],
  • "paginationToken": "po_01FCTS1XMKH9FF43CAFA4CXT3P"
}

Retrieve a payout by Id

This is used to fetch a payout by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_b83f2653-06d7-44a9-a548-5825e8186004

the account id of one of your sub accounts

payoutId
required
string^po_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: po_01FCTS1XMKH9FF43CAFA4CXT3P

Payout to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "po_01FJ1H0023R1AHM77YQ75RMKE7",
  • "paymentsTakenDate": "2021-10-14",
  • "paymentsTakenDateFrom": "2021-10-14",
  • "paymentsTakenDateTo": "2021-10-14",
  • "amount": 9750,
  • "currency": "GBP",
  • "status": "Completed",
  • "scheduleType": "Automatic",
  • "payoutMethod": {
    },
  • "failureReason": "InvalidPayoutMethod",
  • "payoutCalculation": {
    },
  • "scheme": "Ach",
  • "createdTimestamp": 1631696701,
  • "scheduledTimestamp": 1631696701,
  • "completedTimestamp": 1631696701,
  • "metadata": {
    }
}

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

Initiates a transfer of money between Ryft accounts

Used to initiate a transfer of money between Ryft accounts.

Authorizations:
secretApiKeyAuth
Request Body schema: application/json
amount
required
integer <int32> [ 1 .. 3000000 ]

The amount (in minor units) to transfer

currency
required
string <= 3 characters

The three-letter ISO currency code

object or null

Where the amount should be taken from.

Note that you cannot specify both source & destination. A request in which source is specified will initiate a transfer from the supplied sub account to your own platform account.

  • the sub account's balance will be decremented
  • your platform account balance will be incremented
object or null

Where the amount should be credited to.

Note that you cannot specify both source & destination. A request in which destination is specified will initiate a transfer to the supplied sub account from your own platform account.

  • the sub account's balance will be incremented
  • your platform account balance will be decremented
reason
string or null [ 1 .. 250 ] characters

An optional reason describing why the transfer was initiated. Not required but recommended.

metadata
object or null

Used to attach any custom key-value data to the transfer. You can have a maximum of 5 pieces of metadata.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 1500,
  • "currency": "GBP",
  • "destination": {
    },
  • "reason": "Money owed from payments on 2012-01-30"
}

Response samples

Content type
application/json
{
  • "id": "tfr_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "status": "Pending",
  • "amount": 0,
  • "currency": "GBP",
  • "reason": "Covering dispute fees of £25 from 25th October",
  • "source": {
    },
  • "destination": {
    },
  • "errors": [
    ],
  • "metadata": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Fetches a paginated list of your transfers

Retrieves a list of the transfers you've requested. Returned in sorted (by epoch) order (default is newest first)

Authorizations:
secretApiKeyAuth
query Parameters
ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the transfers are returned. false will arrange the results with newest first whereas true shows oldest first

limit
integer <int32>
Default: 20
Example: limit=20

Control how many transfers are returned in the result list. The max limit we allow is 50.

startsAfter
string
Example: startsAfter=tfr_01FCTS1XMKH9FF43CAFA4CXT3P

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here in order to retrieve the next page of results.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "paginationToken": "tfr_01FCTS1XMKH9FF43CAFA4CXT3P"
}

Retrieve a transfer by Id

This is used to fetch a transfer by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string^tfr_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: tfr_01FCTS1XMKH9FF43CAFA4CXT3P

Transfer to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "tfr_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "status": "Pending",
  • "amount": 0,
  • "currency": "GBP",
  • "reason": "Covering dispute fees of £25 from 25th October",
  • "source": {
    },
  • "destination": {
    },
  • "errors": [
    ],
  • "metadata": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Generate a new temporary account link

Generate a temporary account link to redirect the user to, in order for them to complete registration and payout setup via our portal

Authorizations:
secretApiKeyAuth
Request Body schema: application/json
accountId
string

The account id for which the payout verification is required

redirectUrl
string

The URL to redirect back to on completion or cancelation of the verification detail

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Platform Fees

Query any platform fees that your account has taken (when taking payments on behalf of linked sub accounts)

Retrieves your platform fees in sorted (by epoch) order

Retrieves a list of the application fees you've collected. They are returned in sorted (by epoch) order (default is newest first)

Authorizations:
secretApiKeyAuth
query Parameters
ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the platform fees are returned. false will arrange the results with newest first whereas true shows oldest first

limit
integer <int32>
Example: limit=20

Control how many platform-fees are returned in the result list. The max limit we allow is 50.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve a platform fee by Id

This is used to fetch a platform fee by its platformFeeId

Authorizations:
secretApiKeyAuth
path Parameters
platformFeeId
required
string
Example: pf_01FCTS1XMKH9FF43CAFA4CXT3P

PlatformFee to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "pf_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "paymentSessionId": "ps_01JJPPAZTNN38EMDJ72FASHE7R",
  • "amount": 40,
  • "paymentAmount": 450,
  • "processingFee": 7,
  • "netAmount": 33,
  • "currency": "GBP",
  • "fromAccountId": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
  • "createdTimestamp": 1470989538
}

Retrieve platform fee refund(s)

This is used to fetch a platform fee refunds by their platformFeeId

Authorizations:
secretApiKeyAuth
path Parameters
platformFeeId
required
string
Example: pf_01FCTS1XMKH9FF43CAFA4CXT3P

PlatformFee to retrieve refunds for

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Customers

The Customers API allows you to persist customer details across sessions. You should use this if you wish to support saving a customer's payment methods and thereby enabling them to reuse previously entered details for future payments.

Creates a new customer within your account

This is for creating customers within your Ryft account (to enable features such as saved payment methods)

Authorizations:
secretApiKeyAuth
Request Body schema: application/json
email
required
string <email> <= 200 characters

The customer's email address. Note that these must be unique and are case insensitive

firstName
string or null [ 1 .. 80 ] characters

The first name of the customer

lastName
string or null [ 1 .. 80 ] characters

The last name of the customer

homePhoneNumber
string or null

The home phone number of the customer. Must be in E.164 format

mobilePhoneNumber
string or null

The mobile phone number of the customer. Must be in E.164 format

metadata
object or null

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

Responses

Request samples

Content type
application/json
{
  • "email": "example@example.com",
  • "firstName": "Jeff",
  • "lastName": "Bridges",
  • "homePhoneNumber": "+447900000000",
  • "mobilePhoneNumber": "+447900000000",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "email": "user@example.com",
  • "firstName": "Jeff",
  • "lastName": "Bridges",
  • "homePhoneNumber": "+447900000000",
  • "mobilePhoneNumber": "+447900000000",
  • "defaultPaymentMethod": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "metadata": {
    },
  • "createdTimestamp": 1470989538
}

List customers

Used to fetch a paginated list of one or more Customers

Authorizations:
secretApiKeyAuth
query Parameters
email
string
Example: email=example@mail.com

A case insensitive email to search by. Note that emails are unique per Customer so you can expect a single item within the response. Any other query parameters will be ignored if this is provided.

startTimestamp
integer <int64>
Example: startTimestamp=1641859200

The start timestamp (inclusive), it must be before the endTimestamp.

endTimestamp
integer <int64>
Example: endTimestamp=1641945599

The timestamp when to return payment sessions up to (inclusive), it must be after the startTimestamp.

ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the items are returned. false will arrange the results with newest first, whereas true shows oldest first. The default is false.

limit
integer <int32>
Example: limit=10

Control how many items are return in a given page The max limit we allow is 25. The default is 10.

startsAfter
string
Example: startsAfter=cus_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results for that timestamp range.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "paginationToken": "cus_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"
}

Retrieve a customer by Id

This is used to fetch a customer by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
customerId
required
string^cus_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: cus_01FCTS1XMKH9FF43CAFA4CXT3P

Customer to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "email": "user@example.com",
  • "firstName": "Jeff",
  • "lastName": "Bridges",
  • "homePhoneNumber": "+447900000000",
  • "mobilePhoneNumber": "+447900000000",
  • "defaultPaymentMethod": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "metadata": {
    },
  • "createdTimestamp": 1470989538
}

Update a customer by Id

This is used to update an existing customer

Authorizations:
secretApiKeyAuth
path Parameters
customerId
required
string^cus_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: cus_01FCTS1XMKH9FF43CAFA4CXT3P

Customer to update

Request Body schema: application/json
firstName
string or null [ 1 .. 80 ] characters

The first name of the customer

lastName
string or null [ 1 .. 80 ] characters

The last name of the customer

homePhoneNumber
string or null

The home phone number of the customer. Must be in E.164 format

mobilePhoneNumber
string or null

The mobile phone number of the customer. Must be in E.164 format

metadata
object or null

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

defaultPaymentMethod
string or null

The Id of the customer's preferred/default payment method

Responses

Request samples

Content type
application/json
{
  • "firstName": "Jeff",
  • "lastName": "Bridges",
  • "homePhoneNumber": "+447900000000",
  • "mobilePhoneNumber": "+447900000000",
  • "metadata": {
    },
  • "defaultPaymentMethod": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"
}

Response samples

Content type
application/json
{
  • "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "email": "user@example.com",
  • "firstName": "Jeff",
  • "lastName": "Bridges",
  • "homePhoneNumber": "+447900000000",
  • "mobilePhoneNumber": "+447900000000",
  • "defaultPaymentMethod": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "metadata": {
    },
  • "createdTimestamp": 1470989538
}

Delete a customer (and all their payment methods)

This is used to delete a customer by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
customerId
required
string^cus_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: cus_01FCTS1XMKH9FF43CAFA4CXT3P

Customer to delete

Responses

Response samples

Content type
application/json
{
  • "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
}

Retrieve a customer's payment methods

This is used to fetch a customer's payment methods

Authorizations:
secretApiKeyAuth
path Parameters
customerId
required
string^cus_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: cus_01FCTS1XMKH9FF43CAFA4CXT3P

Customer whose payment methods to retrieve

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Payment Methods

The Payment Methods API allows you to tokenize and store previously used payment methods.

Retrieve a payment method by Id

This is used to fetch a payment method by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
paymentMethodId
required
string^pmt_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: pmt_01FCTS1XMKH9FF43CAFA4CXT3P

Payment Method to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "type": "Card",
  • "card": {
    },
  • "billingAddress": {
    },
  • "checks": {
    },
  • "customerId": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "createdTimestamp": 1470989538
}

Update a payment method by Id

This is used to update an existing payment method

Authorizations:
secretApiKeyAuth
path Parameters
paymentMethodId
required
string^pmt_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: pmt_01FCTS1XMKH9FF43CAFA4CXT3P

Payment Method to update

Request Body schema: application/json
object (CustomerAddress)

Responses

Request samples

Content type
application/json
{
  • "billingAddress": {
    }
}

Response samples

Content type
application/json
{
  • "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "type": "Card",
  • "card": {
    },
  • "billingAddress": {
    },
  • "checks": {
    },
  • "customerId": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "createdTimestamp": 1470989538
}

Delete a payment method by Id

This is used to delete a payment method by instead. Note that you can only delete payment-methods that aren't single-use. For example you can delete a customer's saved payment method, but you cannot delete a token generated for one-time purchases

Authorizations:
secretApiKeyAuth
path Parameters
paymentMethodId
required
string^pmt_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: pmt_01FCTS1XMKH9FF43CAFA4CXT3P

Payment Method to delete

Responses

Response samples

Content type
application/json
{
  • "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"
}

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.

Creates a new subscription

Use to create a Subscription (whereby Ryft manage the automatic scheduling and billing of a recurring payment series)

Authorizations:
secretApiKeyAuth
Request Body schema: application/json
object

The customer the subscription is for

required
object

Defines how much and how often to charge the customer for the subscription

object

Use if you want to select an already stored card on file for the subscription and skip collecting new payment details from your customer. Must belong to the customerId provided in this request. Note that 3DS will be required on the initial payment.

description
string or null

(optional) description that helps you personalise/identify the specific subscription

billingCycleTimestamp
number or null

The (epoch) timestamp representing the date on which the customer will regularly be billed. e.g. 15th of each month. Defaults to today if not provided.

metadata
object

use this parameter to attach key-value data to the subscription. These will be sent with any subscription events to your webhooks. You can have a maximum of 5 pieces of metadata.

(ShippingDetails (object or null))

The shipping details for the purchase/payment. This is optional but recommended to reduce fraudulent payments.

object or null

Settings for controlling fields/options on the underlying Payment Session's created by this subscription.

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "price": {
    },
  • "paymentMethod": {
    },
  • "description": "Bob's monthly gym membership",
  • "billingCycleTimestamp": 1631703901,
  • "metadata": {
    },
  • "shippingDetails": {
    },
  • "paymentSettings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "status": "Pending",
  • "description": "Bob's monthly gym membership",
  • "customer": {
    },
  • "paymentMethod": {
    },
  • "paymentSessions": {
    },
  • "price": {
    },
  • "balance": {
    },
  • "pausePaymentDetail": {
    },
  • "cancelDetail": {
    },
  • "billingDetail": {
    },
  • "shippingDetails": {
    },
  • "metadata": {
    },
  • "paymentSettings": {
    },
  • "createdTimestamp": 1470989538
}

List subscriptions

Used to fetch a paginated list of subscriptions

Authorizations:
secretApiKeyAuth
query Parameters
startTimestamp
integer <int64>
Example: startTimestamp=1641859200

The start timestamp (inclusive), it must be before the endTimestamp. If not provided will default to midnight on the current date (UTC).

endTimestamp
integer <int64>
Example: endTimestamp=1641945599

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

ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the subscriptions are returned. false will arrange the results with newest first, whereas true shows oldest first. The default is false.

limit
integer <int32>
Example: limit=10

Control how many items are return in a given page The max limit we allow is 25. The default is 10.

startsAfter
string
Example: startsAfter=sub_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results for that timestamp range.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "paginationToken": "sub_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"
}

Retrieve a subscription by Id

This is used to fetch a subscription by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
subscriptionId
required
string^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P

Subscription to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "status": "Pending",
  • "description": "Bob's monthly gym membership",
  • "customer": {
    },
  • "paymentMethod": {
    },
  • "paymentSessions": {
    },
  • "price": {
    },
  • "balance": {
    },
  • "pausePaymentDetail": {
    },
  • "cancelDetail": {
    },
  • "billingDetail": {
    },
  • "shippingDetails": {
    },
  • "metadata": {
    },
  • "paymentSettings": {
    },
  • "createdTimestamp": 1470989538
}

Updates a subscription by Id

Use to update a Subscription. Cannot be used if the Subscription is Cancelled or Ended.

Authorizations:
secretApiKeyAuth
path Parameters
subscriptionId
required
string^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P

Subscription to retrieve

Request Body schema: application/json
object or null

Defines how much and how often to charge the customer for the Subscription. At least one field should be specified. You can change just the amount OR the interval OR both. Note that merchants operating in the European Union must notify the customer 4 weeks in advance of any changes in pricing. You cannot update this field if the Subscription is Paused, PastDue, Cancelled or Ended. Any updates to the price will be reflected instantly but will only take effect in the next billing cycle

object or null

Update the payment method that will be charged throughout the subscription. This is useful if your customer wishes to change their card or if a previous card has expired. Note that changing this field will trigger the next payment to apply 3DS - check the requiredAction on the latest payment session. Changing this field whilst in PastDue will trigger a automatic retry at the next available opportunity - check the NextBillingTimestamp

description
string or null

(optional) description that helps you personalise/identify the specific subscription

billingCycleTimestamp
number or null

The (epoch) timestamp representing the date on which the customer will regularly be billed. e.g. 15th of each month. You can only update this field if the Subscription is Pending. If you update this field to today then a payment will be triggered immediately. Note: If you want to update this for an Active subscription then we recommend cancelling and re-creating the subscription.

metadata
object

use this parameter to attach key-value data to the subscription. These will be sent with any subscription events to your webhooks. You can have a maximum of 5 pieces of metadata.

(ShippingDetails (object or null))

The shipping details for the purchase/payment. We recommend updating this if the customer's address changes during their subscription.

object

Settings for controlling fields/options on the underlying Payment Session's created by this subscription.

Responses

Request samples

Content type
application/json
{
  • "price": {
    },
  • "paymentMethod": {
    },
  • "description": "Bob's monthly gym membership",
  • "billingCycleTimestamp": 1631703901,
  • "metadata": {
    },
  • "shippingDetails": {
    },
  • "paymentSettings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "status": "Pending",
  • "description": "Bob's monthly gym membership",
  • "customer": {
    },
  • "paymentMethod": {
    },
  • "paymentSessions": {
    },
  • "price": {
    },
  • "balance": {
    },
  • "pausePaymentDetail": {
    },
  • "cancelDetail": {
    },
  • "billingDetail": {
    },
  • "shippingDetails": {
    },
  • "metadata": {
    },
  • "paymentSettings": {
    },
  • "createdTimestamp": 1470989538
}

Pause a subscription by Id

Used to schedule a pause for a Subscription. Only 'Active' subscriptions can be paused, though the details for already 'Paused' subscriptions can also be edited. The subscription will remain in 'Active' and will be moved to 'Paused' when it was next due to be billed. The reason or duration of the pause can be edited by calling this endpoint again, even after it has moved to 'Paused'. After a pause is scheduled but whilst still in 'Active', the pause can be unscheduled via the 'unschedule' flag.

Authorizations:
secretApiKeyAuth
path Parameters
subscriptionId
required
string^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P

Subscription to pause

Request Body schema: application/json
reason
string or null

Optional field describing why the subscription is being paused.

resumeAtTimestamp
number or null <int64>

The epoch timestamp (seconds) when the subscription should resume collecting payments. If not specified, the subscription will remain paused indefinitely until a /resume API call is made.

unschedule
boolean or null

A flag used to unschedule an already scheduled pause, resulting in the customer being billed as normal (as they were before). This can only be 'true' if the subscription is still 'Active', a pause has been scheduled and no other fields are provided. To resume an already 'Paused' subscription then either update the 'resumeAtTimestamp' or call /resume.

Responses

Request samples

Content type
application/json
{
  • "reason": "Offering service for free to customer",
  • "resumeAtTimestamp": 1470989538,
  • "unschedule": true
}

Response samples

Content type
application/json
{
  • "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "status": "Pending",
  • "description": "Bob's monthly gym membership",
  • "customer": {
    },
  • "paymentMethod": {
    },
  • "paymentSessions": {
    },
  • "price": {
    },
  • "balance": {
    },
  • "pausePaymentDetail": {
    },
  • "cancelDetail": {
    },
  • "billingDetail": {
    },
  • "shippingDetails": {
    },
  • "metadata": {
    },
  • "paymentSettings": {
    },
  • "createdTimestamp": 1470989538
}

Resume a subscription by Id

Use to resume a paused Subscription.

Authorizations:
secretApiKeyAuth
path Parameters
subscriptionId
required
string^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P

Subscription to resume

Responses

Response samples

Content type
application/json
{
  • "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "status": "Pending",
  • "description": "Bob's monthly gym membership",
  • "customer": {
    },
  • "paymentMethod": {
    },
  • "paymentSessions": {
    },
  • "price": {
    },
  • "balance": {
    },
  • "pausePaymentDetail": {
    },
  • "cancelDetail": {
    },
  • "billingDetail": {
    },
  • "shippingDetails": {
    },
  • "metadata": {
    },
  • "paymentSettings": {
    },
  • "createdTimestamp": 1470989538
}

Cancel a subscription by Id

Cancel a subscription by its unique Id. This will immediately move the subscription to Cancelled and stop billing the customer. This state is terminal and cannot be reversed.

Authorizations:
secretApiKeyAuth
path Parameters
subscriptionId
required
string^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P

Subscription to cancel

Request Body schema: application/json
reason
string or null

Optional field describing why the subscription is being cancelled.

Responses

Request samples

Content type
application/json
{
  • "reason": "Customer no longer wants service"
}

Response samples

Content type
application/json
{
  • "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "status": "Pending",
  • "description": "Bob's monthly gym membership",
  • "customer": {
    },
  • "paymentMethod": {
    },
  • "paymentSessions": {
    },
  • "price": {
    },
  • "balance": {
    },
  • "pausePaymentDetail": {
    },
  • "cancelDetail": {
    },
  • "billingDetail": {
    },
  • "shippingDetails": {
    },
  • "metadata": {
    },
  • "paymentSettings": {
    },
  • "createdTimestamp": 1470989538
}

Retrieve a list of the payments specific to a subscription

Used to fetch a paginated list of the payment sessions making up the subscription

Authorizations:
secretApiKeyAuth
path Parameters
subscriptionId
required
string^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P

Subscription to retrieve

query Parameters
startTimestamp
integer <int64>
Example: startTimestamp=1641859200

The timestamp when to return payment sessions from (inclusive), it must be before the endTimestamp. If not provided it will default to 0

endTimestamp
integer <int64>
Example: endTimestamp=1641945599

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

ascending
boolean <boolean>
Example: ascending=false

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.

limit
integer <int32>
Example: limit=10

Control how many items are return in a given page The max limit we allow is 25. The default is 10.

startsAfter
string
Example: startsAfter=ps_01FCTS1XMKH9FF43CAFA4CXT3P

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "paginationToken": "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
}

Files

The Files API allows you to query for and upload files to Ryft. Some files may be generated internally by Ryft when requesting reports, or alternatively you may have uploaded evidence/verification documents

List files

Used to fetch a paginated list of files under your account

Authorizations:
secretApiKeyAuth
query Parameters
category
string
Enum: "Evidence" "VerificationDocument" "Report"
Example: category=Evidence

Filter for files in a specific category.

ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the files are returned. false will arrange the results with newest first, whereas true shows oldest first. The default is false.

limit
integer <int32>
Example: limit=10

Control how many items are return in a given page The max limit we allow is 25. The default is 10.

startsAfter
string
Example: startsAfter=fl_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results for that timestamp range.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "paginationToken": "fl_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"
}

Create/Upload a new file to your account.

Upload a file to Ryft via our API. Useful if you need to:

  • upload evidence when challenging disputes
  • upload KYB/KYC documents for sub accounts
Authorizations:
secretApiKeyAuth
header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

The linked accountId (use this when uploading VerificationDocument files for sub accounts)

Request Body schema: multipart/form-data
file
string

Local path to the file being uploaded

category
string
Enum: "Evidence" "VerificationDocument"

The category for the file

metadata
Array of strings or null

Any supplementary/custom metadata you want to attach to the file. You can have a maximum of 5 pieces of metadata.

Responses

Response samples

Content type
application/json
{
  • "id": "fl_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "name": "string",
  • "type": "Pdf",
  • "category": "Evidence",
  • "metadata": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538,
  • "sizeInBytes": 2048
}

Retrieve a file

Retrieve a file by its unique ID

Authorizations:
secretApiKeyAuth
path Parameters
fileId
required
string^fl_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: fl_01FCTS1XMKH9FF43CAFA4CXT3P

File to retrieve

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

The linked accountId (use this if you need to fetch a particular file for a sub account)

Responses

Response samples

Content type
application/json
{
  • "id": "fl_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "name": "string",
  • "type": "Pdf",
  • "category": "Evidence",
  • "metadata": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538,
  • "sizeInBytes": 2048
}

Apple Pay

Allows implementation of Apple Pay on the web via the API with Ryft's Apple Pay processing certificate.

Register a domain for Apple Pay

Registers a domain name for Apple Pay on the web. Note that this is required if relying on Ryft's Apple Pay processing certificate.

A Maxiumum of 99 domains can be registered against a single Ryft account.

Each domain must host our verification file under /.well-known/apple-developer-merchantid-domain-association.

Important: the Content-Type of the hosted file must be application/octet-stream.

Authorizations:
secretApiKeyAuth
header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

The linked accountId (use this if you are processing payments directly under a sub account's URL)

Request Body schema: application/json
domainName
required
string

The domain name you want to register for Apple Pay.

Responses

Request samples

Content type
application/json
{
  • "domainName": "ryftpay.com"
}

Response samples

Content type
application/json
{
  • "id": "apwd_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "domainName": "ryftpay.com",
  • "createdTimestamp": 1631696701
}

List Apple Pay web domains

List the web domains you have registered for Apple Pay

Authorizations:
secretApiKeyAuth
query Parameters
ascending
boolean <boolean>
Example: ascending=false

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.

limit
integer <int32>
Example: limit=10

Control how many items are return in a given page The max limit we allow is 50. The default is 20.

startsAfter
string
Example: startsAfter=apwd_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results for that timestamp range.

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

The linked accountId (use this if you are processing Apple Pay directly under a sub account's registered Apple Pay domain)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "paginationToken": "apwd_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"
}

Retrieve an Apple Pay web domain

This is used to fetch an Apple Pay web domain by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string
Example: apwd_01FCTS1XMKH9FF43CAFA4CXT3P

Apple Pay web domain Id to retrieve

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

The linked accountId (Required if you registered the domain under a specific sub account)

Responses

Response samples

Content type
application/json
{
  • "id": "apwd_01FCTS1XMKH9FF43CAFA4CXT3P",
  • "domainName": "ryftpay.com",
  • "createdTimestamp": 1631696701
}

Delete an Apple Pay web domain

This is used to delete an Apple Pay web domain by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
id
required
string
Example: apwd_01FCTS1XMKH9FF43CAFA4CXT3P

Apple Pay web domain Id to delete

header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

The linked accountId (Required if you registered the domain under a specific sub account)

Responses

Response samples

Content type
application/json
{
  • "id": "apwd_01FCTS1XMKH9FF43CAFA4CXT3P"
}

Create an Apple Pay web session

Request a new Apple Pay web session. Use this endpoint if you process Apple Pay on the web and:

  • you want to rely on Ryft's Apple Pay processing certificate
  • have an existing integration or want to implement Apple Pay via our API (without using our SDKs)
Authorizations:
publicApiKeyAuthsecretApiKeyAuth
header Parameters
Account
string^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...
Example: ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

The linked accountId (use this if you are processing Apple Pay directly under a sub account's registered Apple Pay domain)

Request Body schema: application/json
displayName
required
string [ 3 .. 64 ] characters

This is the name displayed within the Apple Pay payment sheet. Must contain UTF-8 characters.

domainName
required
string

The domain name you have verified for Apple Pay (omit the protocol). This should match window.location.hostname.

Responses

Request samples

Content type
application/json
{
  • "displayName": "Ryft Merchandise",
  • "domainName": "ryftpay.com"
}

Response samples

Content type
application/json
{
  • "sessionObject": "string"
}

Disputes

Disputes (also known as chargebacks) occur when a cardholder wants to query or challenge a transaction on their card statement. The Disputes API allows you to keep track of and manage disputes.

List disputes

Used to fetch a paginated list of disputes

Authorizations:
secretApiKeyAuth
query Parameters
startTimestamp
integer <int64>
Example: startTimestamp=1641859200

The start timestamp (inclusive), it must be before the endTimestamp.

endTimestamp
integer <int64>
Example: endTimestamp=1641945599

The timestamp when to return payment sessions up to (inclusive), it must be after the startTimestamp.

ascending
boolean <boolean>
Example: ascending=false

Control the order (newest or oldest) in which the disputes are returned. false will arrange the results with newest first, whereas true shows oldest first. The default is false.

limit
integer <int32>
Example: limit=10

Control how many items are return in a given page The max limit we allow is 25. The default is 10.

startsAfter
string
Example: startsAfter=dsp_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473

A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results for that timestamp range.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "paginationToken": "dsp_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"
}

Retrieve a dispute

This is used to fetch a dispute by its unique Id

Authorizations:
secretApiKeyAuth
path Parameters
disputeId
required
string^dsp_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: dsp_01FCTS1XMKH9FF43CAFA4CXT3P

Dispute to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "dsp_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "amount": 500,
  • "currency": "GBP",
  • "status": "Open",
  • "category": "Fraudulent",
  • "reason": {
    },
  • "respondBy": 1685059200,
  • "recommendedEvidence": [
    ],
  • "paymentSession": {
    },
  • "evidence": {
    },
  • "customer": {
    },
  • "subAccount": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Accept a dispute

Accepts a specific dispute by Id. Typically you should use this if the dispute is in fact legitimate and you are accepting the financial impact. Note that this operation cannot be done.

Authorizations:
secretApiKeyAuth
path Parameters
disputeId
required
string^dsp_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: dsp_01FCTS1XMKH9FF43CAFA4CXT3P

Dispute to accept

Responses

Response samples

Content type
application/json
{
  • "id": "dsp_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "amount": 500,
  • "currency": "GBP",
  • "status": "Open",
  • "category": "Fraudulent",
  • "reason": {
    },
  • "respondBy": 1685059200,
  • "recommendedEvidence": [
    ],
  • "paymentSession": {
    },
  • "evidence": {
    },
  • "customer": {
    },
  • "subAccount": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Add evidence to a dispute

Adds or updates the evidence currently attached to the dispute. Note that for file evidence, you must first upload the file via our files API. Once you have attached all relevant evidence, call the /challenge endpoint to submit the evidence for review. Note: the Dispute must be in status Open for this operation.

Authorizations:
secretApiKeyAuth
path Parameters
disputeId
required
string^dsp_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: dsp_01FCTS1XMKH9FF43CAFA4CXT3P

Dispute to attach evidence to

Request Body schema: application/json
object or null (DisputeEvidenceTextEntries)

Contains any evidence in text format

object or null (DisputeEvidenceFiles)

Contains any evidence in file format

Responses

Request samples

Content type
application/json
{
  • "text": {
    },
  • "files": {
    }
}

Response samples

Content type
application/json
{
  • "id": "dsp_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "amount": 500,
  • "currency": "GBP",
  • "status": "Open",
  • "category": "Fraudulent",
  • "reason": {
    },
  • "respondBy": 1685059200,
  • "recommendedEvidence": [
    ],
  • "paymentSession": {
    },
  • "evidence": {
    },
  • "customer": {
    },
  • "subAccount": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Remove evidence from a dispute

Removes evidence currently attached to a dispute. Note: the Dispute must be in status Open for this operation.

Authorizations:
secretApiKeyAuth
path Parameters
disputeId
required
string^dsp_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: dsp_01FCTS1XMKH9FF43CAFA4CXT3P

Dispute to remove evidence from

Request Body schema: application/json
text
Array of strings
Items Enum: "billingAddress" "shippingAddress" "duplicateTransaction" "uncategorised"
files
Array of strings
Items Enum: "proofOfDelivery" "customerSignature" "receipt" "shippingConfirmation" "customerCommunication" "refundPolicy" "recurringPaymentAgreement" "uncategorised"

Responses

Request samples

Content type
application/json
{
  • "text": [
    ],
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "dsp_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "amount": 500,
  • "currency": "GBP",
  • "status": "Open",
  • "category": "Fraudulent",
  • "reason": {
    },
  • "respondBy": 1685059200,
  • "recommendedEvidence": [
    ],
  • "paymentSession": {
    },
  • "evidence": {
    },
  • "customer": {
    },
  • "subAccount": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}

Challenge a dispute

Challenges a specific dispute. You should call this endpoint once you have attached all the relevant evidence. Note that you can no longer submit further evidence once challenged, so make sure you have gathered as much as possible to ensure a better chance of winning the dispute.

Authorizations:
secretApiKeyAuth
path Parameters
disputeId
required
string^dsp_[0-7][0-9A-HJKMNP-TV-Z]{25}
Example: dsp_01FCTS1XMKH9FF43CAFA4CXT3P

Dispute to challenge

Responses

Response samples

Content type
application/json
{
  • "id": "dsp_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  • "amount": 500,
  • "currency": "GBP",
  • "status": "Open",
  • "category": "Fraudulent",
  • "reason": {
    },
  • "respondBy": 1685059200,
  • "recommendedEvidence": [
    ],
  • "paymentSession": {
    },
  • "evidence": {
    },
  • "customer": {
    },
  • "subAccount": {
    },
  • "createdTimestamp": 1470989538,
  • "lastUpdatedTimestamp": 1470989538
}