Idempotency keys are required on create and are part of the HMAC v2 canonical string. Reusing a key with different semantic content returns 409.

Errors

Non-success responses use one stable JSON problem envelope so merchants can log a request identifier without exposing request bodies or credentials.

{
  "type": "urn:morphosisblock:payment:error:invalid-request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "The amount decimal value does not match minor_units.",
  "request_id": "req_01K1EXAMPLE8F7Z6K5Q4N3M2PA"
}

Error catalogue

HTTP status	Code	Meaning	Safe merchant action
`400`	`invalid_request`	Request syntax or fields are inconsistent	Correct the request before sending another attempt
`401`	`authentication_failed`	Authentication material is missing, stale, or invalid	Stop and repair signing or credential configuration
`404`	`payment_not_found`	The requested payment is not visible to the merchant key	Verify the locally stored payment identifier
`409`	`idempotency_conflict`	The same idempotency key was paired with different content	Stop; never alter a request while reusing its key
`422`	`payment_denied`	The payment request cannot proceed under a business rule	Do not retry the same logical request automatically

Branch application logic on code, not title or detail. A create may also return:

HTTP status	Meaning	Merchant action
`201`	Payment created with instructions	Persist and present instructions
`202`	Same payment identity, `submission_unknown`	Do not invent a new idempotency key; wait / poll / webhook

Idempotency

POST /v2/payments requires an Idempotency-Key containing 16 to 128 ASCII characters (letters, numbers, ., _, ~, -; first character alphanumeric).

Idempotency-Key: idem_docs_20260731_0001

Generate one key when a merchant order first enters payment creation. Persist it with the order before sending the request. The key is HMAC-bound: changing the key changes the signature.

Required behaviour

Reuse the same key only with equivalent validated content (external_reference, amount fields, and metadata).
Never reuse a key for another merchant order.
If a response is lost, do not invent a new key or create a second logical payment.
Treat submission_unknown as unresolved, not as success or failure.
Make downstream fulfilment idempotent independently of API idempotency.

Ambiguous create outcome

If the connection closes before a complete create response:

Preserve the merchant reference, original request body, idempotency key, timestamped attempt record, and any returned request identifier.
Do not send a new logical payment request with a different key.
Do not promise the customer that creation failed.
Replay the same signed logical create, or wait for webhook / retrieve once you have a payment_id.
Proceed only after an authoritative payment response or payment.updated event.

Getting started

Guides

API reference

Errors and idempotency

Errors

Error catalogue

Idempotency

Required behaviour

Ambiguous create outcome

​Errors

​Error catalogue

​Idempotency

​Required behaviour

​Ambiguous create outcome

Errors

Error catalogue

Idempotency

Required behaviour

Ambiguous create outcome