Errors

Payroo uses standard HTTP status codes and structured error responses.

Error Response Shape

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "amount is required.",
    "type": "validation_error",
    "request_id": "req_01HXYZ"
  }
}

Error Codes

Code	HTTP Status	Description
INVALID_REQUEST	400	Missing or invalid request parameters.
UNAUTHORIZED	401	Missing or invalid API key.
FORBIDDEN	403	API key lacks the required scope.
NOT_FOUND	404	The requested resource does not exist.
IDEMPOTENCY_CONFLICT	409	Same Idempotency-Key used with a different request body.
INVALID_STATE_TRANSITION	422	Transaction cannot be moved to the requested status.
RATE_LIMITED	429	Too many requests. Retry after the indicated period.
PROVIDER_ERROR	502	The upstream payment provider returned an error.
INTERNAL_ERROR	500	An unexpected internal error occurred.

Webhook Events

Event	Description
payment.succeeded	A QR Ph or eWallet payment was completed.
payment.failed	A payment failed or expired.
payout.succeeded	A payout was successfully disbursed.
payout.failed	A payout failed or was rejected.
payout.reversed	A payout was reversed.
eload.purchase.succeeded	An e-load purchase was completed.
eload.purchase.failed	An e-load purchase failed.
bill.inquiry.succeeded	A bill inquiry returned a result.
bill.payment.succeeded	A bill payment was completed.
bill.payment.failed	A bill payment failed.