General Error Model & Codes

Description

VPWS services cover the following endpoints

• /vpws/paymentOptions
• /vpws/paymentOptions/{binNumber}
• /vpws/payment
• /vpws/transaction
• /vpws/payment/cancel
• /vpws/payment/refund

Services respond with HTTP status codes and a standard JSON error model based on the operation result.

Note: The /vpws/transaction service may return the Transaction object directly. In error cases, the standard error model applies.

Standard Response Model

{
  "message": "Description",
  "statusCode": 400,
  "exceptions": null,
  "data": null,
  "oldData": null,
  "errors": [
    {
      "code": "P001",
      "message": "Invalid request parameter"
    }
  ]
}

Field Descriptions

Field	Type	Description
message	string	General info or error message
statusCode	int	HTTP status code
exceptions	object	Application-level error details
data	object	Successful operation data
oldData	object	Previous data before update
errors	array	Multiple error objects

Error Codes

Code	HTTP	Description
P001	400	Invalid parameter
P002	401	Invalid or expired AccessToken
P003	403	Dealer not authorized for this operation
P004	404	Transaction not found
P005	409	Transaction conflict (duplicate request)
P006	422	Transaction validation error
P007	429	Too many requests
P008	500	System error
P009	503	Bank service not responding
P010	504	Timeout
P011	600	Payment failed
P012	601	OTP verification error
P013	602	Cancellation failed
P014	603	Refund failed
P015	604	Partial refund limit exceeded
P016	605	Unsupported operation
P017	606	Transaction already completed
P018	607	BIN undefined
P019	608	POS not found
P020	609	Currency not supported

Error Management Recommendations

• statusCode and errorCode should be checked together.

• Even if 200 is returned, data.isSuccess should be checked.

• Exponential backoff is recommended for 429 errors.

• Retry policies should be applied carefully for bank-related errors (P011–P015).