Error Reference
This page documents all error codes returned by the PayItFast API. Errors are grouped by category to help you quickly identify and handle specific failure scenarios in your integration.
Error Format
All errors are returned as JSON with a code field (machine-readable) and a message field (human-readable description). Always use the code field for programmatic error handling.
Authentication Errors
| Code |
Description |
| CUSTOMER_NOT_FOUND |
Username/password not found in system |
| UNAUTHORIZED_CUSTOMER |
MID header empty or not found |
| Code |
Description |
| INVALID_ARGUMENTS |
Malformed request parameters |
| MISSING_ARGUMENTS |
Required fields absent from the request |
Rate / Currency Errors
| Code |
Description |
| CURRENCY_NOT_FOUND |
Currency not supported |
| QUOTES_LIMIT_ERROR |
Amount outside limits for the trading pair |
| QUOTES_EXPIRED |
Quote no longer valid (exceeded 1-minute validity window) |
User Management Errors
| Code |
Description |
| CONFLICT |
User already exists with the provided email |
| USER_NOT_FOUND |
User does not exist in the system |
| AGE_LIMIT_ERROR |
User age outside acceptable range |
| ADDRESS_RESUBMISSION_REQUIRED |
Address validation failed; resubmission needed |
Order / Transaction Errors
| Code |
Description |
| FILE_REQUIRED |
Invoice documentation needed for the transaction |
| INVALID_PAYMENT_CODE |
Payment code incorrect or invalid |
| INSUFFICIENT_BALANCE |
Account lacks funds for the requested operation |
| RESTRICTED_ACCESS |
User prohibited from transactions |
| INVALID_QR_STRING |
QR code validation failed |
Compliance / KYC Errors
| Code |
Description |
| STANDARD_KYC_REQUIRED |
Level 1 KYC needed (transaction limit exceeded) |
| ENHANCED_KYC_REQUIRED |
Level 2 KYC needed (transaction limit exceeded) |
| BASIC_SCREENING_IN_PROGRESS |
KYC pending approval |
| BASIC_SCREENING_REJECTED |
KYC rejected by compliance screening |
| KYC_EXPIRED |
KYC document expired |
| RESUBMISSION_REQUIRED |
KYC resubmission necessary |
| MAXIMUM_LIMIT_BREACHED |
Transaction cap reached |
| EMAIL_VERIFICATION_FAILED |
Email validation failed |
| EMAIL_UNDER_MANUAL_REVIEW |
Email pending review (24–48 hours) |
| DEVICE_UNDER_MANUAL_REVIEW |
Device/biometric check pending |
| DEVICE_VERIFICATION_FAILED |
Device/biometric verification failed |
| KYT_UNUSUAL_BEHAVIOUR_MANUAL_REVIEW |
Flagged for unusual behavior, under manual review |
| KYT_VELOCITY_RISK_TEMP_BLOCK |
Account disabled for 24 hours due to velocity risk |
| KYT_UNUSUAL_BEHAVIOUR_PERM_BLOCK |
Account permanently disabled due to unusual behavior |
Webhook / Payment Failure Codes
These codes appear in the order.failureCode field of webhook payloads when a payment fails.
| Code |
Description |
| PAYMENT_NOT_COMPLETED |
User cancelled or did not complete payment |
| NAME_NOT_MATCHED |
Sender bank name does not match registered user name |
| BIOMETRICS_CHECK_FAILED |
Device biometric verification failed |
| BIOMETRIC_CHECK_IN_REVIEW |
High-risk device, under compliance review |
| USER_CONSENT_NOT_PROVIDED |
User did not grant gaming consent |
| AMOUNT_MISMATCH |
Payment amount does not match expected amount |
| AUTHENTICATION_FAILED |
User authentication unsuccessful |
| BANK_ACCOUNT_ALREADY_IN_USE |
Account linked to another user |
| BANK_UNDER_MAINTENANCE |
Bank experiencing technical issues |
| DECLINED_BY_BANK |
Bank rejected the transaction |
| INVALID_ACCOUNT_DETAILS |
Account information incorrect |
| TRANSACTION_EXPIRED |
Payment not completed in time |
| TRANSACTION_FAILED |
Transaction processing failure |
| OTHERS |
Unexpected error |
KYC Import Errors
Errors returned when sharing KYC data via Sumsub tokens or third-party providers.
| Code |
Description |
| KYC_IMPORT_FAILED |
Invalid token format |
| INVALID_TOKEN_DETAILS |
Token email or phone does not match |
| TOKEN_DATA_INCOMPLETE |
Missing required KYC information in token |
KYB Errors
Errors specific to business user verification (KYB) workflows.
| Code |
Description |
| BASIC_KYB_NOT_APPROVED |
Basic KYB not yet approved |
| STANDARD_KYB_NOT_APPROVED |
Standard KYB not yet approved |
| STANDARD_KYB_ALREADY_APPROVED |
Standard KYB already completed |
| ADVANCED_KYB_ALREADY_APPROVED |
Advanced KYB already completed |
| KYB_LINK_GENERATION_FAILED |
Link generation failed |
| USER_BLOCKED_OR_REJECTED |
User blocked or rejected |
System Errors
Internal server-side errors. If these persist, contact PayItFast support.
| Code |
Description |
| INTERNAL_SERVER_ERROR |
Internal processing failure |
| SYSTEM_ERROR |
Unhandled system error |
HTTP Status Codes
Standard HTTP status codes used across the API.
| Code |
Description |
200 |
Success — The request completed successfully. |
201 |
Resource Created — A new resource (user, order, etc.) was created. |
400 |
Bad Request — Invalid or missing parameters in the request. |
403 |
Forbidden — Access restricted (KYC pending, account blocked, or limits reached). |
404 |
Not Found — The requested resource does not exist. |
409 |
Conflict — Duplicate resource (e.g., user already exists with this email). |
422 |
Unprocessable Entity — Validation failed (e.g., invalid token details for KYC sharing). |
500 |
Internal Server Error — An unexpected error occurred on the server. |
Webhooks
Understand how failure codes are delivered in webhook payloads.
View guide
KYC & KYB
Learn about the verification process and related error states.
View endpoints
API Overview
Review the full endpoint summary and request/response format.
View overview