Error Codes

Error Response Format

All errors follow the RFC 7807 Problem Details specification:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Detailed error message",
  "instance": "/Gateway/v1/Payment/initiate-checkout"
}

HTTP Status Codes

Request successful

Created

Resource created successfully

Bad Request

Invalid request parameters or malformed request body

Unauthorized

Missing or invalid authentication credentials

Not Found

Requested resource not found

Unprocessable Content

Request validation failed or business logic error

Common Error Scenarios

Authentication Errors

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing authentication token"
}

Causes:

Missing Authorization header
Invalid API key
Expired token

Validation Errors

{
  "type": "https://tools.ietf.org/html/rfc4918#section-11.2",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Amount must be greater than 10"
}

Causes:

Invalid field values
Missing required fields
Format constraints not met

Not Found Errors

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Transaction not found"
}

Causes:

Invalid transaction reference
Resource doesn’t exist
Unauthorized access to resource

Payment-Specific Errors

Insufficient Balance

{
  "status": 422,
  "detail": "Insufficient balance in wallet"
}

Payment Channel Disabled

Waypay can enable or disable a payment channel for your merchant account, separately for deposits and withdrawals. A new order on a disabled channel is rejected before anything is created or charged:

{
  "type": "https://datatracker.ietf.org/doc/html/rfc4918#section-11.2",
  "title": "Payment channel disabled",
  "status": 422,
  "detail": "Easypaisa withdrawals are currently disabled for your merchant account. Please contact support to enable this channel.",
  "errorCode": "MERCHANT_CHANNEL_DISABLED",
  "message": "Easypaisa withdrawals are currently disabled for your merchant account. Please contact support to enable this channel.",
  "channel": "EASYPAISA",
  "operation": "Withdrawal",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Deposits are matched on the wallet you request (paymentMethod / walletProvider).
Withdrawals are matched on the beneficiary’s wallet (customerRef.bankCode). For example, EASYPAISA is an Easypaisa withdrawal.
Orders accepted before a channel was disabled are not affected. They complete normally and still send webhooks.
Re-sending an order you already submitted, with the same Idempotency-Key, returns that order’s result instead of this error.
Do not retry this error. Contact support to have the channel enabled.

On POST /Payment/deposit, if the channel is disabled while your order is being placed, you can also see this code as walletChargeInfo.errorCode.

Invalid Mobile Number

{
  "status": 400,
  "detail": "Invalid mobile number format"
}

Transaction Already Refunded

{
  "status": 422,
  "detail": "Transaction has already been fully refunded"
}

Best Practices

Always check the status code first to determine the error type
Log the complete error response for debugging
Parse the detail field for user-friendly error messages
Implement retry logic for transient errors (5xx status codes)
Handle validation errors by displaying specific field errors to users

API documentation

Authentication

Account Balance

Hosted Page Checkout

Deposit

Withdrawal

Order Status

Refund Endpoints

Settlement Endpoints

Errors

Error Response Format

HTTP Status Codes

Common Error Scenarios

Authentication Errors

Validation Errors

Not Found Errors

Payment-Specific Errors

Insufficient Balance

Payment Channel Disabled

Invalid Mobile Number

Transaction Already Refunded

Best Practices

​Error Response Format

​HTTP Status Codes

​Common Error Scenarios

​Authentication Errors

​Validation Errors

​Not Found Errors

​Payment-Specific Errors

​Insufficient Balance

​Payment Channel Disabled

​Invalid Mobile Number

​Transaction Already Refunded

​Best Practices

Error Response Format

HTTP Status Codes

Common Error Scenarios

Authentication Errors

Validation Errors

Not Found Errors

Payment-Specific Errors

Insufficient Balance

Payment Channel Disabled

Invalid Mobile Number

Transaction Already Refunded

Best Practices