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

# Credit API

> Push funds from Meridian's sponsored account to a customer's account at the home bank.

The Credit API is the bank partner's endpoint for receiving and processing payout instructions from Meridian. Meridian calls it each time a product event requires funds to be pushed to a customer — for example, when a customer initiates a withdrawal from a Retail Virtual Account.

Meridian's Implementation team integrates with the bank partner's Credit 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 Credit 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

Meridian sends a credit instruction to the bank partner's Credit API with the transfer amount and relevant customer details. The bank executes an intra-bank transfer from Meridian's sponsored account to the customer's 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 Credit API requirements during onboarding.
  </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 credit instruction. Meridian confirms exact fields during onboarding.
  </Step>

  <Step title="Account validation">
    If the bank exposes a validation endpoint, Meridian can confirm recipient account eligibility before executing a credit.
  </Step>

  <Step title="Commit credit">
    Meridian submits the credit instruction to the bank partner's API to initiate the actual money movement from Meridian's sponsored account to the customer's account.
  </Step>

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

## Planning considerations

If you are building a Credit API for the first time, account for the following before development begins.

**Idempotency** — Meridian includes a unique transaction ID with every credit instruction. The Credit API must use this ID to detect and safely reject duplicate requests, ensuring a customer is never credited twice for the same transaction.

**Response model** — `commitCredit` 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.

## Reference implementation

If the bank partner does not have an existing Credit API, the following endpoints provide a recommended baseline. Meridian can use this as a starting point during the scoping and requirements phase.

| Endpoint         | Purpose                                                                                                                                                              |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createCredit`   | Establishes the transaction and handles any required setup before money movement begins.                                                                             |
| `validateCredit` | Confirms recipient account eligibility before a credit is attempted.                                                                                                 |
| `commitCredit`   | Initiates the actual money movement from Meridian's sponsored account to the customer's 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. |