Skip to main content
SPEI is a Mexican bank transfer scheme that provides real-time bank transfers using a reference number.

​
Supported countries and currencies

Stripe supports transactions from buyers in MX. Stripe supports processing payments in MXN. Follow the Stripe setup instructions before configuring SPEI.

​
Configuration

For shared APM credentials, see Stripe APM credentials.

​
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. 
var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "MXN",
        Country = "MX",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
                new RedirectPaymentMethodCreate()
                {
                    Method = "spei",
                    RedirectUrl = "https://example.com/callback",
                }
            ),
    }
);
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. 
var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "MXN",
        Country = "MX",
        IntegrationClient = "ios",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
                new RedirectPaymentMethodCreate()
                {
                    Method = "spei",
                    RedirectUrl = "myapp://callback",
                }
            ),
    }
);
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": "ios"
}