Payment statuses and error codes

Use these statuses and error codes to drive your integration logic and handle failures cleanly.

Collection statuses

Status	Meaning
pending	Created, waiting for the customer to pay.
processing	Payment detected, settling.
completed	Funds received and the collection is fulfilled.
failed	Verification failed, or a sandbox payment was marked failed.
cancelled	Cancelled by the merchant before payment.
expired	The 30-minute hosted checkout window has elapsed.

Treat completed as the only success state before you fulfil an order.

Error responses

HTTP	Message	What it means
400	amount is invalid	A required field is missing or has the wrong type.
403	key auth failed	The apikey header is missing, invalid, revoked, or used on the wrong environment.
404	Payment link not found	The reference does not exist in that environment.
501	network error	Upstream or server error. Retry from your backend and log the body.

Handling errors

• Treat the HTTP status as authoritative.
• Log the response body so support can help if needed.
• Retry only 501 responses, with backoff. Do not retry 400 or 404, fix the request instead.

Tip: A 404 often means you created the collection with a test key but are checking it with a live key, or the other way round. Keep environments consistent.

What's next

• See Authenticate your API requests.
• See Set up and verify webhooks.

Still stuck? Email support@boldswitch.ng.