Pay by bank

Pay by bank lets your customer pay for a gift card straight from their UK bank account, using Faster Payments, instead of paying by card. The customer approves the payment in their own banking app, so no card details are involved.

Before you build: pay by bank is for Full API publishers where Spendstream collects the payment. Ask your Spendstream contact to confirm it is available for your account.

How it works

sequenceDiagram
    participant C as Customer
    participant P as Your app
    participant S as Spendstream API
    C->>P: Chooses a gift card and "Pay by bank"
    P->>S: GET getBanksList
    S-->>P: List of banks
    C->>P: Chooses their bank
    P->>S: POST getPayByBankLink
    S-->>P: payment_link and order-id
    P->>C: Redirect to payment_link
    C->>C: Approves the payment in their banking app
    C->>S: Returns to Spendstream
    S-->>P: TRANSACTION_UPDATED webhook (gift card issued)

Build it step by step

Step 1: Show the customer their banks

Call List the UK banks a customer can pay from (GET /getBanksList). Show the bank name and logo, and keep the bank-code of the one the customer chooses.

Step 2: Create the payment link

Call Create a pay by bank link for a gift card purchase (POST /getPayByBankLink). Send the chosen promotion, the amount, the customer’s email and the bank-code as bankCode.

curl -X POST "https://staging-api.spendstream.io/v2/getPayByBankLink" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"promo_id":25,"user_id":"user-123","email":"customer@example.com","name":"Alex Example","currency":"GBP","amount":20.00,"bankCode":"example_bank_gb"}'

{
  "payment_link": "https://example.com/pay-by-bank/link",
  "response": 200,
  "order-id": "17918003116accb3f7b5269"
}

Fields to send:

• promo_id (required): the promotion-id from getPromotionsList, not the brand-id.
• user_id (required): your identifier for the customer. The user is created for you if Spendstream has not seen it before.
• email (required): the customer’s email address.
• amount (required): the gift card amount in pounds.
• currency (required): GBP. Pay by bank is in pounds sterling only.
• bankCode (required): the bank-code from getBanksList.
• name (optional): the customer’s name.

Step 3: Send the customer to their bank

Redirect the customer to payment_link and keep the order-id. They approve the payment in their banking app and come back to Spendstream.

Step 4: Wait for the result

Spendstream confirms the payment, issues the gift card and sends the usual TRANSACTION_UPDATED webhook, which carries your order-id. Check the webhook security guide before you act on it.

Things to know

• Not every bank is listed. Only banks that support Faster Payments appear in getBanksList. If a chosen bank is not supported you get This bank does not support Faster Payments.
• Check the response. Some failures return HTTP 200 with a message and no payment_link. Look for payment_link before redirecting.
• Payments can take a little while. Your customer’s bank sometimes takes a short time to confirm. Do not issue anything yourself: wait for the TRANSACTION_UPDATED webhook.
• Use the order-id to match the result to the purchase in your system.

Payment statuses

💡 Tip: Status detail for pay by bank is coming soon.

Bank payments can take a little while to be confirmed by the customer’s bank. We are working closely with our payments provider to make the status of each payment as accurate and timely as possible, and we will publish the full list of statuses here once that work is complete. Thank you for bearing with us.

In the meantime, you do not need to track bank statuses yourself. When a payment succeeds, the gift card is issued and you receive a TRANSACTION_UPDATED webhook as usual. If the customer cancels or the bank declines the payment, no gift card is issued.

Testing

There is no test mode for pay by bank. A payment moves real money, and our payment provider allows a single callback address, which points at production. Please arrange a small test payment with Spendstream before you go live.

Related pages

• Payments guide: float, hosted payments and how they fit together
• Hosted payment model: paying by card on a hosted page instead
• Gift cards guide: promotions, brands and issuing cards
• Authentication: getting a token
• Go-live checklist