Skip to main content

​
Sign up

Stripe provides self-service sign up for sandbox accounts. To sign up for an account, visit the sign up page.

​
Credentials

When setting up the SPEI via Stripe connection in the dashboard, the following credentials can be configured:

​
Secret key

A Stripe Secret key can be found in the Stripe Dashboard within Developer Settings under API keys.

​
Webhook secret

A Stripe Webhook Secret can be found in the Stripe Dashboard within Developer Settings under Webhooks once webhooks have been configured (see Webhooks below).

​
Stripe connected account (when applicable)

If using Stripe Connect, you can set the Stripe Account ID of the connected account that you intend to use for all transactions through the connection.

​
Approval URL (optional)

By default, the connector returns an approval URL that redirects buyers to a Stripe-hosted page with instructions for completing a bank transfer. If required, you can set a different approval URL here which allows you to build your own page for showing bank transfer instructions to buyers. When set, the Approval URL is returned with a Session Token appended as a query parameter named token. This Session Token can be used with the Transaction Session API to retrieve the details required to build your own page.

​
Webhooks

SPEI payments and refunds are completed asynchronously, so webhooks must be configured to update the status of transactions. Webhooks are configured in the Stripe Dashboard within Developer Settings under Webhooks. The SPEI connector relies on the following Stripe webhooks:
  • payment_intent.succeeded
  • payment_intent.partially_funded
  • payment_intent.canceled
  • charge.refund.updated

​
Integration

The default integration for SPEI via Stripe uses a redirect to a payments page hosted by Stripe.

​
Redirect integration

Start by creating a new transaction with the following required fields.
POST /transactions
{
  "amount": 100,
  "currency": "MXN",
  "country": "MX",
  "intent": "capture",
  "payment_method": {
    "method": "spei",
    "redirect_url": "https://example.com/callback",
    "country": "MX",
    "currency": "MXN"
  }
}
After the transaction is created, the API response includes a payment_method.approval_url and the status is set to processing. 
{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://payments.stripe.com/bank_transfers/instructions/test..."
  },
  "method": "spei"
}
Redirect the buyer to the approval_url (open in a browser or Webview), where they see instructions for completing a bank transfer. Once the buyer completes a bank transfer, the transaction progresses to a capture_succeeded state in response to a webhook from Stripe.

​
Direct integration

If you intend to use your own hosted page for presenting the buyer with bank transfer instructions, you can include an integration_client parameter set to web, ios or android when creating a new transaction. 
POST /transactions

{
    "amount": 100,
    "currency": "MXN",
    "country": "MX",
    "intent": "capture",
    "integration_client": "web",
    "payment_method": {
    "method": "spei",
    "redirect_url": "https://example.com/callback",
    "country": "MX",
    "currency": "MXN"
    }
}
After the transaction is created, the API response includes a session_token. You use this token with the session endpoint to retrieve the session data for the transaction and build a custom page that displays the bank transfer instructions. 
POST /transactions/:transaction_id/session?token=:session_token

{
    "session_data": {
        "paymentIntentId": "pi_3StlgnRAbJldLcy50NYwrdAN",
        "bankTransferInstructions": {
            "type": "mx_bank_transfer",
            "currency": "mxn",
            "reference": "266688",
            "amount_remaining": 1000,
            "financial_addresses": [
                {
                    "spei": {
                        "clabe": "124180613177193525",
                        "bank_code": "124",
                        "bank_name": "CITI MEXICO",
                        "bank_address": {
                            "city": "Naucalpan",
                            "line1": "Blvd. Manuel Avila Camacho 1902",
                            "line2": "Planta Baja, Cd. Satelite",
                            "state": "Estado de Mexico",
                            "country": "MX",
                            "postal_code": "C.P. 53100"
                        },
                        "account_holder_name": "Gr4vy sandbox",
                        "account_holder_address": {
                            "city": "Ciudad de México",
                            "line1": "Av Paseo de la Reforma 180 piso 29 col Juarez",
                            "line2": null,
                            "state": "Ciudad de México",
                            "country": "MX",
                            "postal_code": "06600"
                        }
                    },
                    "type": "spei",
                    "supported_networks": [
                        "spei"
                    ]
                }
            ],
            "hosted_instructions_url": "https://payments.stripe.com/bank_transfers/instructions/test_YWNjdF8xU29peEtSQWJKbGRMY3k1LF9UcnRKS1JrUExGMHVUTmR6bjVJQWxOWGd3SXpoNks20100O3vRPYrH"
        }
    },
    "default_completion_url": "https://example.com/callback",
    "integration_client": "web"
}