Skip to content
/
Retrieve a list of the pa...

Ryft Payment API (1.1.0)

Ryft provides a collection of APIs that you can use to accept and process payments + marketplace functionality (payouts). We have a testing environment called sandbox, which you can sign up for to test API calls without affecting live data.

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 50 requests per second.

We also allow a brief burst above this limit to accommodate a sudden increase in traffic.

If you exceed the above quota then the API will respond with a 429 status code and you will need to retry the API call (we recommend implementing a retry policy with an exponential back-off).

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://ryftpay.com
Ryft
support@ryftpay.com
Languages
Servers
Sandbox environmment
https://sandbox-api.ryftpay.com/v1/
Production environment
https://api.ryftpay.com/v1/

Payments

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

Operations

Webhooks

Create and manage webhooks.

Operations

Events

Events are persisted throughout the lifecycle of a payment/action as you use our API. We use events to notify you when something important happens in your account (or a linked sub account). The most commonly used event occurs when a payment is captured, in which case we persist a PaymentSession.captured event and then (optionally) send it to any webhooks you have registered that are listening for that event type.

Note that if you are taking payments as a platform (for sub accounts), events are saved against the sub account accountId, but will be sent to any webhooks that your account has configured.

Operations

Accounts

Account registration for your sub accounts

Operations

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.

Operations

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.

Operations

Payouts

A payout represents the transfer of money from Ryft to a connected payout method (bank account), i.e. when we send money you're owed. Typically this is automated.

However, the payouts API allows you to explicitly create payouts for your sub accounts. Generally we'd recommend this if you are a marketplace who wants to control exactly when payouts should be sent out.

Operations

Transfers

A Transfer represents the movement of money between Ryft accounts.

This API allows platforms/marketplaces to transfer money from/to particular sub accounts, useful when:

  • you owe a sub account money from a particular transaction and want to explicitly send it after the fact
  • you want to recoup funds from a sub account, such as when dealing with disputes
  • you want to collect additional/new commission from the sub account
Operations

Balances

The balances API allows you to view your own or a particular sub accounts balances in real-time.

Typically useful when making use of manual payouts or our transfers API so you can determine the funds available prior to initiating requests.

Operations

Balance Transactions

Allows you to query for balance transactions. These transactions represent all actions within a Ryft account that impact account balances.

This API can only be used for reconciliation on transactions created from July 2025 onwards

Operations

Platform Fees

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

Operations

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.

Operations

Payment Methods

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

Operations

Subscriptions

The subscriptions API allows you to automatically have Ryft schedule and charge recurring payments for a specific day and time. This API is not required to process recurring payments. After additional configuration, you can use our payment-sessions API to create and charge the recurring payments yourself.

Operations

Creates a new subscription

Request

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

Security
secretApiKeyAuth
Bodyapplication/json
customerobjectrequired

The customer the subscription is for

customer.​idstring

The id of the customer

Example: "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
priceobjectrequired

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

price.​amountinteger(int32)[ 30 .. 100000 ]

The amount (in minor units) that is charged on each recurring payment throughout the subscription

Example: 5000
price.​currencystring<= 3 characters

The ISO currency code

Example: "GBP"
price.​intervalobject(RecurringIntervalRequest)
paymentMethodobject

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.

descriptionstring or null

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

Example: "Bob's monthly gym membership"
billingCycleTimestampnumber 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.

Example: 1631703901
metadataobject

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.

Example: {"orderId":"1","customerId":"123"}
shippingDetailsobject or null(ShippingDetails)
Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}}
paymentSettingsobject or null

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

curl -i -X POST \
  https://sandbox-api.ryftpay.com/v1/subscriptions \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": {
      "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
    },
    "price": {
      "amount": 5000,
      "currency": "GBP",
      "interval": {
        "unit": "Months",
        "count": 1,
        "times": 12
      }
    },
    "paymentMethod": {
      "id": "pmt_01FCTS1XMKH9FF43CAFA4CXT3P"
    },
    "description": "Bob'\''s monthly gym membership",
    "billingCycleTimestamp": 1631703901,
    "metadata": {
      "orderId": "1",
      "customerId": "123"
    },
    "shippingDetails": {
      "address": {
        "firstName": "Fox",
        "lastName": "Mulder",
        "lineOne": "Stonehenge",
        "postalCode": "SP4 7DE",
        "city": "Salisbury",
        "country": "GB"
      }
    },
    "paymentSettings": {
      "statementDescriptor": {
        "descriptor": "Ryft Ltd",
        "city": "London"
      }
    }
  }'

Responses

The subscription was created successfully

Bodyapplication/json
idstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}

The ID of the subscription

Example: "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ"
statusstring
Enum"Pending""Active""Cancelled""PastDue""Ended""Paused"
Example: "Active"
descriptionstring or null

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

Example: "Bob's monthly gym membership"
customerobject
paymentMethodobject or null
paymentSessionsobject
priceobject(RecurringPrice)
balanceobject(SubscriptionBalance)

The full outstanding amount owed by the customer for this subscription. Any outstanding amount will be included in future cycle payments (on top of the recurring price)

Example: {"amount":5000}
pausePaymentDetailobject or null

Non-null if you have paused payments for the subscription.

cancelDetailobject or null

Non-null if the subscription is cancelled

billingDetailobject
shippingDetailsobject or null(ShippingDetails)
Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}}
metadataobject or null

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.

Example: {"myCustomerId":"1"}
paymentSettingsobject

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

createdTimestampinteger(int64)

The epoch timestamp (seconds) when the subscription was created

Example: 1470989538
Response
application/json
{
  "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  "status": "Active",
  "description": "Bob's monthly gym membership",
  "customer": {
    "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentMethod": {
    "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentSessions": {
    "initial": { … },
    "latest": { … }
  },
  "price": {
    "amount": 5000,
    "currency": "GBP",
    "interval": { … }
  },
  "balance": {
    "amount": 5000
  },
  "pausePaymentDetail": {
    "reason": "Offering service for free to customer",
    "resumeAtTimestamp": 1470989538,
    "pausedAtTimestamp": 1470989538
  },
  "cancelDetail": {
    "reason": "Customer no longer wants to use the service",
    "cancelledAtTimestamp": 1480989538
  },
  "billingDetail": {
    "totalCycles": 12,
    "currentCycle": 4,
    "currentCycleStartTimestamp": 1480989538,
    "currentCycleEndTimestamp": 1480989538,
    "billingCycleTimestamp": 1480989538,
    "nextBillingTimestamp": 1480989538,
    "failureDetail": { … }
  },
  "shippingDetails": {
    "address": { … }
  },
  "metadata": {
    "myCustomerId": "1"
  },
  "paymentSettings": {
    "statementDescriptor": { … }
  },
  "createdTimestamp": 1470989538
}

List subscriptions

Request

Used to fetch a paginated list of subscriptions

Security
secretApiKeyAuth
Query
startTimestampinteger(int64)

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

Example: startTimestamp=1641859200
endTimestampinteger(int64)

The timestamp when to return payment sessions up to (inclusive), it must be after the startTimestamp. If not provided it will default to the current time (UTC).

Example: endTimestamp=1641945599
ascendingboolean(boolean)

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.

Example: ascending=false
limitinteger(int32)

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

Example: limit=10
startsAfterstring

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.

Example: startsAfter=sub_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473
curl -i -X GET \
  https://sandbox-api.ryftpay.com/v1/subscriptions \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully retrieved the subscriptions

Bodyapplication/json
itemsArray of objects(Subscription)
paginationTokenstring or null

A token to use for getting the next page of results - send the same request with this value in the 'paginationToken' query parameter. This field is null when there are no further items to return

Example: "sub_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"
Response
application/json
{
  "items": [
    { … }
  ],
  "paginationToken": "sub_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"
}

Retrieve a subscription by Id

Request

This is used to fetch a subscription by its unique Id

Security
secretApiKeyAuth
Path
subscriptionIdstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}required

Subscription to retrieve

Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P
curl -i -X GET \
  https://sandbox-api.ryftpay.com/v1/subscriptions/sub_01FCTS1XMKH9FF43CAFA4CXT3P \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully retrieved the given Subscription

Bodyapplication/json
idstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}

The ID of the subscription

Example: "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ"
statusstring
Enum"Pending""Active""Cancelled""PastDue""Ended""Paused"
Example: "Active"
descriptionstring or null

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

Example: "Bob's monthly gym membership"
customerobject
paymentMethodobject or null
paymentSessionsobject
priceobject(RecurringPrice)
balanceobject(SubscriptionBalance)

The full outstanding amount owed by the customer for this subscription. Any outstanding amount will be included in future cycle payments (on top of the recurring price)

Example: {"amount":5000}
pausePaymentDetailobject or null

Non-null if you have paused payments for the subscription.

cancelDetailobject or null

Non-null if the subscription is cancelled

billingDetailobject
shippingDetailsobject or null(ShippingDetails)
Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}}
metadataobject or null

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.

Example: {"myCustomerId":"1"}
paymentSettingsobject

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

createdTimestampinteger(int64)

The epoch timestamp (seconds) when the subscription was created

Example: 1470989538
Response
application/json
{
  "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  "status": "Active",
  "description": "Bob's monthly gym membership",
  "customer": {
    "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentMethod": {
    "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentSessions": {
    "initial": { … },
    "latest": { … }
  },
  "price": {
    "amount": 5000,
    "currency": "GBP",
    "interval": { … }
  },
  "balance": {
    "amount": 5000
  },
  "pausePaymentDetail": {
    "reason": "Offering service for free to customer",
    "resumeAtTimestamp": 1470989538,
    "pausedAtTimestamp": 1470989538
  },
  "cancelDetail": {
    "reason": "Customer no longer wants to use the service",
    "cancelledAtTimestamp": 1480989538
  },
  "billingDetail": {
    "totalCycles": 12,
    "currentCycle": 4,
    "currentCycleStartTimestamp": 1480989538,
    "currentCycleEndTimestamp": 1480989538,
    "billingCycleTimestamp": 1480989538,
    "nextBillingTimestamp": 1480989538,
    "failureDetail": { … }
  },
  "shippingDetails": {
    "address": { … }
  },
  "metadata": {
    "myCustomerId": "1"
  },
  "paymentSettings": {
    "statementDescriptor": { … }
  },
  "createdTimestamp": 1470989538
}

Updates a subscription by Id

Request

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

Security
secretApiKeyAuth
Path
subscriptionIdstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}required

Subscription to retrieve

Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P
Bodyapplication/json
priceobject 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

paymentMethodobject 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

descriptionstring or null

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

Example: "Bob's monthly gym membership"
billingCycleTimestampnumber 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.

Example: 1631703901
metadataobject

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.

Example: {"orderId":"1","customerId":"123"}
shippingDetailsobject or null(ShippingDetails)
Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}}
paymentSettingsobject

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

curl -i -X PATCH \
  https://sandbox-api.ryftpay.com/v1/subscriptions/sub_01FCTS1XMKH9FF43CAFA4CXT3P \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "price": {
      "amount": 5000,
      "interval": {
        "unit": "Months",
        "count": 1,
        "times": 12
      }
    },
    "paymentMethod": {
      "id": "pmt_01FCTS1XMKH9FF43CAFA4CXT3P"
    },
    "description": "Bob'\''s monthly gym membership",
    "billingCycleTimestamp": 1631703901,
    "metadata": {
      "orderId": "1",
      "customerId": "123"
    },
    "shippingDetails": {
      "address": {
        "firstName": "Fox",
        "lastName": "Mulder",
        "lineOne": "Stonehenge",
        "postalCode": "SP4 7DE",
        "city": "Salisbury",
        "country": "GB"
      }
    },
    "paymentSettings": {
      "statementDescriptor": {
        "descriptor": "Ryft Ltd",
        "city": "London"
      }
    }
  }'

Responses

The subscription was updated successfully

Bodyapplication/json
idstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}

The ID of the subscription

Example: "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ"
statusstring
Enum"Pending""Active""Cancelled""PastDue""Ended""Paused"
Example: "Active"
descriptionstring or null

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

Example: "Bob's monthly gym membership"
customerobject
paymentMethodobject or null
paymentSessionsobject
priceobject(RecurringPrice)
balanceobject(SubscriptionBalance)

The full outstanding amount owed by the customer for this subscription. Any outstanding amount will be included in future cycle payments (on top of the recurring price)

Example: {"amount":5000}
pausePaymentDetailobject or null

Non-null if you have paused payments for the subscription.

cancelDetailobject or null

Non-null if the subscription is cancelled

billingDetailobject
shippingDetailsobject or null(ShippingDetails)
Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}}
metadataobject or null

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.

Example: {"myCustomerId":"1"}
paymentSettingsobject

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

createdTimestampinteger(int64)

The epoch timestamp (seconds) when the subscription was created

Example: 1470989538
Response
application/json
{
  "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  "status": "Active",
  "description": "Bob's monthly gym membership",
  "customer": {
    "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentMethod": {
    "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentSessions": {
    "initial": { … },
    "latest": { … }
  },
  "price": {
    "amount": 5000,
    "currency": "GBP",
    "interval": { … }
  },
  "balance": {
    "amount": 5000
  },
  "pausePaymentDetail": {
    "reason": "Offering service for free to customer",
    "resumeAtTimestamp": 1470989538,
    "pausedAtTimestamp": 1470989538
  },
  "cancelDetail": {
    "reason": "Customer no longer wants to use the service",
    "cancelledAtTimestamp": 1480989538
  },
  "billingDetail": {
    "totalCycles": 12,
    "currentCycle": 4,
    "currentCycleStartTimestamp": 1480989538,
    "currentCycleEndTimestamp": 1480989538,
    "billingCycleTimestamp": 1480989538,
    "nextBillingTimestamp": 1480989538,
    "failureDetail": { … }
  },
  "shippingDetails": {
    "address": { … }
  },
  "metadata": {
    "myCustomerId": "1"
  },
  "paymentSettings": {
    "statementDescriptor": { … }
  },
  "createdTimestamp": 1470989538
}

Pause a subscription by Id

Request

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.

Security
secretApiKeyAuth
Path
subscriptionIdstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}required

Subscription to pause

Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P
Bodyapplication/json
reasonstring or null

Optional field describing why the subscription is being paused.

Example: "Offering service for free to customer"
resumeAtTimestampnumber 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.

Example: 1470989538
unscheduleboolean 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.

Example: false
curl -i -X PATCH \
  https://sandbox-api.ryftpay.com/v1/subscriptions/sub_01FCTS1XMKH9FF43CAFA4CXT3P/pause \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "Offering service for free to customer",
    "resumeAtTimestamp": 1470989538,
    "unschedule": false
  }'

Responses

The subscription was paused successfully

Bodyapplication/json
idstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}

The ID of the subscription

Example: "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ"
statusstring
Enum"Pending""Active""Cancelled""PastDue""Ended""Paused"
Example: "Active"
descriptionstring or null

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

Example: "Bob's monthly gym membership"
customerobject
paymentMethodobject or null
paymentSessionsobject
priceobject(RecurringPrice)
balanceobject(SubscriptionBalance)

The full outstanding amount owed by the customer for this subscription. Any outstanding amount will be included in future cycle payments (on top of the recurring price)

Example: {"amount":5000}
pausePaymentDetailobject or null

Non-null if you have paused payments for the subscription.

cancelDetailobject or null

Non-null if the subscription is cancelled

billingDetailobject
shippingDetailsobject or null(ShippingDetails)
Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}}
metadataobject or null

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.

Example: {"myCustomerId":"1"}
paymentSettingsobject

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

createdTimestampinteger(int64)

The epoch timestamp (seconds) when the subscription was created

Example: 1470989538
Response
application/json
{
  "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  "status": "Active",
  "description": "Bob's monthly gym membership",
  "customer": {
    "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentMethod": {
    "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentSessions": {
    "initial": { … },
    "latest": { … }
  },
  "price": {
    "amount": 5000,
    "currency": "GBP",
    "interval": { … }
  },
  "balance": {
    "amount": 5000
  },
  "pausePaymentDetail": {
    "reason": "Offering service for free to customer",
    "resumeAtTimestamp": 1470989538,
    "pausedAtTimestamp": 1470989538
  },
  "cancelDetail": {
    "reason": "Customer no longer wants to use the service",
    "cancelledAtTimestamp": 1480989538
  },
  "billingDetail": {
    "totalCycles": 12,
    "currentCycle": 4,
    "currentCycleStartTimestamp": 1480989538,
    "currentCycleEndTimestamp": 1480989538,
    "billingCycleTimestamp": 1480989538,
    "nextBillingTimestamp": 1480989538,
    "failureDetail": { … }
  },
  "shippingDetails": {
    "address": { … }
  },
  "metadata": {
    "myCustomerId": "1"
  },
  "paymentSettings": {
    "statementDescriptor": { … }
  },
  "createdTimestamp": 1470989538
}

Resume a subscription by Id

Request

Use to resume a paused Subscription.

Security
secretApiKeyAuth
Path
subscriptionIdstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}required

Subscription to resume

Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P
curl -i -X PATCH \
  https://sandbox-api.ryftpay.com/v1/subscriptions/sub_01FCTS1XMKH9FF43CAFA4CXT3P/resume \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

The subscription was resumed successfully

Bodyapplication/json
idstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}

The ID of the subscription

Example: "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ"
statusstring
Enum"Pending""Active""Cancelled""PastDue""Ended""Paused"
Example: "Active"
descriptionstring or null

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

Example: "Bob's monthly gym membership"
customerobject
paymentMethodobject or null
paymentSessionsobject
priceobject(RecurringPrice)
balanceobject(SubscriptionBalance)

The full outstanding amount owed by the customer for this subscription. Any outstanding amount will be included in future cycle payments (on top of the recurring price)

Example: {"amount":5000}
pausePaymentDetailobject or null

Non-null if you have paused payments for the subscription.

cancelDetailobject or null

Non-null if the subscription is cancelled

billingDetailobject
shippingDetailsobject or null(ShippingDetails)
Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}}
metadataobject or null

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.

Example: {"myCustomerId":"1"}
paymentSettingsobject

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

createdTimestampinteger(int64)

The epoch timestamp (seconds) when the subscription was created

Example: 1470989538
Response
application/json
{
  "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  "status": "Active",
  "description": "Bob's monthly gym membership",
  "customer": {
    "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentMethod": {
    "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentSessions": {
    "initial": { … },
    "latest": { … }
  },
  "price": {
    "amount": 5000,
    "currency": "GBP",
    "interval": { … }
  },
  "balance": {
    "amount": 5000
  },
  "pausePaymentDetail": {
    "reason": "Offering service for free to customer",
    "resumeAtTimestamp": 1470989538,
    "pausedAtTimestamp": 1470989538
  },
  "cancelDetail": {
    "reason": "Customer no longer wants to use the service",
    "cancelledAtTimestamp": 1480989538
  },
  "billingDetail": {
    "totalCycles": 12,
    "currentCycle": 4,
    "currentCycleStartTimestamp": 1480989538,
    "currentCycleEndTimestamp": 1480989538,
    "billingCycleTimestamp": 1480989538,
    "nextBillingTimestamp": 1480989538,
    "failureDetail": { … }
  },
  "shippingDetails": {
    "address": { … }
  },
  "metadata": {
    "myCustomerId": "1"
  },
  "paymentSettings": {
    "statementDescriptor": { … }
  },
  "createdTimestamp": 1470989538
}

Cancel a subscription by Id

Request

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.

Security
secretApiKeyAuth
Path
subscriptionIdstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}required

Subscription to cancel

Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P
Bodyapplication/json
reasonstring or null

Optional field describing why the subscription is being cancelled.

Example: "Customer no longer wants service"
curl -i -X DELETE \
  https://sandbox-api.ryftpay.com/v1/subscriptions/sub_01FCTS1XMKH9FF43CAFA4CXT3P/cancel \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "Customer no longer wants service"
  }'

Responses

Successfully cancelled the given Subscription

Bodyapplication/json
idstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}

The ID of the subscription

Example: "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ"
statusstring
Enum"Pending""Active""Cancelled""PastDue""Ended""Paused"
Example: "Active"
descriptionstring or null

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

Example: "Bob's monthly gym membership"
customerobject
paymentMethodobject or null
paymentSessionsobject
priceobject(RecurringPrice)
balanceobject(SubscriptionBalance)

The full outstanding amount owed by the customer for this subscription. Any outstanding amount will be included in future cycle payments (on top of the recurring price)

Example: {"amount":5000}
pausePaymentDetailobject or null

Non-null if you have paused payments for the subscription.

cancelDetailobject or null

Non-null if the subscription is cancelled

billingDetailobject
shippingDetailsobject or null(ShippingDetails)
Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}}
metadataobject or null

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.

Example: {"myCustomerId":"1"}
paymentSettingsobject

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

createdTimestampinteger(int64)

The epoch timestamp (seconds) when the subscription was created

Example: 1470989538
Response
application/json
{
  "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  "status": "Active",
  "description": "Bob's monthly gym membership",
  "customer": {
    "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentMethod": {
    "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentSessions": {
    "initial": { … },
    "latest": { … }
  },
  "price": {
    "amount": 5000,
    "currency": "GBP",
    "interval": { … }
  },
  "balance": {
    "amount": 5000
  },
  "pausePaymentDetail": {
    "reason": "Offering service for free to customer",
    "resumeAtTimestamp": 1470989538,
    "pausedAtTimestamp": 1470989538
  },
  "cancelDetail": {
    "reason": "Customer no longer wants to use the service",
    "cancelledAtTimestamp": 1480989538
  },
  "billingDetail": {
    "totalCycles": 12,
    "currentCycle": 4,
    "currentCycleStartTimestamp": 1480989538,
    "currentCycleEndTimestamp": 1480989538,
    "billingCycleTimestamp": 1480989538,
    "nextBillingTimestamp": 1480989538,
    "failureDetail": { … }
  },
  "shippingDetails": {
    "address": { … }
  },
  "metadata": {
    "myCustomerId": "1"
  },
  "paymentSettings": {
    "statementDescriptor": { … }
  },
  "createdTimestamp": 1470989538
}

Retrieve a list of the payments specific to a subscription

Request

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

Security
secretApiKeyAuth
Path
subscriptionIdstring^sub_[0-7][0-9A-HJKMNP-TV-Z]{25}required

Subscription to retrieve

Example: sub_01FCTS1XMKH9FF43CAFA4CXT3P
Query
startTimestampinteger(int64)

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

Example: startTimestamp=1641859200
endTimestampinteger(int64)

The timestamp when to return payment sessions up to (inclusive), it must be after the startTimestamp. If not provided it will default to the current time (UTC).

Example: endTimestamp=1641945599
ascendingboolean(boolean)

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

Example: ascending=false
limitinteger(int32)

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

Example: limit=10
startsAfterstring

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.

Example: startsAfter=ps_01FCTS1XMKH9FF43CAFA4CXT3P
curl -i -X GET \
  https://sandbox-api.ryftpay.com/v1/subscriptions/sub_01FCTS1XMKH9FF43CAFA4CXT3P/payment-sessions \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully retrieved the payment sessions

Bodyapplication/json
itemsArray of objects(PaymentSession)
paginationTokenstring or null

A token to use for getting the next page of results. This will be null when there are no further pages to fetch

Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P"
Response
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

Operations

Apple Pay

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

Operations

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.

Operations

In-Person Products

The in-person products API allows you query for the products we offer for in-person payments. Useful to view and decide which SKUs you wish to order. Note that products themselves cannot be ordered. You must select one or more SKUs to purchase equipment.

Operations

In-Person SKUs

The in-person SKUs API allows you query for the SKUs we offer for in-person payments. SKUs are ultimately the items you order when purchasing equipment. Each SKU is scoped to a specific country and currency.

Operations

In-Person Orders

The in-person orders API allows you to request physical terminal orders to specific locations. Used in combination with our terminal API you can integrate in-person (card present) payments.

Operations

In-Person Locations

The in-person locations API allows you to setup and manage the locations in which terminals reside.

Operations

In-Person Terminals

The in-person terminals API allows you to setup and manage your physical terminal hardware for in-person (card present) payments.

Operations