Error Codes

This guide documents the most common ePay API error codes, what they mean, and how to respond to them.

Response format

Most API errors follow this structure:

{
  "success": false,
  "errorCode": "SOME_ERROR_CODE",
  "message": "Human readable message"
}

Common error codes

error_code	description
SCA_EXPIRED	3DS / SCA authentication session expired
INSUFFICIENT_FUNDS	Account lacks sufficient funds or credit
REJECTED_BY_SCA	3DS / SCA authentication failed or declined by issuer
DO_NOT_HONOR	Generic decline from issuer—no specific reason
EXPIRED	Operation expired before completion
SCA_CANCELLED_BY_USER	User canceled 3DS / SCA authentication process
REJECTED_BY_MERCHANT	Merchant intentionally declined the payment
CARD_EXPIRED	Card expired—use updated card details
CANCELLED_BY_USER	Customer canceled the payment
CARD_LOST_OR_STOLEN	Card reported lost or stolen—must not retry
ACQUIRER_DECLINED	Acquirer declined authorization
CARD_RESTRICTED	Card restricted—transaction type not allowed
SUSPECTED_FRAUD	Declined due to suspected fraudulent activity
ACQUIRER_DOWN	Acquirer network temporarily unavailable
AMOUNT_LIMIT_EXCEEDED	Amount exceeds card or issuer transaction limit
INVALID_CARD_NUMBER	Card number invalid or not recognized
CARD_BLOCKED	Card blocked—contact issuer
CARD_CLOSED	Card account closed by issuer
DECLINED_BY_ISSUER_OR_SCHEME	Issuer or card network declined transaction
SCA_REQUIRED	3DS / SCA authentication required before authorization
MISSING_ACQUIRER_AGREEMENT	Merchant–acquirer contract not configured
INVALID_CVC	Security code (CVC/CVV) incorrect
ACQUIRER_TIMEOUT	Acquirer did not respond within time limit
AGE_VERIFICATION_NOT_COMPLETED	Required age verification was not completed
ISSUER_DOWN	Issuer system unavailable—try again later
INVALID_AGREEMENT	Invalid or missing merchant setup agreement
SYSTEM_ERROR	Message or processing format error
REJECTED_UNKNOWN	Transaction rejected for unspecified reason
MANUAL_ABORTED	Transaction manually stopped
TIMEOUT_ABORTED	Process aborted due to timeout
PRE_AUTH_FAILED	Pre‑authorization attempt unsuccessful
CARD_PIN_ISSUE	Wrong or unverifiable PIN
DUPLICATE_TRANSACTION	Same transaction already processed
TIMEOUT	Operation timed out before issuer response
ACQUIRER_ERROR	Error or malformed response from acquirer
OPERATION_NOT_SUPPORTED	Operation type not supported by system/card
REJECTED_BY_ISSUER	Transaction declined directly by issuer
UNSUPPORTED_SCHEME	Card scheme not supported for this merchant
SECURITY_VIOLATION	Security or data integrity check failed
INVALID_3DS_AGREEMENT	Invalid or missing 3DS / SCA configuration
RULE_VIOLATION	Blocked by scheme or issuer transaction rules
TECHNICAL_FAILURE	Technical failure during authorization process
INCONSISTENT_TRANSACTION_DATA	Transaction data inconsistent or corrupted
WITHDRAWAL_LIMIT	Withdrawal count or value limit exceeded
VALIDATION_ERROR	Request parameters failed validation checks
TERMINAL_NOT_FOUND	Terminal or POS device not recognized
FAILED_REQUEST	Transaction request could not be processed
PIN_TIMEOUT	PIN entry not completed within time allowed
TRY_AGAIN	Temporary issue—please retry shortly
SERVER_ERROR	Unexpected server or integration error

External status codes in webhooks

In the notification webhook, the transaction object may also contain externalStatusCodes.

This object exposes any known raw or near-raw status codes returned by the underlying payment systems, such as the acquirer, the card network, the terminal, or the SCA flow.

This is useful if you want to handle specific rejection reasons differently than the normalized errorCode returned by ePay.

How it relates to errorCode

• transaction.errorCode is ePay's interpreted and normalized error code.
• transaction.externalStatusCodes contains the more specific underlying status codes when they are known.
• If you only need a stable cross-provider integration, handle errorCode.
• If you need provider-specific behavior, inspect externalStatusCodes as an additional input.

Example

{
  "transaction": {
    "state": "FAILED",
    "errorCode": "DO_NOT_HONOR",
    "externalStatusCodes": {
      "acquirer": "05",
      "network": "05",
      "sca": "N07"
    }
  }
}

In this example, ePay has interpreted the failure as DO_NOT_HONOR, while the webhook still gives you access to the more specific underlying values through externalStatusCodes.

Available fields

• acquirer: The status code returned by the processing acquirer.
• network: The status code returned by the card scheme network.
• terminal: The status code returned by the terminal provider for in-person terminal payments.
• sca: A unified status code representing the outcome of the SCA flow, such as 3DS.

externalStatusCodes is nullable, and individual keys are only present when the value is known to ePay.

How to use this guide

• Check the HTTP status code first.
• Use errorCode for programmatic handling.
• Use message for logging and debugging, not control flow.