Error mapping

Introduction

This document provides a comprehensive reference for all error codes returned by the Precium S2S API. Understanding these codes enables proper error handling, appropriate customer messaging, and informed decisions about transaction retries.

‍

Error Response Structure

When a transaction fails, the API returns an error object with the following structure:

‍

JSON

{
 "error": {
   "code": "insufficient_funds",
   "description": "Insufficient funds",
   "type": "Insufficient funds",
   "friendly_header": "Insufficient funds",
   "friendly_message": "The transaction failed due to insufficient funds. Fund your account and try again later."
 }
}


‍

Error Categories

Precium errors are categorised by type to help you implement appropriate handling logic:

‍

‍

MIT Retry Classification

For Merchant-Initiated Transactions (MIT), errors are classified as Soft or Hard declines:

‍

‍

Error Code Quick Reference

Priority Levels

‍

Complete Error Code Catalogue

Authentication Failures

3ds_authentication_failed

‍

Possible Causes:

• Incorrect information entered during the 3DS challenge (OTP, password, biometric)
• The issuer's authentication system was temporarily unavailable
• Fraud prevention systems flagged the transaction as suspicious

‍

Merchant Action:

• Allow the customer to retry the payment and authentication process
• Provide clear instructions for completing 3DS authentication
• Suggest using another card if available
• Offer an alternative payment method

‍

Customer Message: "There was a problem with the authentication process. Try again - with another card if possible. If this issue persists, contact your bank for help, or use another payment method."

‍

timeout_3ds_enrollment_check

‍

Possible Causes:

• The enrollment check was not completed within the timeout period
• Network issues between the provider and the 3DS provider

‍

Merchant Action:

• Allow the customer to retry payment and authentication
• Monitor for patterns with specific issuers (BINs) or card types
• Contact Precium support if the issue persists

‍

Customer Message: "There was a problem with the authentication process. Try again - with another card if possible."

‍

timeout

‍

Customer Message: "There was a problem with the authentication process. Try again - with another card if possible."

‍

Charge Declines

do_not_honour

‍

Customer Message: "The transaction was declined by your bank for an unspecified reason. Try again later - with another card if possible. If this issue persists, contact your bank."

‍

insufficient_funds

‍

Customer Message: "The transaction failed due to insufficient funds. Fund your account and try again later, with another card if possible."

‍

authorization_failed

‍

Customer Message: "The transaction failed unexpectedly. Try again later - with another card if possible."

‍

exceeded_account_limit

‍

Customer Message: "The transaction was declined by your bank due to your account limit being exceeded."

‍

exceeds_frequency_limit

‍

Customer Message: "The transaction was declined by your bank due to your account frequency limit being exceeded."

‍

exceeds_withdrawal_limit

‍

Customer Message: "The transaction was declined by your bank due to your account withdrawal limit being exceeded."

‍

antifraud_general

‍

Possible Causes:

• Incomplete or inaccurate client object data
• Different identifiers used with the same card details
• Access from a restricted country
• Velocity or value thresholds exceeded
• 3DS or CVV checks bypassed

‍

Customer Message: "The transaction was blocked due to suspected fraud. Try again later, with another card if possible. If this issue persists, use another payment method or contact us for help."

‍

soft_decline_contact_support

‍

Customer Message: "The transaction was blocked due to suspected fraud. Try again later - with another card if possible."

‍

transaction_not_permitted_to_cardholder

‍

Customer Message: "The transaction failed due to the card not supporting this transaction type. Try again with another card, or contact your bank for help."

‍

transaction_not_supported_or_not_valid_for_card

‍

Customer Message: "The transaction failed due to the card not supporting this transaction type. Try again with another card."

‍

Fraud Flags

blacklisted_tx

‍

Customer Message: "The transaction was blocked due to suspected fraud. Try again later, with another card if possible."

‍

blacklisted_tx_issuing_country

‍

Customer Message: "The transaction was blocked due to suspected fraud. Try again with another card if possible."

‍

blacklisted_tx_risk_score

‍

Customer Message: "The transaction was blocked due to suspected fraud. Try again with another card if possible."

‍

suspected_fraud

‍

Customer Message: "The transaction was blocked due to suspected fraud. Try again later - with another card if possible."

‍

Invalid Token Errors

expired_card

‍

Customer Message: "The transaction failed due to the card having expired. Try again with another card, or contact your bank for help."

‍

lost_card

‍

Customer Message: "The transaction failed due to the card being reported as lost. Try again with another card."

‍

stolen_card

‍

Customer Message: "The transaction failed due to the card being reported as stolen. Try again with another card."

‍

restricted_card

‍

Customer Message: "The transaction failed due to the card being restricted. Try again with another card."

‍

recurring_token_expired

‍

Customer Message: "The transaction failed due to the card you saved having expired. Try again with another card."

‍

Configuration Errors

acquirer_configuration_error

‍

Customer Message: "There was a problem processing payment due to a technical issue. Try again later."

‍

no_matching_terminal

‍

Customer Message: "There was a problem processing payment due to a technical issue. Try again later."

‍

Network Errors

acquirer_connection_error

‍

Customer Message: "There was a problem processing payment due to a technical issue. Try again later."

‍

issuer_not_available

‍

Customer Message: "There was a problem processing payment due to a technical issue. Try again later."

‍

timeout_acquirer_status_check

‍

Customer Message: "There was a problem processing payment due to a technical issue. Please try again later."

‍

Provider Errors

acquirer_error_cs

‍

Customer Message: "There was a problem processing payment due to a technical issue. Try again later."

‍

acquirer_internal_error

‍

Customer Message: "There was a problem processing payment due to a technical issue. Try again later."

‍

acquirer_routing_error

‍

Customer Message: "There was a problem processing payment due to a technical issue. Please try again later."

‍

Validation Errors

invalid_amount

‍

Customer Message: "There was a problem processing payment due to incomplete or invalid data. Check input data and try again."

‍

invalid_card_data / invalid_card_number / invalid_expires

‍

Note: Expiry must be in MM/YY format.

‍

Customer Message: "There was a problem processing payment due to incomplete or invalid data."

‍

Cardholder Name / Card Number / CVC / Expiry Validation Errors

‍

These include: validation_card_number_invalid, validation_card_number_not_provided, validation_card_number_too_long, validation_cardholder_name_invalid, validation_cardholder_name_not_provided, validation_cvc_invalid, validation_cvc_not_provided, validation_expires_invalid, etc.

• Implement client-side Luhn check validation for card numbers
• Ensure card numbers contain only digits
• CVC should be 3 digits (4 for Amex)
• Use MM/YY format for expiry dates

‍

Invalid Request Errors

s2s_not_supported

‍

Customer Message: "There was a problem processing payment due to a technical issue. Use another payment method."

‍

security_violation

‍

Customer Message: "The transaction was blocked due to suspected fraud. Try again later - with another card if possible."

‍

unknown_payment_method / transaction_not_permitted_on_terminal

‍

Pre-Authorization and Capture Errors

capture_amount_exceeds_authorization

‍

authorization_expired

‍

Customer Message: "The payment authorization has expired. Please complete a new payment."

‍

void_not_permitted / already_captured / already_voided / partial_capture_not_supported

‍

These errors relate to invalid capture, void, or refund operations. Check transaction status before attempting these operations.

‍

Refund and Void Errors

refund_amount_exceeds_original / refund_void_not_permitted / transaction_not_refundable

‍

Track total refunded amounts and verify transaction status before attempting refunds or voids.

‍

Zero Authorization Errors

zero_auth_not_permitted

‍

Contact Precium to enable zero authorization.

‍

External 3DS/MPI Errors

invalid_external_3ds_data

‍

Required Fields:

• is_external_3DS: true
• authentication_transaction_id
• cavv
• eci_raw
• xid (for 3DS1) or ds_trans_id (for 3DS2)

‍

external_3ds_not_enabled

‍

Contact Precium to enable external 3DS and ensure you're using a Non-3DS brand.

‍

Webhook Errors

webhook_signature_invalid / webhook_timestamp_expired / webhook_endpoint_unreachable / webhook_timeout

‍

Verify webhook secret, check server clock sync, confirm endpoint is accessible, and ensure responses return within 5 seconds using async processing.

‍

Network Token Errors

invalid_network_token / cryptogram_expired

‍

Request fresh tokens and cryptograms from MDES/VTS. Submit transactions promptly after cryptogram generation.

‍

Other Errors

general_transaction_error / payment_rejected_other_reason / exceeded_acquirer_refund_amount

‍

Contact Precium support for investigation.

‍

MIT Retry Decision Tree

flowchart TD
    A[MIT Transaction Failed] --> B{Check Error Code}
    B --> C{MIT Retry Classification}
    C -->|Hard| D[Do Not Retry]
    C -->|Soft| E{Retry Count?}
    C -->|Not Specified| F[Evaluate Manually]
    D --> G[Request New Payment Method]
    E -->|< 4| H[Schedule Retry]
    E -->|>= 4| I[Exhaust Retries]
    H --> J{Retry #}
    J -->|1| K[Wait 24h]
    J -->|2| L[Wait 48h]
    J -->|3| M[Wait 72h]
    J -->|4| N[Wait 96h]
    K --> O[Retry Transaction]
    L --> O
    M --> O
    N --> O
    I --> G
    F --> P{Error Category}
    P -->|Network/Provider| H
    P -->|Validation/Config| Q[Fix and Retry Immediately]
    P -->|Fraud/Card Invalid| D

‍

Error Handling Best Practices

1. Implement Proper Error Categorisation

PYTHON

HARD_DECLINE_CODES = [
   'expired_card', 'lost_card', 'stolen_card', 'restricted_card',
   'recurring_token_expired', 'antifraud_general', 'blacklisted_tx',
   'suspected_fraud', 'transaction_not_permitted_to_cardholder'
]

SOFT_DECLINE_CODES = [
   'do_not_honour', 'insufficient_funds', 'authorization_failed',
   'exceeded_account_limit', 'exceeds_frequency_limit',
   'general_transaction_error', 'acquirer_connection_error',
   'issuer_not_available'
]


‍

2. Display Customer-Friendly Messages

‍

Never expose raw error codes to customers. Use the friendly_header and friendly_message fields from the error response.

‍

3. Log Comprehensively

‍

For troubleshooting, log: timestamp, purchase ID, error code, full error response, and request details (excluding sensitive card data).

‍

4. Set Up Alerts

‍

Configure alerts for URGENT priority errors (immediate), HIGH priority errors (within 4 hours), error rate thresholds, and unexpected error codes.

‍

Support Contact

For unresolved errors or investigation requests:

• Email: support@precium.com
• Priority Issues: Reference the error code and purchase ID
• Include: Timestamp, purchase_id, error response, and steps to reproduce