Skip to content
/
Create a new sub account

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

Create a new sub account

Request

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

Security
secretApiKeyAuth
Bodyapplication/jsonrequired
onboardingFlow(AccountOnboardingFlow (string or null))
(AccountOnboardingFlow (string or null))
emailstring 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.

Example: "test@ryftpay.com"
entityType(AccountEntityType (string or null))
(AccountEntityType (string or null))
business(CreateBusinessRequest (object or null))
(CreateBusinessRequest (object or null))
individual(CreateIndividualRequest (object or null))
(CreateIndividualRequest (object or null))
metadataobject 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.

Example: {"accountId":"1"}
settings(AccountSettingsRequest (object or null))
(AccountSettingsRequest (object or null))
termsOfService(AccountTermsOfServiceRequest (object or null))
(AccountTermsOfServiceRequest (object or null))
curl -i -X POST \
  https://sandbox-api.ryftpay.com/v1/accounts \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "test@example.com"
  }'

Responses

The account was created successfully

Bodyapplication/json
idstring

The ID of the account

Example: "ac_b83f2653-06d7-44a9-a548-5825e8186004"
typestring(AccountTypes)

The type of account

Enum"Standard""Sub"
Example: "Sub"
frozenboolean

A flag to determine whether or not the account is frozen. We may temporarily mark an account as frozen if we detect any potential fraudulent activity. Payments can still be taken however payouts will be disabled, contact us to resolve the issue.

Example: false
emailstring or null(email)<= 200 characters

The account's email address

Example: "test@ryftpay.com"
onboardingFlowAccountOnboardingFlow (string)
AccountOnboardingFlow (string)
entityType(AccountEntityType (string or null))
(AccountEntityType (string or null))
business(BusinessResponse (object or null))
(BusinessResponse (object or null))
individual(IndividualResponse (object or null))
(IndividualResponse (object or null))
verificationobject(AccountVerification)
metadataobject 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.

Example: {"accountId":"1"}
settingsAccountSettingsResponse (object)
AccountSettingsResponse (object)
capabilitiesobject(AccountCapabilities)
termsOfServiceobject or null
createdTimestampinteger(int64)

The epoch timestamp (seconds) when the account was created

Example: 1470989538
status(AccountStatuses (string or null))Deprecated
(AccountStatuses (string or null))
actionsRequiredArray of objects or nullDeprecated

A list of actions required by the user when the status is 'ActionRequired', each accompanied by a description. DEPRECATED - if you wish to determine if actions are required before payouts can be sent out, check: - if frozen is true on this response - if verification.status is Required on this response - if status is Invalid on any payout methods under /v1/accounts/{id}/payout-methods

Response
application/json
{
  "id": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
  "type": "Sub",
  "status": "ActionRequired",
  "actionsRequired": [
    { … }
  ],
  "frozen": false,
  "email": "test@ryftpay.com",
  "onboardingFlow": "Hosted",
  "entityType": "Business",
  "business": {
    "name": "Ryft LTD",
    "type": "Corporation",
    "registrationNumber": "12345678",
    "registrationDate": "1990-01-20",
    "registeredAddress": { … },
    "contactEmail": "contact@test.com",
    "phoneNumber": "+447900000000",
    "tradingName": "Ryft Computer Parts Ltd",
    "tradingAddress": { … },
    "tradingCountries": [ … ],
    "websiteUrl": "https://www.example.com",
    "documents": [ … ]
  },
  "individual": {
    "firstName": "Fred",
    "middleNames": "David",
    "lastName": "Jones",
    "email": "fred.jones@example.com",
    "dateOfBirth": "1990-01-20",
    "countryOfBirth": "GB",
    "gender": "Male",
    "nationalities": [ … ],
    "address": { … },
    "phoneNumber": "+447900000000",
    "documents": [ … ]
  },
  "verification": {
    "status": "Required",
    "requiredFields": [ … ],
    "requiredDocuments": [ … ],
    "errors": [ … ],
    "persons": { … }
  },
  "metadata": {
    "accountId": "1"
  },
  "settings": {
    "payouts": { … }
  },
  "capabilities": {
    "visaPayments": { … },
    "mastercardPayments": { … },
    "amexPayments": { … },
    "inPersonPayments": { … }
  },
  "termsOfService": {
    "acceptance": { … }
  },
  "createdTimestamp": 1470989538
}

Retrieve a sub account by Id

Request

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

Security
secretApiKeyAuth
Path
idstring^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...required

the account id of one of your sub accounts

Example: ac_b83f2653-06d7-44a9-a548-5825e8186004
curl -i -X GET \
  https://sandbox-api.ryftpay.com/v1/accounts/ac_b83f2653-06d7-44a9-a548-5825e8186004 \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

The account was retrieved successfully

Bodyapplication/json
idstring

The ID of the account

Example: "ac_b83f2653-06d7-44a9-a548-5825e8186004"
typestring(AccountTypes)

The type of account

Enum"Standard""Sub"
Example: "Sub"
frozenboolean

A flag to determine whether or not the account is frozen. We may temporarily mark an account as frozen if we detect any potential fraudulent activity. Payments can still be taken however payouts will be disabled, contact us to resolve the issue.

Example: false
emailstring or null(email)<= 200 characters

The account's email address

Example: "test@ryftpay.com"
onboardingFlowAccountOnboardingFlow (string)
AccountOnboardingFlow (string)
entityType(AccountEntityType (string or null))
(AccountEntityType (string or null))
business(BusinessResponse (object or null))
(BusinessResponse (object or null))
individual(IndividualResponse (object or null))
(IndividualResponse (object or null))
verificationobject(AccountVerification)
metadataobject 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.

Example: {"accountId":"1"}
settingsAccountSettingsResponse (object)
AccountSettingsResponse (object)
capabilitiesobject(AccountCapabilities)
termsOfServiceobject or null
createdTimestampinteger(int64)

The epoch timestamp (seconds) when the account was created

Example: 1470989538
status(AccountStatuses (string or null))Deprecated
(AccountStatuses (string or null))
actionsRequiredArray of objects or nullDeprecated

A list of actions required by the user when the status is 'ActionRequired', each accompanied by a description. DEPRECATED - if you wish to determine if actions are required before payouts can be sent out, check: - if frozen is true on this response - if verification.status is Required on this response - if status is Invalid on any payout methods under /v1/accounts/{id}/payout-methods

Response
application/json
{
  "id": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
  "type": "Sub",
  "status": "ActionRequired",
  "actionsRequired": [
    { … }
  ],
  "frozen": false,
  "email": "test@ryftpay.com",
  "onboardingFlow": "Hosted",
  "entityType": "Business",
  "business": {
    "name": "Ryft LTD",
    "type": "Corporation",
    "registrationNumber": "12345678",
    "registrationDate": "1990-01-20",
    "registeredAddress": { … },
    "contactEmail": "contact@test.com",
    "phoneNumber": "+447900000000",
    "tradingName": "Ryft Computer Parts Ltd",
    "tradingAddress": { … },
    "tradingCountries": [ … ],
    "websiteUrl": "https://www.example.com",
    "documents": [ … ]
  },
  "individual": {
    "firstName": "Fred",
    "middleNames": "David",
    "lastName": "Jones",
    "email": "fred.jones@example.com",
    "dateOfBirth": "1990-01-20",
    "countryOfBirth": "GB",
    "gender": "Male",
    "nationalities": [ … ],
    "address": { … },
    "phoneNumber": "+447900000000",
    "documents": [ … ]
  },
  "verification": {
    "status": "Required",
    "requiredFields": [ … ],
    "requiredDocuments": [ … ],
    "errors": [ … ],
    "persons": { … }
  },
  "metadata": {
    "accountId": "1"
  },
  "settings": {
    "payouts": { … }
  },
  "capabilities": {
    "visaPayments": { … },
    "mastercardPayments": { … },
    "amexPayments": { … },
    "inPersonPayments": { … }
  },
  "termsOfService": {
    "acceptance": { … }
  },
  "createdTimestamp": 1470989538
}

Update a sub account by Id

Request

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

Security
secretApiKeyAuth
Path
idstring^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...required

the account id of one of your sub accounts

Example: ac_b83f2653-06d7-44a9-a548-5825e8186004
Bodyapplication/jsonrequired

The request for updating an account

entityType(AccountEntityType (string or null))
(AccountEntityType (string or null))
business(UpdateBusinessRequest (object or null))
(UpdateBusinessRequest (object or null))
individual(UpdateIndividualRequest (object or null))
(UpdateIndividualRequest (object or null))
metadataobject 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.

Example: {"accountId":"1"}
settings(AccountSettingsRequest (object or null))
(AccountSettingsRequest (object or null))
termsOfService(AccountTermsOfServiceRequest (object or null))
(AccountTermsOfServiceRequest (object or null))
capabilities(AccountCapabilitiesRequest (object or null))
(AccountCapabilitiesRequest (object or null))
curl -i -X PATCH \
  https://sandbox-api.ryftpay.com/v1/accounts/ac_b83f2653-06d7-44a9-a548-5825e8186004 \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityType": "Business",
    "business": {
      "name": "Ryft LTD",
      "type": "Corporation",
      "registrationNumber": "12345678",
      "registrationDate": "1990-01-20",
      "registeredAddress": {
        "lineOne": "123 Test Street",
        "lineTwo": null,
        "city": "Manchester",
        "country": "GB",
        "postalCode": "SP4 7DE",
        "region": null
      },
      "contactEmail": "contact@test.com",
      "phoneNumber": "+447900000000",
      "tradingName": "Ryft Computer Parts Ltd",
      "tradingAddress": {
        "lineOne": "123 Test Street",
        "lineTwo": null,
        "city": "Manchester",
        "country": "GB",
        "postalCode": "SP4 7DE",
        "region": null
      },
      "tradingCountries": [
        "GB"
      ],
      "websiteUrl": "https://www.example.com",
      "documents": [
        {
          "type": "BankStatement",
          "front": "fl_01G0EYVFR02KBBVE2YWQ8AKMGJ",
          "back": "fl_01G0EYVFR02KBBVE2YWQ8AKMGJ",
          "country": "GB"
        }
      ]
    },
    "individual": {
      "firstName": "Fred",
      "middleNames": "David",
      "lastName": "Jones",
      "email": "fred.jones@example.com",
      "dateOfBirth": "1990-01-20",
      "countryOfBirth": "GB",
      "gender": "Male",
      "nationalities": [
        "GB"
      ],
      "address": {
        "lineOne": "123 Test Street",
        "lineTwo": null,
        "city": "Manchester",
        "country": "GB",
        "postalCode": "SP4 7DE",
        "region": null
      },
      "phoneNumber": "+447900000000",
      "documents": [
        {
          "type": "BankStatement",
          "front": "fl_01G0EYVFR02KBBVE2YWQ8AKMGJ",
          "back": "fl_01G0EYVFR02KBBVE2YWQ8AKMGJ",
          "country": "GB"
        }
      ]
    },
    "metadata": {
      "accountId": "1"
    },
    "settings": {
      "payouts": {
        "schedule": {
          "type": "Automatic"
        }
      }
    },
    "termsOfService": {
      "acceptance": {
        "ipAddress": "127.0.0.1",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36",
        "when": 1697557453
      }
    },
    "capabilities": {
      "amexPayments": {
        "requested": true
      },
      "inPersonPayments": {
        "requested": true
      }
    }
  }'

Responses

The account was updated successfully

Bodyapplication/json
idstring

The ID of the account

Example: "ac_b83f2653-06d7-44a9-a548-5825e8186004"
typestring(AccountTypes)

The type of account

Enum"Standard""Sub"
Example: "Sub"
frozenboolean

A flag to determine whether or not the account is frozen. We may temporarily mark an account as frozen if we detect any potential fraudulent activity. Payments can still be taken however payouts will be disabled, contact us to resolve the issue.

Example: false
emailstring or null(email)<= 200 characters

The account's email address

Example: "test@ryftpay.com"
onboardingFlowAccountOnboardingFlow (string)
AccountOnboardingFlow (string)
entityType(AccountEntityType (string or null))
(AccountEntityType (string or null))
business(BusinessResponse (object or null))
(BusinessResponse (object or null))
individual(IndividualResponse (object or null))
(IndividualResponse (object or null))
verificationobject(AccountVerification)
metadataobject 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.

Example: {"accountId":"1"}
settingsAccountSettingsResponse (object)
AccountSettingsResponse (object)
capabilitiesobject(AccountCapabilities)
termsOfServiceobject or null
createdTimestampinteger(int64)

The epoch timestamp (seconds) when the account was created

Example: 1470989538
status(AccountStatuses (string or null))Deprecated
(AccountStatuses (string or null))
actionsRequiredArray of objects or nullDeprecated

A list of actions required by the user when the status is 'ActionRequired', each accompanied by a description. DEPRECATED - if you wish to determine if actions are required before payouts can be sent out, check: - if frozen is true on this response - if verification.status is Required on this response - if status is Invalid on any payout methods under /v1/accounts/{id}/payout-methods

Response
application/json
{
  "id": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
  "type": "Sub",
  "status": "ActionRequired",
  "actionsRequired": [
    { … }
  ],
  "frozen": false,
  "email": "test@ryftpay.com",
  "onboardingFlow": "Hosted",
  "entityType": "Business",
  "business": {
    "name": "Ryft LTD",
    "type": "Corporation",
    "registrationNumber": "12345678",
    "registrationDate": "1990-01-20",
    "registeredAddress": { … },
    "contactEmail": "contact@test.com",
    "phoneNumber": "+447900000000",
    "tradingName": "Ryft Computer Parts Ltd",
    "tradingAddress": { … },
    "tradingCountries": [ … ],
    "websiteUrl": "https://www.example.com",
    "documents": [ … ]
  },
  "individual": {
    "firstName": "Fred",
    "middleNames": "David",
    "lastName": "Jones",
    "email": "fred.jones@example.com",
    "dateOfBirth": "1990-01-20",
    "countryOfBirth": "GB",
    "gender": "Male",
    "nationalities": [ … ],
    "address": { … },
    "phoneNumber": "+447900000000",
    "documents": [ … ]
  },
  "verification": {
    "status": "Required",
    "requiredFields": [ … ],
    "requiredDocuments": [ … ],
    "errors": [ … ],
    "persons": { … }
  },
  "metadata": {
    "accountId": "1"
  },
  "settings": {
    "payouts": { … }
  },
  "capabilities": {
    "visaPayments": { … },
    "mastercardPayments": { … },
    "amexPayments": { … },
    "inPersonPayments": { … }
  },
  "termsOfService": {
    "acceptance": { … }
  },
  "createdTimestamp": 1470989538
}

Verify a 'Business' entity sub account

Request

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.

Security
secretApiKeyAuth
Path
idstring^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...required

the account id of one of your sub accounts

Example: ac_b83f2653-06d7-44a9-a548-5825e8186004
curl -i -X POST \
  https://sandbox-api.ryftpay.com/v1/accounts/ac_b83f2653-06d7-44a9-a548-5825e8186004/verify \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Verification was successfully submitted.

Bodyapplication/json
idstring

The ID of the account

Example: "ac_b83f2653-06d7-44a9-a548-5825e8186004"
typestring(AccountTypes)

The type of account

Enum"Standard""Sub"
Example: "Sub"
frozenboolean

A flag to determine whether or not the account is frozen. We may temporarily mark an account as frozen if we detect any potential fraudulent activity. Payments can still be taken however payouts will be disabled, contact us to resolve the issue.

Example: false
emailstring or null(email)<= 200 characters

The account's email address

Example: "test@ryftpay.com"
onboardingFlowAccountOnboardingFlow (string)
AccountOnboardingFlow (string)
entityType(AccountEntityType (string or null))
(AccountEntityType (string or null))
business(BusinessResponse (object or null))
(BusinessResponse (object or null))
individual(IndividualResponse (object or null))
(IndividualResponse (object or null))
verificationobject(AccountVerification)
metadataobject 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.

Example: {"accountId":"1"}
settingsAccountSettingsResponse (object)
AccountSettingsResponse (object)
capabilitiesobject(AccountCapabilities)
termsOfServiceobject or null
createdTimestampinteger(int64)

The epoch timestamp (seconds) when the account was created

Example: 1470989538
status(AccountStatuses (string or null))Deprecated
(AccountStatuses (string or null))
actionsRequiredArray of objects or nullDeprecated

A list of actions required by the user when the status is 'ActionRequired', each accompanied by a description. DEPRECATED - if you wish to determine if actions are required before payouts can be sent out, check: - if frozen is true on this response - if verification.status is Required on this response - if status is Invalid on any payout methods under /v1/accounts/{id}/payout-methods

Response
application/json
{
  "id": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
  "type": "Sub",
  "status": "ActionRequired",
  "actionsRequired": [
    { … }
  ],
  "frozen": false,
  "email": "test@ryftpay.com",
  "onboardingFlow": "Hosted",
  "entityType": "Business",
  "business": {
    "name": "Ryft LTD",
    "type": "Corporation",
    "registrationNumber": "12345678",
    "registrationDate": "1990-01-20",
    "registeredAddress": { … },
    "contactEmail": "contact@test.com",
    "phoneNumber": "+447900000000",
    "tradingName": "Ryft Computer Parts Ltd",
    "tradingAddress": { … },
    "tradingCountries": [ … ],
    "websiteUrl": "https://www.example.com",
    "documents": [ … ]
  },
  "individual": {
    "firstName": "Fred",
    "middleNames": "David",
    "lastName": "Jones",
    "email": "fred.jones@example.com",
    "dateOfBirth": "1990-01-20",
    "countryOfBirth": "GB",
    "gender": "Male",
    "nationalities": [ … ],
    "address": { … },
    "phoneNumber": "+447900000000",
    "documents": [ … ]
  },
  "verification": {
    "status": "Required",
    "requiredFields": [ … ],
    "requiredDocuments": [ … ],
    "errors": [ … ],
    "persons": { … }
  },
  "metadata": {
    "accountId": "1"
  },
  "settings": {
    "payouts": { … }
  },
  "capabilities": {
    "visaPayments": { … },
    "mastercardPayments": { … },
    "amexPayments": { … },
    "inPersonPayments": { … }
  },
  "termsOfService": {
    "acceptance": { … }
  },
  "createdTimestamp": 1470989538
}

Create a manual payout for a sub account

Request

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
Security
secretApiKeyAuth
Path
idstring^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...required

the account id of one of your sub accounts

Example: ac_b83f2653-06d7-44a9-a548-5825e8186004
Bodyapplication/jsonrequired
amountinteger(int32)required

The amount (in minor units) to payout

Example: 5000
currencystring<= 3 charactersrequired

The three-letter ISO currency code

Example: "GBP"
payoutMethodIdstring^pm_[0-7][0-9A-HJKMNP-TV-Z]{25}required

The payout method to send the payout amount to

Example: "pm_01FCTS1XMKH9FF43CAFA4CXT3P"
metadataobject or null

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

Example: {"orderId":"1","customerId":"123"}
curl -i -X POST \
  https://sandbox-api.ryftpay.com/v1/accounts/ac_b83f2653-06d7-44a9-a548-5825e8186004/payouts \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 5000,
    "currency": "GBP",
    "payoutMethodId": "pm_01FCTS1XMKH9FF43CAFA4CXT3P",
    "metadata": {
      "orderId": "1",
      "customerId": "123"
    }
  }'

Responses

Successfully created payout

Bodyapplication/json
idstring

The id of the payout

Example: "po_01FJ1H0023R1AHM77YQ75RMKE7"
amountinteger(int64)

The total amount that was paid out, minus any fees

Example: 9750
currencystring<= 3 characters

The ISO code of the payout currency

Example: "GBP"
statusstring(AccountPayoutStatuses)

The status of the payout

Enum"Completed""Failed""Pending""PendingAccountVerification""PendingTransactionVerification""PendingPayoutMethodAction""PendingAccountAction""InProgress""Cancelled""Expired"
Example: "InProgress"
scheduleTypestring

Whether the payout was issued automatically by Ryft or manually requested.

Enum"Automatic""Manual"
Example: "Automatic"
payoutMethodobject or null(PayoutPayoutMethodResponse)
failureReasonstring or null

If the payout is in the 'Failed' status, this is an additional reason to explain why

Example: "InvalidPayoutMethod"
schemestring or null(PayoutScheme)

The scheme used to payout to your account

Enum"Ach""Bacs""Chaps""Fps""Swift""Sepa""SepaInstant"
Example: "Fps"
createdTimestampinteger(int64)

The epoch timestamp (seconds) when the payout was created

Example: 1631696701
scheduledTimestampinteger(int64)

epoch timestamp of when the payout is scheduled to be paid

Example: 1631696701
completedTimestampinteger or null(int64)

epoch timestamp of when the payout moved to the 'Completed' status, i.e. when it was paid out

Example: 1631696701
metadataobject or null

Your custom key-value data for the payout. You can have a maximum of 5 pieces of metadata.

Example: {"orderId":"1","customerId":"123"}
paymentsTakenDatestring(date)Deprecated

Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout.

Example: "2021-10-14"
paymentsTakenDateFromstring(date)Deprecated

Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout. The date on which payments within this payout began, in the format yyyy-MM-dd

Example: "2021-10-14"
paymentsTakenDateTostring(date)Deprecated

Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout. The date on which payments within this payout end, in the format yyyy-MM-dd

Example: "2021-10-14"
payoutCalculationobject(PayoutCalculationResponse)Deprecated

Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout. An object containing a breakdown of how the payout was calculated

Response
application/json
{
  "id": "po_01FJ1H0023R1AHM77YQ75RMKE7",
  "paymentsTakenDate": "2021-10-14",
  "paymentsTakenDateFrom": "2021-10-14",
  "paymentsTakenDateTo": "2021-10-14",
  "amount": 9750,
  "currency": "GBP",
  "status": "InProgress",
  "scheduleType": "Automatic",
  "payoutMethod": {
    "id": "pm_01FCTS1XMKH9FF43CAFA4CXT3P",
    "bankAccount": { … }
  },
  "failureReason": "InvalidPayoutMethod",
  "payoutCalculation": {
    "paymentsCapturedAmount": 10000,
    "paymentsRefundedAmount": 50,
    "paymentsSplitAmount": 10000,
    "paymentsSplitRefundedAmount": 50,
    "splitPaymentsAmount": 10000,
    "splitPaymentsRefundedAmount": 50,
    "platformFeesCollectedAmount": 0,
    "platformFeesRefundedAmount": 0,
    "platformFeesPaidAmount": 100,
    "processingFeesPaidAmount": 100,
    "chargebacksAmount": 100,
    "chargebackReversalsAmount": 100,
    "platformChargebacksAmount": 100,
    "platformChargebackReversalsAmount": 100,
    "transferredInAmount": 100,
    "transferredOutAmount": 100,
    "payoutAmount": 9750,
    "currency": "GBP",
    "numberOfPaymentsCaptured": 100,
    "numberOfPaymentsRefunded": 1,
    "numberOfPaymentsSplit": 100,
    "numberOfPaymentsSplitRefunded": 1,
    "numberOfSplitPayments": 100,
    "numberOfSplitPaymentsRefunded": 1,
    "numberOfPlatformFeesCollected": 0,
    "numberOfPlatformFeesRefunded": 0,
    "numberOfChargebacks": 0,
    "numberOfChargebackReversals": 0,
    "numberOfPlatformChargebacks": 0,
    "numberOfPlatformChargebackReversals": 0,
    "numberOfTransfersIn": 0,
    "numberOfTransfersOut": 0,
    "numberOfCustomers": 74,
    "numberOfNewCustomers": 50
  },
  "scheme": "Fps",
  "createdTimestamp": 1631696701,
  "scheduledTimestamp": 1631696701,
  "completedTimestamp": 1631696701,
  "metadata": {
    "orderId": "1",
    "customerId": "123"
  }
}

List payouts for a sub account

Request

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

Security
secretApiKeyAuth
Path
idstring^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...required

the account id of one of your sub accounts

Example: ac_b83f2653-06d7-44a9-a548-5825e8186004
Query
ascendingboolean(boolean)

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.

Example: ascending=false
limitinteger(int32)

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

Default 20
Example: limit=20
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 in order to retrieve the next page of results.

Example: startsAfter=po_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473
startTimestampinteger(int64)

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

Example: startTimestamp=1641859200
endTimestampinteger(int64)

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

Example: endTimestamp=1641945599
startDatestring(date)Deprecated

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

endDatestring(date)Deprecated

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

curl -i -X GET \
  https://sandbox-api.ryftpay.com/v1/accounts/ac_b83f2653-06d7-44a9-a548-5825e8186004/payouts \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Payouts were retrieved successfully

Bodyapplication/json
payoutsArray of objects(PayoutResponse)
paginationTokenstring

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

Example: "po_01FCTS1XMKH9FF43CAFA4CXT3P"
Response
application/json
{
  "payouts": [
    { … }
  ],
  "paginationToken": "po_01FCTS1XMKH9FF43CAFA4CXT3P"
}

Retrieve a a payout for a sub account by Id

Request

This is used to fetch a payout by its unique Id

Security
secretApiKeyAuth
Path
idstring^ac_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a...required

the account id of one of your sub accounts

Example: ac_b83f2653-06d7-44a9-a548-5825e8186004
payoutIdstring^po_[0-7][0-9A-HJKMNP-TV-Z]{25}required

Payout to retrieve

Example: po_01FCTS1XMKH9FF43CAFA4CXT3P
curl -i -X GET \
  https://sandbox-api.ryftpay.com/v1/accounts/ac_b83f2653-06d7-44a9-a548-5825e8186004/payouts/po_01FCTS1XMKH9FF43CAFA4CXT3P \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully retrieved the given Payout

Bodyapplication/json
idstring

The id of the payout

Example: "po_01FJ1H0023R1AHM77YQ75RMKE7"
amountinteger(int64)

The total amount that was paid out, minus any fees

Example: 9750
currencystring<= 3 characters

The ISO code of the payout currency

Example: "GBP"
statusstring(AccountPayoutStatuses)

The status of the payout

Enum"Completed""Failed""Pending""PendingAccountVerification""PendingTransactionVerification""PendingPayoutMethodAction""PendingAccountAction""InProgress""Cancelled""Expired"
Example: "InProgress"
scheduleTypestring

Whether the payout was issued automatically by Ryft or manually requested.

Enum"Automatic""Manual"
Example: "Automatic"
payoutMethodobject or null(PayoutPayoutMethodResponse)
failureReasonstring or null

If the payout is in the 'Failed' status, this is an additional reason to explain why

Example: "InvalidPayoutMethod"
schemestring or null(PayoutScheme)

The scheme used to payout to your account

Enum"Ach""Bacs""Chaps""Fps""Swift""Sepa""SepaInstant"
Example: "Fps"
createdTimestampinteger(int64)

The epoch timestamp (seconds) when the payout was created

Example: 1631696701
scheduledTimestampinteger(int64)

epoch timestamp of when the payout is scheduled to be paid

Example: 1631696701
completedTimestampinteger or null(int64)

epoch timestamp of when the payout moved to the 'Completed' status, i.e. when it was paid out

Example: 1631696701
metadataobject or null

Your custom key-value data for the payout. You can have a maximum of 5 pieces of metadata.

Example: {"orderId":"1","customerId":"123"}
paymentsTakenDatestring(date)Deprecated

Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout.

Example: "2021-10-14"
paymentsTakenDateFromstring(date)Deprecated

Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout. The date on which payments within this payout began, in the format yyyy-MM-dd

Example: "2021-10-14"
paymentsTakenDateTostring(date)Deprecated

Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout. The date on which payments within this payout end, in the format yyyy-MM-dd

Example: "2021-10-14"
payoutCalculationobject(PayoutCalculationResponse)Deprecated

Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout. An object containing a breakdown of how the payout was calculated

Response
application/json
{
  "id": "po_01FJ1H0023R1AHM77YQ75RMKE7",
  "paymentsTakenDate": "2021-10-14",
  "paymentsTakenDateFrom": "2021-10-14",
  "paymentsTakenDateTo": "2021-10-14",
  "amount": 9750,
  "currency": "GBP",
  "status": "InProgress",
  "scheduleType": "Automatic",
  "payoutMethod": {
    "id": "pm_01FCTS1XMKH9FF43CAFA4CXT3P",
    "bankAccount": { … }
  },
  "failureReason": "InvalidPayoutMethod",
  "payoutCalculation": {
    "paymentsCapturedAmount": 10000,
    "paymentsRefundedAmount": 50,
    "paymentsSplitAmount": 10000,
    "paymentsSplitRefundedAmount": 50,
    "splitPaymentsAmount": 10000,
    "splitPaymentsRefundedAmount": 50,
    "platformFeesCollectedAmount": 0,
    "platformFeesRefundedAmount": 0,
    "platformFeesPaidAmount": 100,
    "processingFeesPaidAmount": 100,
    "chargebacksAmount": 100,
    "chargebackReversalsAmount": 100,
    "platformChargebacksAmount": 100,
    "platformChargebackReversalsAmount": 100,
    "transferredInAmount": 100,
    "transferredOutAmount": 100,
    "payoutAmount": 9750,
    "currency": "GBP",
    "numberOfPaymentsCaptured": 100,
    "numberOfPaymentsRefunded": 1,
    "numberOfPaymentsSplit": 100,
    "numberOfPaymentsSplitRefunded": 1,
    "numberOfSplitPayments": 100,
    "numberOfSplitPaymentsRefunded": 1,
    "numberOfPlatformFeesCollected": 0,
    "numberOfPlatformFeesRefunded": 0,
    "numberOfChargebacks": 0,
    "numberOfChargebackReversals": 0,
    "numberOfPlatformChargebacks": 0,
    "numberOfPlatformChargebackReversals": 0,
    "numberOfTransfersIn": 0,
    "numberOfTransfersOut": 0,
    "numberOfCustomers": 74,
    "numberOfNewCustomers": 50
  },
  "scheme": "Fps",
  "createdTimestamp": 1631696701,
  "scheduledTimestamp": 1631696701,
  "completedTimestamp": 1631696701,
  "metadata": {
    "orderId": "1",
    "customerId": "123"
  }
}

Create a link for a sub account to authorize their account

Request

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.

Security
secretApiKeyAuth
Bodyapplication/json
emailstring(email)<= 200 characters

The main email address for the account

Example: "test@ryftpay.com"
redirectUrlstring

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.

Example: "https://mywebsite.com/account/verification?p1=kjr4jbnm4bm4b5mnb"
curl -i -X POST \
  https://sandbox-api.ryftpay.com/v1/accounts/authorize \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "test@ryftpay.com",
    "redirectUrl": "https://mywebsite.com/account/verification?p1=kjr4jbnm4bm4b5mnb"
  }'

Responses

Successfully created temporary auth link

Bodyapplication/json
createdTimestampinteger(int64)

The epoch timestamp (seconds) when the temporary auth link was created

Example: 1631696701
expiresTimestampinteger(int64)

The epoch timestamp (seconds) when the temporary auth link expires

Example: 1631703901
urlstring

The URL to redirect to.

Example: "https://sandbox-dash.ryftpay.com/signin?atl=123"
Response
application/json
{
  "createdTimestamp": 1631696701,
  "expiresTimestamp": 1631703901,
  "url": "https://sandbox-dash.ryftpay.com/signin?atl=123"
}

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

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