> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debit API

> Pull funds from a customer's account into Meridian's sponsored account at the home bank.

The Debit API is the bank partner's endpoint for receiving and processing pull instructions from Meridian. Meridian calls it each time a product event requires funds to be pulled from a customer — for example, when a customer converts local currency between their home bank accounts.

Meridian's Implementation team integrates with the bank partner's Debit API during onboarding. The exact specification is partner-dependent, and Meridian adapts to what the bank provides.

<Note>
  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](#reference-implementation) below for a recommended starting point.
</Note>

## 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

<Steps>
  <Step title="Authentication">
    Meridian supports multiple authentication methods and aligns with the bank partner's Debit API requirements during onboarding.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Transaction status">
    Meridian requires a mechanism to retrieve final transaction status after you submit a debit instruction.
  </Step>
</Steps>

## 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. |