Draft API Preview for the MorphosisBlock Payment API. Error codes and retry guidance are proposed contract material. They are not evidence of an available service.

Errors

Non-success responses use one stable JSON envelope so merchants can log a request identifier without exposing request bodies or credentials. Use the HTTP status for the broad failure class, code for application logic, and request_id when correlating a failed request.

{
  "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_01K1DRAFT8F7Z6K5Q4N3M2P1A0"
}

The URI is a stable documentation identifier and is not a callable endpoint.

Draft 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

Error messages are for people and may change. Branch application logic on code, not title or detail.

Idempotency

POST /v2/payments requires an Idempotency-Key containing 16 to 128 ASCII characters. The draft permits letters, numbers, ., _, ~, and -, with a letter or number as the first character.

Idempotency-Key: idem_docs_20260730_0001

Generate one key when a merchant order first enters payment creation. Persist it with the order before sending the request.

Required behaviour

Reuse the same key only with byte-for-byte equivalent logical content.
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.
Do not promise the customer that creation failed.
Wait for an authoritative payment response or payment.updated event before proceeding.

This preview does not promise that replaying a create request is available or safe. A launch contract must define and test server-side idempotency retention and recovery before merchants are instructed to replay writes.

Logging

Log the payment identifier, merchant reference, idempotency key, error code, request identifier, HTTP status, and timestamp. Do not log request-signing secrets, signatures, full authentication headers, customer personal data, or raw webhook bodies.

Getting started

Guides

API reference

Errors and idempotency

Errors

Draft error catalogue

Idempotency

Required behaviour

Ambiguous create outcome

Logging

​Errors

​Draft error catalogue

​Idempotency

​Required behaviour

​Ambiguous create outcome

​Logging

Errors

Draft error catalogue

Idempotency

Required behaviour

Ambiguous create outcome

Logging