> ## 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. # Get transaction status > Retrieve the current status of a credit, polled by Meridian until the transaction is terminal. ## OpenAPI ````yaml products/bank-transfers/credit-api-example/credit-api-example.yaml GET /credits/{transactionId} 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: /credits/{transactionId}: get: tags: - Credits summary: Get the transaction status description: > Returns the current status of a credit. Meridian's orchestration is built on durable workflows (Temporal) whose activities poll this endpoint with automatic retries until the transaction is final. That model imposes four requirements: 1. **Poll-until-final contract** — `COMPLETED` and `FAILED` are the terminal statuses. Meridian keeps polling while a credit reports `RECEIVED`, `VALIDATED`, or `PROCESSING`, and stops as soon as it reports `COMPLETED` or `FAILED`. Once terminal, the status must never change. 2. **Monotonic status** — a transaction's status must only move forward (`RECEIVED → VALIDATED → PROCESSING → COMPLETED|FAILED`, skipping steps is fine). Retried activities may observe the same transaction many times, out of order relative to other calls; a status that regresses or flips between finals breaks workflow determinism. `UNKNOWN` is exempt: it can be reported at any point and can be followed by any status. 3. **Idempotent and read-only** — calling this endpoint any number of times must have no side effects. 4. **`404` for unknown `transactionId`** — never a `200` with `FAILED`. Meridian interprets `404` as "not committed yet" (retryable): workflows call this endpoint before commit as an existence check, and after transport timeouts where the commit may never have arrived. A `FAILED` here would terminate the workflow with a wrong outcome. The endpoint must keep answering for finished transactions for a reconciliation window agreed during onboarding (30 days minimum recommended). operationId: getCreditStatus parameters: - name: transactionId in: path required: true description: >- Meridian's unique transaction identifier, as sent in the credit instruction. schema: type: string maxLength: 64 responses: '200': description: Current status of the credit. content: application/json: schema: $ref: '#/components/schemas/CreditResult' '401': $ref: '#/components/responses/Unauthorized' '404': description: >- No credit exists for this `transactionId` (treated by Meridian as retryable / not yet committed). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: errorCode: TRANSACTION_NOT_FOUND errorMessage: No credit found for transactionId mrdn-9f2c1e4a. '500': $ref: '#/components/responses/ServerError' components: schemas: CreditResult: type: object description: Outcome of a validate, commit, or status call. One shape for all three. required: - transactionId - status properties: transactionId: type: string description: Echo of Meridian's transaction identifier. status: $ref: '#/components/schemas/CreditStatus' bankReference: type: string maxLength: 64 description: > The bank's own reference for the transfer, if one exists. Meridian stores this for reconciliation and support. Include it on every response after commit. errorCode: type: string description: > Machine-readable failure code. **Required whenever `status` is `FAILED`.** Use a stable, documented set; Meridian maps these to customer-facing outcomes. Recommended baseline: - `ACCOUNT_NOT_FOUND` - `ACCOUNT_INACTIVE` - `NAME_MISMATCH` - `LIMIT_EXCEEDED` - `INVALID_AMOUNT` - `COMPLIANCE_REJECTED` - `INSUFFICIENT_FUNDS` (sponsored account) - `DUPLICATE_TRANSACTION` - `BANK_SYSTEM_ERROR` errorMessage: type: string maxLength: 500 description: >- Human-readable detail for the failure. Not shown to customers verbatim. completedAt: type: string format: date-time description: RFC 3339 timestamp when the credit reached a final status. ApiError: type: object description: Transport-level error payload for 4xx/5xx responses. required: - errorCode - errorMessage properties: errorCode: type: string errorMessage: type: string CreditStatus: type: string description: > Transaction state machine: - `RECEIVED` — registered; nothing checked and nothing moved - `VALIDATED` — the recipient account passed eligibility checks - `PROCESSING` — money movement is underway - `COMPLETED` — terminal; the funds reached the recipient - `FAILED` — terminal; the credit will not be delivered - `UNKNOWN` — outcome not yet determinable, for example a timeout in your core system or an unreachable downstream rail; not terminal Status moves only forward through that order, though skipping steps is fine, and terminal statuses must never change once reported. `UNKNOWN` is exempt from the ordering and may be followed by any status. Prefer it over guessing `FAILED`, since a terminal status can never be walked back. enum: - RECEIVED - VALIDATED - PROCESSING - COMPLETED - FAILED - UNKNOWN responses: Unauthorized: description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/ApiError' ServerError: description: Unexpected bank-side failure. Meridian treats this as retryable. content: application/json: schema: $ref: '#/components/schemas/ApiError' 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. ````