Skip to main content
Ryft is a UK-based payment platform built for marketplaces and platforms. Alongside standard card processing, Ryft lets a platform take payments on behalf of its sub-accounts (for example sellers, hosts, or charities) and keep a platform fee on each payment.

​
Setup

Ryft accounts are set up by the Ryft team. Contact Ryft to open a sandbox and a production account, and to agree which card schemes and payment types your account needs.

​
Enable American Express

American Express payments are disabled by default on Ryft accounts. Visa and Mastercard work without extra setup. To accept American Express, enable the Amex payments capability in the Ryft portal under Settings -> Capabilities. For non-hosted sub-accounts, the main account requests the capability through the Ryft Accounts API instead. See the Ryft capabilities documentation for details.

​
Credentials

When setting up Ryft in the dashboard, configure the following credentials. The API keys are in the Developer section of the Ryft portal, which you reach from the profile menu in the top right. See the Ryft portal documentation for details.
  • Public API Key (public_key) - Your Ryft public key.
  • Secret API Key (secret_key) - Your Ryft secret key. Treat this value as a password.
  • Webhook Secret (webhook_secret, optional) - The secret for the webhook endpoint registered in Ryft. When set, Gr4vy validates the signature on every webhook Ryft sends.
  • Include platform fees in refunds (refund_platform_fee, optional) - When enabled, every refund also refunds the platform fee on the payment. See Platform fees.

​
Webhooks

Ryft reports the outcome of 3-D Secure challenges, captures, voids, and refunds by webhook, and Gr4vy uses those events to keep transactions in sync. Register a webhook endpoint for your Ryft account before you take live traffic.
  1. Copy the webhook URL for your Ryft payment service, which is the webhook_url field on the payment service in the Gr4vy dashboard and API. Each payment service has its own URL.
  2. In the Ryft portal, go to Developer -> Webhooks and create an endpoint with that URL.
  3. Subscribe to the payment events, including the PaymentSession events and, if you use platform fees, the PlatformFee events.
  4. Copy the secret for that endpoint into the Webhook Secret field on your Gr4vy connector.
For more details, see the Ryft webhooks documentation.

​
Connector configuration

After setting up your Ryft connector in the dashboard, configure how transactions are routed to it. Choose one of the following options:
  • Using Flow - Configure Ryft as the target connector in Flow to automatically route card transactions to this connector
  • Using the API - Explicitly set the payment_service_id parameter to the Ryft connector ID when creating transactions. This overrides any Flow routing rules.
The connector ID can be found in the dashboard under Connections -> Configured connections.

​
Capabilities

​
Supported countries

​
Supported currencies

​
Limitations

  • No digital wallets - Apple Pay and Google Pay aren’t supported through this connector.
  • No network tokens - Stored cards are Ryft payment methods, and can’t be used with another connector.
  • Single capture - An authorization can be captured once, in full or for a lower amount. Multiple captures and captures above the authorized amount aren’t supported.
  • Hosted 3-D Secure only - Ryft runs its own 3-D Secure authentication. External 3-D Secure data can’t be passed through.

​
Integration

To accept card payments with Ryft, use one of Gr4vy’s client-side integration methods to securely collect card details. Due to PCI compliance requirements, card data should never be sent directly to your servers. You can integrate using:
  • Embed - A pre-built, customizable payment form that handles the complete payment flow
  • Secure Fields - Embed card input fields for building custom payment forms while maintaining PCI compliance
  • Mobile SDKs - Native SDKs for iOS, Android, React Native, and other platforms
These methods handle card data collection and tokenization. Once the card details are collected and tokenized, create a transaction through the Gr4vy API, which routes the payment to your configured Ryft connection based on your Flow rules or explicit payment_service_id parameter.

​
3-D Secure

When the card issuer asks for authentication, the transaction moves to buyer_approval_pending and returns an approval_url. Send the buyer to that URL, where Ryft runs the 3-D Secure challenge. Gr4vy then retrieves the result from Ryft and completes the transaction. When you create the transaction through the API, set redirect_url on the payment_method so the buyer returns to your site after the challenge. Embed and the mobile SDKs handle this for you.

​
Stored cards and recurring payments

Set store to true to save the card as a Gr4vy payment method. You can then use it for later customer-initiated payments, and for merchant-initiated subscription, installment, and unscheduled card-on-file payments. Set payment_source on every transaction in the series. For each later merchant-initiated payment, also set merchant_initiated and is_subsequent_payment to true. See recurring payments for the full set of flags for each scenario. Ryft keeps each stored card on a Ryft customer record. Gr4vy looks up that record for you on every payment, so no extra fields are needed.

​
Connection options

Use connection_options under the ryft-card key to route a payment to a Ryft sub-account and to take a platform fee on it. Both options are optional.

​
Sub-accounts

When sub_account_id is set, Gr4vy sends every request for the transaction to Ryft on behalf of that sub-account. This includes 3-D Secure, captures, voids, refunds, and syncs, so you only need to send the option when you create the transaction.

​
Platform fees

When platform_fee is set, Ryft moves the fee from the payment to your main account and settles the rest to the sub-account. For a delayed capture, Gr4vy applies the same fee when the transaction is captured, so there is no need to send it again. Platform fees only apply to payments made on behalf of a sub-account, so send platform_fee together with sub_account_id. By default, a refund is taken from the sub-account’s balance and the main account keeps its platform fee. To refund the platform fee as well, enable Include platform fees in refunds on the connector. The main account then bears the cost of the refunded fee. This setting applies to every refund on the connector, including partial refunds. For more on how Ryft handles fees, see the Ryft refunds documentation.

​
Testing

Use the Ryft sandbox with the test cards from the Ryft test cards documentation. The page lists cards for 3-D Secure frictionless and challenge flows, and cards that trigger specific issuer declines. To test American Express, enable the Amex capability on your sandbox account first, as described in Enable American Express.