Bank Transfers & SPEI

How bank transfers work

A bank transfer is a push payment: instead of Shuttle pulling money from the
customer's account, Stripe issues a set of bank details and the customer sends the
money themselves from their own banking app. Nothing is collected until they do.

This is the opposite of a card payment or a direct debit, and it changes the shape
of the transaction — the payment is created, sits pending while the customer
goes away and makes the transfer, and only completes when Stripe matches the
incoming funds against it. That can be minutes or days later.

Where it is available

Bank transfer is enabled per gateway in the Stripe connection settings, and must
also be enabled on your Stripe account. The rail used depends on the currency:

A payment in any other currency will not offer bank transfer.

📘

MXN needs a Mexican Stripe account

SPEI is gated by the Stripe account's settlement currency. A UK, EU or US Stripe
account will reject an MXN payment with currency mxn invalid — the merchant's
Stripe account must be registered in Mexico and settle in MXN. This is account
configuration, not a setting in Shuttle.

The customer journey

• Payment created — the customer chooses Pay By Bank Transfer at checkout.
• Instructions issued — Stripe returns the bank details to pay to. For SPEI this
  is a CLABE and a reference; other rails return the equivalent account details.
  Shuttle shows the customer a link to those instructions.
• Transaction is pending — the payment is recorded as Pending. No money has
  moved yet.
• Customer transfers the money — from their own bank, using the details above.
• Stripe matches the funds — Stripe notifies Shuttle and the transaction is
  marked as Approved.

Bank transfers are for one-off payments. There is no mandate, so a bank transfer
cannot be saved as a payment method or used for recurring contracts.

How this works in Shuttle

While the payment is waiting for the customer, the transaction is Pending and
carries a sub-status saying so:

sub_status is on the transaction and
payment objects, and can be searched on
(criteria=sub_status=CUSTOMER_ACTION_REQUIRED). A transaction with no sub_status
— or NO_ACTION_REQUIRED — is not waiting on anybody.

Use it to tell the two kinds of pending apart: a pending card or direct debit is
being processed by the bank, whereas a pending bank transfer is waiting for the
customer to actually send the money.

Partial payments

If the customer transfers less than the full amount, Stripe holds what arrived and
the payment stays pending with sub_status_reason of partially_funded. The
customer is shown the amount still outstanding and can top it up against the same
instructions.

If the customer never pays

An unfunded transfer produces no final notification from Stripe, so Shuttle sets an
expiry window when the payment is created. The window is the "Bank Transfer - days
before an unpaid pending payment expires" gateway setting (default 14 days,
valid range 1–90).

When the window is reached, Shuttle re-checks the payment with Stripe:

Multibanco is not covered by this window — Stripe expires its vouchers itself.

Refunds

SPEI (MXN) payments cannot be refunded from Shuttle. SPEI is a push-only rail
and cannot be reversed, so a refund attempt is blocked with a message telling the
operator to refund manually in the Stripe dashboard by returning the funds to the
customer's CLABE.

The other bank transfer rails have the same underlying limitation — the money is
returned to the customer's account via Stripe's customer balance rather than being
reversed down the original path — so treat bank transfer refunds as a manual
operation in every currency.

Enabling bank transfer

• Enable bank transfers on your Stripe account (Stripe dashboard → Settings →
  Payment methods).
• In the Shuttle admin portal, open the Stripe gateway settings and enable
  Enable Bank Transfer.
• Optionally set "Bank Transfer - days before an unpaid pending payment expires".
  Leave it blank for the 14-day default.
• Save the gateway settings.

See Connecting Stripe for the full list of connection
options.