Developer docs

Errors

ZOZOPAY uses standard HTTP status codes. Errors return a JSON body with a readable message.

Error format

{
  "error": "amount: Number must be less than or equal to 1000000"
}

Validation errors (400) list each field and its problem in the error string, and also include a details object with the same information grouped by field.

Status codes

CodeMeaningWhat to do
200Request succeeded.Read the response body.
201Resource created.Store the returned id.
400Invalid request body.Fix the fields named in the message and retry.
401Missing, malformed, wrong or revoked API key.Check the Authorization header, or create a new key.
403Your merchant account is not active.Complete KYC or contact support.
404The payment link does not exist or belongs to another merchant.Check the ID.
500Something went wrong on our side.Retry after a short delay, then contact support if it persists.

Handling errors

const res = await fetch(url, options);

if (!res.ok) {
  const { error } = await res.json();
  // 4xx: fix the request. 5xx: retry later.
  throw new Error(`ZOZOPAY ${res.status}: ${error}`);
}

const link = await res.json();

Retries: there are no idempotency keys yet. Retrying a failed POST after a network error could create a second payment link, so check your own records or use a unique receiptId first.