Skip to main content

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.

Stripe is a global payments platform that supports card processing and a broad set of alternative payment methods.

​
Supported payment methods

MethodCountriesCurrenciesNotes
CardAD, AE, 247 moreAED, AFN, 130 moreEnable card payments in your Stripe account.
AffirmCA, USCAD, USDBNPL availability depends on buyer eligibility.
KlarnaCA, GB, USCAD, GBP, USDBNPL availability depends on buyer eligibility.
OXXOMXMXNCash voucher flow with redirect.
SPEIMXMXNBank transfer flow with redirect.

​
Setup

Stripe provides a self-service sign-up for a sandbox account. To sign up for an account visit the sign-up page and fill in the details.

​
Credentials

When setting up Stripe in the dashboard, configure the following credentials, which are obtained from Stripe:

​
Secret key

The Stripe Secret key can be found in the Stripe Admin Portal under the Developers -> API Keys section.

​
APM credentials

When setting up Stripe APMs in the dashboard, configure the following credentials:
  • Webhook secret: Find this in the Stripe Dashboard within Developer Settings under Webhooks once webhooks have been configured.
  • Stripe connected account: Set this when using Stripe Connect. See Stripe Connect below.
  • Publishable key: Used to initialize the Gr4vy hosted web page on a redirect.

​
Stripe Connect

Stripe Connect lets a platform account make API calls on behalf of a connected merchant account. This configuration is optional. Leave it empty for standard (non-Connect) integrations where all transactions run directly on the platform account.

​
Credential field

Most Stripe connectors expose a Stripe connected account field in the connection settings. Setting it applies the connected account to every operation on that connection.

​
Per-transaction override

To route individual transactions to different connected accounts, pass the connected account as a connection option when creating a transaction. 
{
  "connection_options": {
    "stripe-card": {
      "stripe_connect": {
        "stripe_account": "acct_1OcAyNGbm1cKE2pL"
      }
    }
  }
}
When present, the per-transaction value takes precedence over the credential field for that operation. Routing individual transactions to a different account can have undesired side effects (see webhooks below).

​
Webhooks with Stripe Connect

When a connected account is configured, incoming webhooks are matched against the configured Stripe account. Events that belong to a different account are rejected. If you process payments across multiple connected accounts, configure a separate Stripe connection for each account with the matching connected account ID.
Changing the connected account on an existing Stripe connection breaks all in-flight transactions created under the previous account ID. Stripe objects (payment intents, payment methods, customers) are scoped to the account that created them. A capture, void, or refund attempted against a payment intent created under a different account fails.If you need to change the connected account, create a new connection for the new account and keep the old connection active until all in-flight transactions have settled.

​
APM payment IDs

When creating the transaction, the payment_service_transaction_id is the client secret, and in the extra_xids field you can find the payment intent ID as payment_id. After the transaction is approved by the user, the payment_service_transaction_id is updated to the payment intent ID.

​
Webhooks

Webhooks are useful as they allow receiving updates about transactions processed. This can be configured in the Stripe dashboard by creating an event destination. Please enable Stripe webhooks only for the following events, to ensure minimal processing delays.
  • payment_intent.canceled
  • charge.expired
  • charge.refund.updated
  • charge.refunded
  • payment_intent.succeeded
  • payment_intent.amount_capturable_updated
  • payment_intent.payment_failed

​
Recurring payments

The Stripe connector can operate as either an open or a closed-loop connector. In a closed-loop configuration a Stripe token is used for every transaction, which means you can not process a subsequent payment with another provider. In an open-loop situation card data from the vault is used for every transaction, allowing processing transactions in a recurring payments with a different payment service for every transaction. By default, your Stripe connector works in a closed-loop configuration, as Stripe requires open-loop to be enabled for your account before transactions can be processed that way. Open-loop can be enabled in the connection settings through the dashboard. After enabling open-loop and saving the changes, a new check-box appears to enable network tokens. Please contact the support team for additional guidance.

​
Digital wallets

Recurring Apple Pay and Google Pay are supported through Stripe in a close-loop configuration. For this to work you need to contact Stripe to get decoded Apple and Google Pay token pass-through enabled on their /v1/tokens API. Recurring digital wallet payments on Stripe in an open-loop configuration are currently not supported as this requires a different Stripe API. Support for this is planned for the near future.

​
Gated features

Stripe gates certain features on the platform. In case the following errors are encountered, please reach out to Stripe as mentioned below.

​
Access to raw card data

The integration relies on the ability to pass Stripe the full card PAN. If you encounter an error Sending credit card numbers directly to the Stripe API is generally unsafe. We suggest you use test tokens that map to the test card you are using, see https://stripe.com/docs/testing. To enable testing raw card data APIs, see https://support.stripe.com/questions/enabling-access-to-raw-card-data-apis., please contact Stripe’s support team to enable raw card data API.

​
Use of statement_descriptor field

If you encounter an error statement_descriptor parameter is not supported for the payment_method_type card, please contact your Stripe technical account manager to enable this feature. In the meantime, you can enable the Remove statement descriptor toggle in the Stripe connector settings in the Gr4vy dashboard. Note that Stripe deprecates the statement_descriptor field for card payments. By default, Gr4vy sends the statement_descriptor_suffix field instead. If you want to keep using the older field, enable the Use legacy statement descriptor toggle in the Stripe connector settings in the Gr4vy dashboard.