If the bank partner does not have an existing Debit API, Meridian can provide consultation to help scope the integration and define requirements before development begins. See Reference implementation below for a recommended starting point.
How it works
When a customer converts local currency between their home bank accounts, Meridian sends a debit instruction to the bank partner’s Debit API. The instruction includes the transfer amount and relevant customer details. The bank executes an intra-bank transfer from the customer’s local currency account into Meridian’s sponsored account at the home bank. The bank then returns a confirmation, and Meridian uses it to update the transaction status.Integration requirements
Authentication
Meridian supports multiple authentication methods and aligns with the bank partner’s Debit API requirements during onboarding.
Authorize debit (optional)
Some banks require a one-time approval before funds can be pulled from a customer’s account. If required, Meridian will request authorization before proceeding to commit the debit.
Request payload
Meridian formats the request body according to the bank partner’s specification, including any required encryption or signing. Meridian passes transaction details and sender/recipient KYC data with every debit instruction. Meridian confirms exact fields during onboarding.
Account validation
If the bank exposes a validation endpoint, Meridian can confirm the source account is eligible and has sufficient funds before executing a debit.
Commit debit
Meridian submits the debit instruction to the bank partner’s API to initiate the actual money movement from the customer’s account into Meridian’s sponsored account.
Planning considerations
If you are building a Debit API for the first time, account for the following before development begins. Idempotency — Meridian includes a unique transaction ID with every debit instruction. The Debit API must use this ID to detect and safely reject duplicate requests, ensuring a customer is never debited twice for the same transaction. Response model —commitDebit should return a final result synchronously. This allows Meridian to update the transaction status immediately and deliver the best customer experience. If the bank’s core system cannot support a synchronous response, an asynchronous model is possible — Meridian will poll getStatus to confirm the outcome. Treat this as a fallback and align it with Meridian during scoping.
Sandbox environment — A non-production environment is required before go-live. Meridian will use it to validate the integration end-to-end before any real money movement occurs.
Insufficient funds handling — Unlike a credit, a debit can fail because the source account does not have enough funds. The bank must provide clear error codes for this scenario, and you should define a retry strategy with Meridian during onboarding.
Reference implementation
If the bank partner does not have an existing Debit API, the following endpoints provide a recommended baseline. Meridian can use this as a starting point during the scoping and requirements phase.| Endpoint | Purpose |
|---|---|
authorizeDebit | (Optional) Requests one-time approval from the bank before funds can be pulled from the customer’s account. |
createDebit | Establishes the transaction and handles any required setup before money movement begins. |
validateDebit | Confirms the source account is eligible and has sufficient funds. |
commitDebit | Initiates the actual money movement from the customer’s account into Meridian’s sponsored account. |
getStatus | Fetches the current transaction status to confirm success or failure. Must support detailed error codes and align on retry strategy with Meridian during onboarding. |