> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ryft - Card

> Connect to Ryft to accept credit and debit card payments, with sub-account routing and platform fees for marketplaces.

**Ryft**

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](https://www.ryftpay.com/) 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](https://developer.ryftpay.com/documentation/get_started/portal/settings#capabilities) 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](https://developer.ryftpay.com/documentation/get_started/portal) 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](#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](https://developer.ryftpay.com/documentation/get_started/webhooks).

## 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](/guides/dashboard/flow/overview.md) 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

This list is for guidance only. It doesn't guarantee availability or
create any rights, and the provider may need to enable some features for
your account.

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

> [!NOTE]
>
> This is a closed-loop connector. Some failover scenarios are limited. For
> details, see [Open-loop versus
> closed-loop](/guides/features/recurring-payments/open-loop.md).

## 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](/guides/payments/embed/quick-start)** - A pre-built, customizable payment form that handles the complete payment flow
* **[Secure Fields](/guides/payments/secure-fields/quick-start)** - Embed card input fields for building custom payment forms while maintaining PCI compliance
* **[Mobile SDKs](/guides/payments/mobile.md)** - Embed SDKs for iOS, Android, and React Native

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](/guides/features/recurring-payments/overview.md) 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.

Because Ryft stores the card, Ryft keeps and replays the [Mastercard Transaction Link Identifier (TLID)](/guides/features/recurring-payments/mastercard-tlid.md) itself. Nothing is needed from you or from Gr4vy.

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

| Option | Type | Description |
| - | - | - |
| `sub_account_id` | string | The ID of a Ryft sub-account linked to your main account, for example `ac_123456789`. The payment is made on behalf of that sub-account. |
| `platform_fee` | integer | The fee your main account keeps from the payment, in the smallest currency unit (for example `205` for £2.05). Must be between `0` and `2000000`, and can't be more than the transaction amount, or Ryft rejects the payment. |

```json theme={"system"}
{
  "amount": 5000,
  "currency": "GBP",
  "country": "GB",
  "payment_method": {
    "method": "checkout-session",
    "id": "[CHECKOUT_SESSION_ID]"
  },
  "connection_options": {
    "ryft-card": {
      "sub_account_id": "ac_123456789",
      "platform_fee": 205
    }
  }
}
```

### 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](https://developer.ryftpay.com/documentation/get_started/manage_payments/refund).

## Testing

Use the Ryft sandbox with the test cards from the [Ryft test cards documentation](https://developer.ryftpay.com/documentation/get_started/process_payments/test_cards). 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](#enable-american-express).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.