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

# Status webhook

> Push a final transaction status to Meridian instead of waiting for polling.



## OpenAPI

````yaml products/bank-transfers/credit-api-example/credit-api-example.yaml webhook creditStatusChanged
openapi: 3.1.0
info:
  title: Meridian Credit API — Reference Specification
  version: 1.0.0
  summary: >-
    Recommended API surface for bank partners receiving credit (payout)
    instructions from Meridian.
  description: >
    This is Meridian's **reference specification** for a bank partner Credit
    API. It is the API the

    **bank partner hosts** and **Meridian calls** whenever a product event
    requires funds to be pushed

    from Meridian's sponsored account to a customer's account at the home bank
    (for example, a customer

    withdrawal from a Retail Virtual Account).


    Partners are not required to implement this exact contract — Meridian adapts
    to existing partner

    APIs during onboarding. However, partners building a Credit API from scratch
    should start here:

    an API matching this specification plugs directly into Meridian's
    integration layer with minimal

    custom mapping, which shortens the integration timeline considerably.


    ## Lifecycle


    Meridian drives every credit through the same sequence:


    1. **`POST /credits`** (optional) — register the credit instruction ahead of
    any processing.
       The bank persists the data structure and returns `RECEIVED`. No checks against the recipient
       account, no money movement.
    2. **`POST /credits/validate`** (optional but recommended) — confirm the
    recipient account can
       receive the credit before any money movement. No funds move. Safe to call repeatedly.
    3. **`POST /credits/commit`** — execute the transfer. Idempotent on
    `transactionId`.

    4. **`GET /credits/{transactionId}`** — retrieve the current status.
    Meridian's workflow engine
       polls this until the credit reports `COMPLETED` or `FAILED`; it may also call it **before**
       commit as a pre-check, so an unknown `transactionId` must return `404` (not an error status),
       which Meridian treats as "not yet committed" rather than a failure.
    5. **Status webhook** (optional) — proactively notify Meridian of a final
    status instead of
       waiting for polling. See the `webhooks` section.

    Steps 1 and 2 are independent: Meridian may call validate without a prior
    create, and commit

    without either. Every request carries the full instruction payload, so no
    step depends on

    bank-side state from an earlier one.


    ## Response model


    If your core system can settle synchronously, returning a final result
    (`COMPLETED` or `FAILED`)

    straight from `commit` lets Meridian update the customer sooner. Meridian
    does not depend on it,

    though: it polls the status endpoint until the credit is terminal either
    way, so a synchronous

    final result is an optimization rather than a requirement.


    Most partners settle asynchronously. That is the expected case: return
    `PROCESSING` from commit

    and expose the final state via `GET /credits/{transactionId}` and, ideally,
    the status webhook.

    Align the polling and retry strategy with Meridian during onboarding.


    ## Idempotency


    `transactionId` is Meridian's unique identifier for the credit and is the
    idempotency key.

    If a `commit` is received for a `transactionId` that was already processed,
    return the original

    outcome (do not credit twice). If the payload differs from the original
    request for the same

    `transactionId`, return `409`.


    ## Business failures vs transport failures


    A credit that is *received and rejected by business rules* (account closed,
    limit exceeded,

    compliance block) is a **`200` response** with `status: FAILED` plus a
    machine-readable

    `errorCode`. Reserve `4xx`/`5xx` for malformed requests, authentication
    failures, and genuine

    server faults. This distinction is load-bearing: Meridian retries transport
    failures but treats

    business failures as final.


    ## Conventions


    These are the conventions used throughout this specification. They are
    recommendations, not

    requirements — Meridian can adapt to the bank's preferred formats during
    onboarding.


    - Amounts are strings with up to 2 decimal places (never floats), with an
    ISO 4217 currency code.

    - Country codes are ISO 3166-1 alpha-2 (`PH`, `US`).

    - Timestamps are RFC 3339 / ISO 8601 with timezone offset.

    - All requests and responses are `application/json` over HTTPS (TLS 1.2+).
  contact:
    name: Meridian Implementation Team
    url: https://docs.mnai.com/products/bank-transfers/credit-api
servers:
  - url: https://api.examplebank.com/meridian/v1
    description: Production (partner-hosted)
  - url: https://sandbox.examplebank.com/meridian/v1
    description: Sandbox (required before go-live)
security:
  - bearerAuth: []
tags:
  - name: Credits
    description: Validate, execute, and track credit (payout) instructions.
paths: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Assume OAuth 2.0 client credentials issued by the bank, presented as a
        bearer token.

        Meridian can adapt to the bank's preferred authentication scheme during
        onboarding.

````