Error Handling

When you encounter an error while calling the PayKKa API，there are two possible cases:

Non-200 HTTP Code is returned

This is a standard PayKKa response. We recommend checking the request based on the returned ret_code and ret_msg.

{
    "ret_code": "010000",
    "ret_msg": "Invalid request"
}

200 HTTP Code is returned，but the response body contains additional business error details

For example，in a transaction request，although the request itself was successful，a business error is returned with the parameters error_code and error_description.
We recommend handling business errors appropriately to ensure a smooth experience for your customers.
Note: The business parameters may vary for different APIs.

{
    "ret_code": "000000",
    "ret_msg": "Success",
    "data": {
        "error_code": "2099",
        "error_description": "Invalid Card",
        "merchant_id": "18356675194960",
        "trans_id": "T4329476032",
        "order_id": "GW206194332333335",
        "status": "FAILURE",
        "amount": 322,
        "currency": "HKD"
    }
}

Response Format

Parameter Name	Description	Type	Required
`ret_code`	Response error code	String	✅
`ret_msg`	Response error message	String	✅
`data`	Response business data，may be empty if the business fails	Object	❌

Error Enums (ret_code)

Code	Description
`000000`	Request successful
`999999`	System exception
`010000`	Invalid request，parameter error
`206001`	Invalid API version
`206002`	Signature not found
`206003`	Signature error
`206004`	Signature expired
`206005`	Merchant does not exist
`206006`	Merchant public key not configured
`206007`	Merchant status disabled
`206008`	Member status disabled
`206011`	The session does not exist
`206017`	PCI compliance insufficient
`206020`	Card information decryption failed
`206021`	Card encryption information expired，please retry payment
`206022`	Card not supported，please use another card
`206024`	the order doesn't exist
`210001`	Payment method not supported
`210002`	shopperReference cannot be empty
`210003`	shipping cannot be empty
`210004`	MIT cannot be empty
`210005`	MIT must be true
`210006`	MIT must be false
`210009`	Recurring payment agreement does not exist
`210010`	Recurring payment agreement not activated
`210011`	returnUrl cannot be empty
`210012`	browser cannot be empty
`210013`	IP address cannot be empty
`210014`	token or card information cannot be empty
`210015`	Phone or email cannot be empty
`210016`	tokenUsage cannot be empty
`210017`	Card information cannot be empty
`210018`	Card expiry year cannot be empty
`210019`	Card expiry month cannot be empty
`210020`	CVV cannot be empty
`210021`	Payment information error
`210022`	Card Token not recognized
`210023`	Card Token not activated
`210024`	Card Token not supported
`210025`	Card not supported，please use another card
`210026`	Invalid bank card
`210027`	Merchant does not exist
`210028`	Merchant disabled
`210029`	Merchant not allowed to transact
`210030`	Merchant not allowed to refund
`210031`	Merchant currency not supported
`210032`	Merchant payment type not supported
`210033`	Merchant payment method not supported
`210037`	Refund currency differs from original transaction
`210038`	Transaction not allowed to refund
`210039`	Transaction completed，duplicate submission not allowed
`210040`	Refund completed，duplicate submission not allowed
`210042`	Channel error
`210043`	Order number and transaction ID cannot both be empty
`210044`	Order does not exist
`210045`	Invalid expiry time
`210047`	Refund amount cannot exceed refundable amount
`210048`	Multiple submissions inconsistent
`210049`	Checkout completed，duplicate submission not allowed
`210050`	Current order status not allowed to modify
`210051`	Invalid order parameters
`210052`	Checkout does not exist
`210054`	Payment order processing，please do not repeat payment
`210055`	No available route
`210056`	Area code cannot be empty when phone is not empty
`210057`	Billing country cannot be empty
`210058`	Transaction not allowed to close
`210059`	First name and last name cannot be empty
`210060`	Address cannot be empty
`210061`	City cannot be empty
`210062`	Transaction not allowed to capture
`210063`	Transaction not allowed to void
`210064`	Capture failed
`210065`	Void failed
`210066`	Capture amount cannot exceed capturable amount
`210067`	Capture currency differs from original transaction
`210068`	tokenAuthentication cannot be empty