Prerequisites
- Lightspark has enabled open banking for your platform. Until then, creating a payment returns
403 OPEN_BANKING_NOT_ENABLED. - The customer is an individual, and their verification status is
APPROVED. - The customer has an
EURinternal account. Open banking payments fund that account only. - You have an
httpspage in your app for the customer to return to.
Fund an account by open banking
1
Create the payment
Call The payment is
POST /internal-accounts/{id}/open-banking-payments with the amount in euro cents and your redirectUrl. Send an Idempotency-Key so a retried request returns the same payment instead of starting a second one.cURL
PENDING. Grid sets its reference, which the customer sees on their bank statement.Response
2
Send the customer to their bank
Open
authorizationUrl in the customer’s browser or a web view. Avoid an iframe: many banks approve the payment by opening their own app or a full page, which an iframe can block. The customer chooses their bank, signs in, and approves the payment. The link stops working at expiresAt.3
Handle the return
When the customer leaves their bank, they land on your
redirectUrl with openBankingPaymentId added to the query, for example https://app.example.com/top-up/return?openBankingPaymentId=OpenBankingPayment:019542f5-b3e7-1d02-0000-000000000020. Any query parameters you put on redirectUrl are kept. Ignore any other parameters added on the way back.To show the current state, call GET /internal-accounts/{id}/open-banking-payments/{openBankingPaymentId}.In a native app,
redirectUrl can be a universal link (iOS) or App Link (Android), since both are https URLs. The customer reaches it through a redirect, not a tap, so the operating system may not open your app. Serve a web page at the same URL that shows the payment’s status and offers a button back to your app. To return reliably, open authorizationUrl in an authentication session (ASWebAuthenticationSession on iOS, a Custom Tab on Android) and watch for redirectUrl.4
Learn the outcome
Grid sends one
OPEN_BANKING_PAYMENT webhook when the payment reaches a final status.The credit itself is an ordinary incoming transaction. It sends its own
INCOMING_PAYMENT webhooks and updates the account balance like any other deposit.Errors
Creating a payment fails before anything is sent to the customer’s bank, so a failed request leaves nothing to clean up.403 OPEN_BANKING_NOT_ENABLED
Tracking status
Use theOPEN_BANKING_PAYMENT webhook as the source of truth. Call the GET endpoint once when the customer returns to your page, and again if you need to refresh the screen. If you must poll, wait at least 5 seconds between calls, and stop once the payment is no longer PENDING. A payment the customer approved before expiresAt can stay PENDING after it while the bank sends the funds, so don’t treat expiresAt as the end.
Sandbox
In sandbox,authorizationUrl opens a Grid page that stands in for the bank. Its button completes the payment, credits the account and sends the webhooks, then returns the customer to your redirectUrl with openBankingPaymentId, as in production.
To settle a payment without the browser, for example in automated tests, call the sandbox endpoint. Pass status: FAILED to simulate a refused payment.
cURL