Skip to main content
This section is Meridian’s reference specification for a bank partner Credit API. It describes the API the bank partner hosts and Meridian calls. Meridian calls it whenever a product event requires pushing funds from Meridian’s sponsored account to a customer’s account at the home bank, such as 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. See Credit API for how that integration works.
If you are building a Credit API from scratch, start here. Every request is an ISO 20022 pacs.008 customer credit transfer and every response is an ISO 20022 pacs.002 payment status report, both sent as JSON. Meridian’s integration layer already uses this message internally, so an API matching this specification plugs in with no custom mapping. This shortens the integration timeline considerably.

​
Message format

Messages use the ISO 20022 XML tag names as JSON keys, so the structure maps one to one onto the ISO 20022 message definitions:
Every message carries exactly one transaction. See Message reference for what Meridian puts in each field, and the endpoint pages for the full schemas and examples.

​
Lifecycle

Meridian drives every credit through the same sequence:
1

Prepare Credit: create (optional)

POST /credits registers the pacs.008 ahead of any processing. The bank persists it and returns RCVD. No checks against the recipient account, and no money movement.
2

Prepare Credit: validate (optional but recommended)

POST /credits/validate confirms the recipient account can receive the credit, returning ACCP or RJCT. No funds move, and it is safe to call repeatedly.
3

Execute Credit: commit

POST /credits/commit executes the transfer. It is idempotent on EndToEndId.
4

Confirm Credit: get transaction status

GET /credits/{endToEndId} returns the current credit status. Meridian’s workflow engine polls this until the credit reports ACSC or RJCT, and may also call it before commit as a pre-check. Until the bank receives a commit, the endpoint must return 404 rather than a status, even for a credit that was created or validated. Meridian treats the 404 as “not yet committed” rather than a failure.
5

Confirm Credit: status webhook (optional)

Proactively push the final pacs.002 to Meridian instead of waiting for polling.
Create and validate are independent. Meridian may call validate without a prior create, and commit without either. Every request carries the full pacs.008, so no step depends on bank-side state from an earlier one.

​
Status codes

Every response reports a status in TxInfAndSts[0].TxSts, using ISO 20022 codes. Create and validate report the outcome of that call only. The credit status starts at commit.

​
Create and validate responses

These do not set the credit status, and the status endpoint does not report them. Validate reports the eligibility check as of the call, so repeated calls can return different results. A validate call never changes the credit status.

​
Credit status

Commit, the status endpoint, and the status webhook report these values. Before commit, the status endpoint returns 404. The credit status moves only forward, from ACSP to ACSC or RJCT, though skipping ACSP is fine. Terminal statuses must never change once reported. PDNG is exempt from the ordering: you can report it at any point after commit and follow it with any status.

​
Response model

If your core system can settle synchronously, return a final result (ACSC or RJCT) straight from commit so Meridian can update the customer sooner. This is an optimization, not a requirement. Meridian polls the status endpoint until the credit is terminal either way. Most partners settle asynchronously, and that is the expected case. Return ACSP from commit and expose the final state via GET /credits/{endToEndId} and, ideally, the status webhook. Align the polling and retry strategy with Meridian during onboarding.

​
When you cannot determine the outcome

Report PDNG when you genuinely do not know the result yet, such as a timeout inside your core system or an unreachable downstream rail. It is not a terminal status, so Meridian keeps polling, and you can follow it with any other status later.
PDNG is always better than guessing RJCT. ACSC and RJCT are terminal and can never be walked back, so a wrong guess is unrecoverable.

​
Rejection reasons

Every RJCT must carry an ISO 20022 reason code in StsRsnInf[].Rsn.Cd. Meridian maps these codes to customer-facing outcomes. Meridian holds a rejection without a reason for manual review instead of reversing it automatically, which delays the customer.

​
Idempotency

EndToEndId is Meridian’s unique identifier for the credit and serves as the idempotency key. If you receive a commit for an EndToEndId you already processed, return the original outcome and do not credit twice. If the payload differs from the original request for the same EndToEndId, return 409. Meridian sets GrpHdr.CreDtTm each time it builds a request, so leave it out of the comparison.

​
Business failures vs transport failures

When you reject a credit on business rules, such as a closed account, an exceeded limit, or a compliance block, return a 200 response. The response carries a pacs.002 with TxSts: RJCT and a reason code. Reserve 4xx and 5xx for malformed requests, authentication failures, and genuine server faults.
This distinction is critical. Meridian retries transport failures but treats business failures as final.

​
Conventions

These are the conventions used throughout this specification. Meridian can adapt to the bank’s preferred formats during onboarding.
  • Amounts (Amt) are JSON numbers with up to 2 decimal places. Parse them into a decimal type, never a binary float. Currencies are ISO 4217 codes.
  • Country codes are ISO 3166-1 alpha-2 (PH, US).
  • Timestamps are ISO 8601 with a timezone offset or Z.
  • EndToEndId and InstrId can be up to 64 characters, and MsgId up to 83. Both are longer than the ISO 20022 Max35Text limit.
  • All requests and responses are application/json over HTTPS (TLS 1.2+).
  • Ignore JSON properties you do not recognize. Meridian may add optional fields without a version change.