err_code. Branch on it, not on message. For the response shape and retry rules, see Error handling.
General Server or Network Issues
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 401 | AUTH_UNAUTHORIZED | Unauthorized |
| 401 | AUTH_MISSING_HEADERS | Missing authentication headers |
| 401 | AUTH_INVALID_SIGNATURE | Invalid signature |
| 404 | NOT_FOUND | Not Found |
| 429 | TOO_MANY_REQUESTS | Too many requests |
| 400 | NET_TIMEOUT | Request timed out |
| 400 | UNKNOWN_ERROR | Unknown Error |
Customer Endpoints
/customer/create
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_INVALID_COUNTRY | Invalid country code |
| 400 | REQ_NON_RESIDENT_UNSUPPORTED | Non-Residents not supported |
| 400 | REQ_INVALID_RESIDENCE_COUNTRY | Invalid residence country code |
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 400 | USR_DUPLICATE_CONTACT | Phone or email linked with another user |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/customer/:customer_id
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | USR_NOT_FOUND | User not found |
| 400 | AUTH_ORG_MISMATCH | User does not belong to organization |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/customer/list
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | INPUT_INVALID_DATE_FORMAT | Invalid date format |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
KYC Endpoints
/kyc/configuration/:customer_id
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | USR_NOT_FOUND | User not found |
| 400 | AUTH_ORG_MISMATCH | User does not belong to organization |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/kyc/add-kyc-data
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 400 | USR_NOT_FOUND | User not found |
| 400 | AUTH_ORG_MISMATCH | User does not belong to organization |
| 400 | KYC_INVALID_AADHAAR_INPUT | For AADHAAR, either provide both document_front_image_url and document_back_image_url, OR provide aadhaar_json inside additional_data |
| 400 | KYC_INVALID_DOC_TYPE | Document type not supported for your country |
| 400 | KYC_IN_USE | KYC already in use |
| 400 | INPUT_MALFORMED_ADDITIONAL_INFO | Malformed additional_info input |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/kyc/update-tax-info
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 400 | USR_NOT_FOUND | User not found |
| 400 | AUTH_ORG_MISMATCH | User does not belong to organization |
| 400 | KYC_IN_USE | KYC already in use |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/kyc/update-document-info
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 400 | USR_NOT_FOUND | User not found |
| 400 | AUTH_ORG_MISMATCH | User does not belong to organization |
| 400 | KYC_IN_USE | KYC already in use |
| 400 | KYC_INVALID_AADHAAR_INPUT | For AADHAAR, either provide both document_front_image_url and document_back_image_url, OR provide aadhaar_json inside additional_data |
| 400 | KYC_INVALID_DOC_TYPE | Document type not supported for your country |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/kyc/update-selfie-info
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | USR_NOT_FOUND | User not found |
| 400 | AUTH_ORG_MISMATCH | User does not belong to organization |
| 400 | INPUT_MALFORMED_ADDITIONAL_INFO | Malformed additional_info input |
| 400 | KYC_UPDATE_LIMIT_EXCEEDED | Kyc update limit is reached |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/kyc/reset-kyc
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | USR_NOT_FOUND | User not found |
| 400 | AUTH_ORG_MISMATCH | User does not belong to organization |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
Bank Endpoints
/bank/create
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | USR_NOT_FOUND | User not found |
| 400 | AUTH_ORG_MISMATCH | User does not belong to organization |
| 400 | USR_UNVERIFIED | User is unverified |
| 400 | BANK_DUPLICATE_ACCOUNT | UPI ID or account number is already in use |
| 400 | BANK_LIMIT_REACHED | 3 UPI ID or account number already added for user |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/bank/:customer_id/:bank_id
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | USR_NOT_FOUND | User not found |
| 400 | AUTH_ORG_MISMATCH | User does not belong to organization |
| 400 | BANK_NOT_FOUND | UPI or bank account not found |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/bank/list/:customer_id
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | USR_NOT_FOUND | User not found |
| 400 | AUTH_ORG_MISMATCH | User does not belong to organization |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
Payout Endpoints
/payout/configuration
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payout/limits/:customer_id
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | USR_UNVERIFIED | User is unverified |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payout/fetch-rate
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payout/quotation
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | PAYOUT_AMOUNT_ZERO_OR_NEGATIVE | Entered amount cannot be zero or negative |
| 400 | PAYOUT_AMOUNT_BELOW_MIN | Entered amount is less than minimum txn amount |
| 400 | PAYOUT_AMOUNT_ABOVE_MAX | Entered amount exceeds maximum txn amount |
| 400 | RISK_AML_FAILED | AML screening failed |
| 400 | RISK_IP_CHECK_FAILED | IP address check failed |
| 400 | INPUT_MALFORMED | Malformed input |
| 400 | USR_UNVERIFIED | User is unverified |
| 400 | RISK_DAILY_LIMIT_EXCEEDED | Daily limit exhausted |
| 400 | RISK_EDD_REQUIRED | EDD required |
| 400 | BANK_ACCOUNT_UNVERIFIED | UPI or bank account is unverified |
| 400 | BANK_NOT_FOUND | UPI or bank account does not belong to user or not found |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
| 503 | SYS_SERVICE_UNAVAILABLE | Service unavailable |
/payout/quotation/:quotation_id
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payout/initiate
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 400 | PAYOUT_DUPLICATE_CLIENT_REF_ID | Client Reference ID already exists |
| 400 | PAYOUT_QUOTATION_NOT_FOUND | Quotation not found |
| 400 | PAYOUT_QUOTATION_LINKED | Quotation linked to another payout |
| 400 | PAYOUT_QUOTATION_EXPIRED | Quotation has expired |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payout/:payout_id
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | PAYOUT_INVALID_PAYOUT_ID | Invalid Payout ID |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payout/history
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payout/edd/save
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | USR_UNVERIFIED | Customer is unverified |
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payout/edd/list
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | INPUT_INVALID_PARAMETER | Invalid user ID |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
Payin Endpoints
/payin/configuration
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payin/limits/:customer_id
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | USR_UNVERIFIED | User is unverified |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payin/fetch-rate
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payin/quotation
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 400 | PAYIN_AMOUNT_ZERO_OR_NEGATIVE | Entered amount cannot be zero or negative |
| 400 | PAYIN_AMOUNT_BELOW_MIN | Entered amount is less than minimum txn amount |
| 400 | PAYIN_AMOUNT_ABOVE_MAX | Entered amount exceeds maximum txn amount |
| 400 | RISK_AML_FAILED | AML screening failed |
| 400 | RISK_IP_CHECK_FAILED | IP address check failed |
| 400 | USR_UNVERIFIED | User is unverified |
| 400 | RISK_DAILY_LIMIT_EXCEEDED | Daily limit exhausted |
| 400 | RISK_EDD_REQUIRED | EDD required |
| 400 | BANK_ACCOUNT_UNVERIFIED | UPI or bank account is unverified |
| 400 | BANK_NOT_FOUND | UPI or bank account does not belong to user or not found |
| 400 | BANK_MODE_MISMATCH | Bank ID should match with selected payment mode |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
| 503 | SYS_SERVICE_UNAVAILABLE | Service unavailable |
/payin/quotation/
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payin/initiate
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 400 | PAYIN_DUPLICATE_CLIENT_REF_ID | Client Reference ID already exists |
| 400 | PAYIN_QUOTATION_NOT_FOUND | Quotation not found |
| 400 | PAYIN_QUOTATION_LINKED | Quotation linked to another payin |
| 400 | PAYIN_QUOTATION_EXPIRED | Quotation has expired |
| 400 | PAYIN_DUPLICATE_UTR | UTR already linked to another payin |
| 400 | PAYIN_INVALID_UTR_FORMAT | Invalid UTR format |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payin/:payin_id
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payin/history
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payin/edd/save
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | USR_UNVERIFIED | Customer is unverified |
| 400 | REQ_FIELD_MISSING | Mandatory field is missing |
| 400 | INPUT_MALFORMED | Malformed input |
| 500 | SYS_INTERNAL_ERROR | Internal server error |
/payin/edd/list
| Status Code | Failure Code | Failure Reason |
|---|---|---|
| 400 | INPUT_INVALID_PARAMETER | Invalid user ID |
| 500 | SYS_INTERNAL_ERROR | Internal server error |