This page provides a comprehensive list of decline and error codes used in the finsino API. These codes help identify specific reasons for transaction declines, errors, or failed validations. Each code is categorized for easier reference.

Upstream Decline Codes

Code	Enum Field	Description
1	`UNEXPECTED_ERROR`	A generic or unknown error occurred.
2	`REJECTED_BY_ISSUER_BANK_ERROR`	The transaction was explicitly rejected by the issuer bank.
3	`THREE_DS_AUTHENTICATION_ERROR`	An error occurred during 3-D Secure authentication.
4	`FORM_TIMEOUT_ERROR`	The payment form timed out and was closed or expired.
5	`INSUFFICIENT_FUNDS_ERROR`	The account or card has insufficient funds to complete the transaction.
6	`LIMITED_BY_ISSUER_BANK_ERROR`	The issuer bank imposed a limit preventing the transaction from proceeding.
7	`ANTI_FRAUD_ERROR`	The transaction was flagged as fraudulent and declined by the anti-fraud system.
8	`DATA_VALIDATION_ERROR`	The provided payment or card data failed validation checks.
9	`PREPAY_TIMEOUT_ERROR`	A timeout occurred during the prepayment process.
10	`THREE_DS_PAGE_ERROR`	The 3-D Secure page encountered an error, halting authentication.
11	`PROCESSOR_DENIED`	The payment processor denied the transaction.
12	`GENERIC_PROCESSING_ERROR`	A generic error occurred during transaction processing.
13	`TECHNICAL_GATEWAY_ERROR`	A technical error occurred at the payment gateway.
14	`DUPLICATED_ORDER_ID_ERROR`	The order ID is already in use or duplicated.
15	`CURRENCY_EXCHANGE_NOT_ALLOWED_ERROR`	The currency exchange operation is not permitted for this transaction.
16	`GATE_NOT_FOUND_ERROR`	The requested payment gateway or channel could not be located.
17	`ORDER_BILLING_ERROR`	There was an error in the order's billing details.
18	`CARD_TIME_LIMIT_ERROR`	The card’s allowable time window for the transaction was exceeded.
19	`THREE_DS_TIMEOUT_ERROR`	The 3-D Secure process timed out.
20	`THREE_DS_CANCEL_ERROR`	The 3-D Secure flow was canceled by the user or the system.
21	`THREE_DS_REDIRECT_TIMEOUT`	The 3-D Secure redirect process timed out.
22	`THREE_DS_REDIRECT_ERROR`	An error occurred during the 3-D Secure redirect.
23	`THREE_DS_ABANDONED`	The 3-D Secure process was abandoned before completion.
24	`CARD_INFORMATION_INVALID`	The card details provided are invalid.
25	`INVALID_CUSTOMER_REDIRECT_URL`	The customer redirect URL is invalid or malformed.
26	`INVALID_CALLBACK_URL`	The provided callback URL is invalid.
27	`CURRENCY_NOT_SUPPORTED`	The selected currency is not supported for this transaction.
28	`FRAUDULENT_TRANSACTION`	The transaction was flagged as fraudulent and rejected.
29	`MERCHANT_NOT_ACTIVE`	The merchant account is inactive or disabled.
30	`INVALID_CARD_HOLDER_DETAILS`	The provided cardholder details are incorrect or missing.
31	`INVALID_ORDER_AMOUNT`	The order amount is invalid or does not meet the required threshold.
61	`INTERNAL_UNEXPECTED_ERROR`	A generic or unknown error occurred in the internal system.
62	`INTERNAL_VALIDATION_ERROR`	The internal system failed a data or parameter validation check.
63	`GATEWAY_UNEXPECTED_ERROR`	A generic or unknown error occurred at the gateway.
64	`GATEWAY_ANTI_FRAUD_ERROR`	The transaction was flagged as fraudulent by the gateway's anti-fraud system.
65	`GATEWAY_VALIDATION_ERROR`	The provided data failed gateway-level validation checks.
66	`GATEWAY_FX_CONVERSION_ERROR`	An error occurred while the gateway processed currency conversion (FX).
67	`GATEWAY_NO_DOWNSTREAM_GATEWAY_ERROR`	The gateway could not forward the request to any downstream gateway.
68	`GATEWAY_DOWNSTREAM_GATEWAY_ERROR`	The downstream gateway returned an error.
69	`GATEWAY_TRANSACTION_LIMIT_ERROR`	The transaction was blocked due to gateway-imposed transaction limits.
70	`GATEWAY_PROCESSING_ERROR`	A generic error occurred while processing the transaction at the gateway.
71	`GATEWAY_AUTHENTICATION_ERROR`	An authentication error occurred at the gateway.
72	`GATEWAY_TECHNICAL_ERROR`	A technical issue occurred at the gateway.
73	`GATEWAY_TIMEOUT_ERROR`	The gateway timed out while processing the transaction.
74	`GATEWAY_INSUFFICIENT_FUNDS`	The gateway detected insufficient funds.
75	`GATEWAY_CARD_DECLINED`	The gateway declined the card transaction.
76	`GATEWAY_ISSUER_DECLINED`	The card issuer declined the transaction.
77	`GATEWAY_DUPLICATE_REQUEST`	A duplicate transaction request was detected by the gateway.
78	`GATEWAY_POLICY_VIOLATION`	The transaction violated a policy set by the gateway.
79	`GATEWAY_CARD_EXPIRED`	The card has expired.
80	`GATEWAY_REDIRECT_ERROR`	An error occurred during a gateway redirect.
81	`GATEWAY_LIMIT_EXCEEDED`	A limit was exceeded at the gateway.
82	`GATEWAY_GENERAL_DECLINE`	The transaction was declined for an unspecified reason by the gateway.

General Decline Codes

Code	Description
`3001`	Downstream service timeout.
`3006`	Merchant has no supported card networks.
`3007`	Configuration not found.
`3010`	No processors available.
`3011`	BIN Risk Check result blocked.
`3012`	Payment transaction not found for refund.
`3013`	Payment transaction has non-success status.

Field Has Invalid State Codes

Code	Description
`4001`	Created date is missing.
`4002`	Email is missing.
`4008`	Transaction entity must be present on outbox message.
`4009`	No pending cascading step found.
`4010`	No root node found.
`4011`	No matching route condition or default node found.
`4012`	No routing configuration found.
`4014`	Customer type condition is invalid.
`4015`	PSP was not assigned.
`4016`	External MID was not assigned.

Country Decline Codes

Code	Description
`100`	Country code is blocked.
`101`	Country origin type not supported.
`102`	Country restriction mode not supported.
`103`	Country code is missing when "open all" is not enabled.
`104`	Country code is not allowed.
`105`	Multiple countries detected.

Domain Decline Codes

Code	Description
`201`	Domain not allowed.
`202`	Domain referer missing or empty.
`203`	Domain referer has an invalid format.
`204`	Domain referer not in allowed list.

Risk Decline Codes

Code	Description
`300`	Overall risk declined.
`301`	Risk AVS declined.
`302`	Risk billing address declined.
`303`	Risk browser declined.
`304`	Risk chargeback declined.
`305`	Risk country declined.
`306`	Risk country mismatch declined.
`307`	Risk CVV declined.
`308`	Risk device declined.
`309`	Risk email address declined.
`310`	Risk email domain declined.
`311`	Risk email local part declined.
`312`	Risk issuer ID number declined.
`313`	Risk order amount declined.
`314`	Risk phone number declined.
`315`	Risk shipping address declined.
`316`	Risk shipping address distance to IP location declined.
`317`	Risk time of day declined.

Activable Decline Codes

Code	Description
`400`	Merchant account is inactive.
`401`	Account is inactive.
`402`	External MID is inactive.
`403`	Entity activation status undefined.
`404`	Could not route transaction to upstream.

Other Decline Codes

3DS Errors

Code	Description
`1001`	Authentication failed.
`1002`	Authentication failed due to timeout.
`1003`	Authentication failed due to invalid response.
`1004`	Authentication aborted by the user.
`1005`	Authentication aborted by the issuer.
`1006`	Authentication abandoned by the user.
`1007`	3DS redirect error.
`1008`	3DS redirect due to timeout.

Failed Sub-Reasons

Code	Description
`1010`	Downstream Timeout.
`1011`	Declined due to invalid CVV.
`1012`	Declined due to invalid expiry date.
`1013`	Declined due to invalid card number.
`1014`	Declined due to invalid amount.
`1015`	Declined due to invalid currency.
`1016`	Declined due to invalid merchant.
`1017`	Declined due to invalid transaction.
`1018`	Declined due to unsupported brand.
`1019`	Declined due to limit exceeded.
`1020`	Declined due to suspected fraud.
`1021`	Declined with "Do Not Honor" response.
`1022`	Declined due to invalid card BIN.
`1023`	Declined due to communication error.
`1024`	Declined due to Credit Card Bin Map Error.

For further inquiries regarding decline codes, contact the finsino support team.

This page provides a comprehensive list of decline and error codes used in the iQono API. These codes help identify specific reasons for transaction declines, errors, or failed validations. Each code is categorized for easier reference.

Upstream Decline Codes

Code	Enum Field	Description
1	`UNEXPECTED_ERROR`	A generic or unknown error occurred.
2	`REJECTED_BY_ISSUER_BANK_ERROR`	The transaction was explicitly rejected by the issuer bank.
3	`THREE_DS_AUTHENTICATION_ERROR`	An error occurred during 3-D Secure authentication.
4	`FORM_TIMEOUT_ERROR`	The payment form timed out and was closed or expired.
5	`INSUFFICIENT_FUNDS_ERROR`	The account or card has insufficient funds to complete the transaction.
6	`LIMITED_BY_ISSUER_BANK_ERROR`	The issuer bank imposed a limit preventing the transaction from proceeding.
7	`ANTI_FRAUD_ERROR`	The transaction was flagged as fraudulent and declined by the anti-fraud system.
8	`DATA_VALIDATION_ERROR`	The provided payment or card data failed validation checks.
9	`PREPAY_TIMEOUT_ERROR`	A timeout occurred during the prepayment process.
10	`THREE_DS_PAGE_ERROR`	The 3-D Secure page encountered an error, halting authentication.
11	`PROCESSOR_DENIED`	The payment processor denied the transaction.
12	`GENERIC_PROCESSING_ERROR`	A generic error occurred during transaction processing.
13	`TECHNICAL_GATEWAY_ERROR`	A technical error occurred at the payment gateway.
14	`DUPLICATED_ORDER_ID_ERROR`	The order ID is already in use or duplicated.
15	`CURRENCY_EXCHANGE_NOT_ALLOWED_ERROR`	The currency exchange operation is not permitted for this transaction.
16	`GATE_NOT_FOUND_ERROR`	The requested payment gateway or channel could not be located.
17	`ORDER_BILLING_ERROR`	There was an error in the order's billing details.
18	`CARD_TIME_LIMIT_ERROR`	The card’s allowable time window for the transaction was exceeded.
19	`THREE_DS_TIMEOUT_ERROR`	The 3-D Secure process timed out.
20	`THREE_DS_CANCEL_ERROR`	The 3-D Secure flow was canceled by the user or the system.
21	`THREE_DS_REDIRECT_TIMEOUT`	The 3-D Secure redirect process timed out.
22	`THREE_DS_REDIRECT_ERROR`	An error occurred during the 3-D Secure redirect.
23	`THREE_DS_ABANDONED`	The 3-D Secure process was abandoned before completion.
24	`CARD_INFORMATION_INVALID`	The card details provided are invalid.
25	`INVALID_CUSTOMER_REDIRECT_URL`	The customer redirect URL is invalid or malformed.
26	`INVALID_CALLBACK_URL`	The provided callback URL is invalid.
27	`CURRENCY_NOT_SUPPORTED`	The selected currency is not supported for this transaction.
28	`FRAUDULENT_TRANSACTION`	The transaction was flagged as fraudulent and rejected.
29	`MERCHANT_NOT_ACTIVE`	The merchant account is inactive or disabled.
30	`INVALID_CARD_HOLDER_DETAILS`	The provided cardholder details are incorrect or missing.
31	`INVALID_ORDER_AMOUNT`	The order amount is invalid or does not meet the required threshold.
61	`INTERNAL_UNEXPECTED_ERROR`	A generic or unknown error occurred in the internal system.
62	`INTERNAL_VALIDATION_ERROR`	The internal system failed a data or parameter validation check.
63	`GATEWAY_UNEXPECTED_ERROR`	A generic or unknown error occurred at the gateway.
64	`GATEWAY_ANTI_FRAUD_ERROR`	The transaction was flagged as fraudulent by the gateway's anti-fraud system.
65	`GATEWAY_VALIDATION_ERROR`	The provided data failed gateway-level validation checks.
66	`GATEWAY_FX_CONVERSION_ERROR`	An error occurred while the gateway processed currency conversion (FX).
67	`GATEWAY_NO_DOWNSTREAM_GATEWAY_ERROR`	The gateway could not forward the request to any downstream gateway.
68	`GATEWAY_DOWNSTREAM_GATEWAY_ERROR`	The downstream gateway returned an error.
69	`GATEWAY_TRANSACTION_LIMIT_ERROR`	The transaction was blocked due to gateway-imposed transaction limits.
70	`GATEWAY_PROCESSING_ERROR`	A generic error occurred while processing the transaction at the gateway.
71	`GATEWAY_AUTHENTICATION_ERROR`	An authentication error occurred at the gateway.
72	`GATEWAY_TECHNICAL_ERROR`	A technical issue occurred at the gateway.
73	`GATEWAY_TIMEOUT_ERROR`	The gateway timed out while processing the transaction.
74	`GATEWAY_INSUFFICIENT_FUNDS`	The gateway detected insufficient funds.
75	`GATEWAY_CARD_DECLINED`	The gateway declined the card transaction.
76	`GATEWAY_ISSUER_DECLINED`	The card issuer declined the transaction.
77	`GATEWAY_DUPLICATE_REQUEST`	A duplicate transaction request was detected by the gateway.
78	`GATEWAY_POLICY_VIOLATION`	The transaction violated a policy set by the gateway.
79	`GATEWAY_CARD_EXPIRED`	The card has expired.
80	`GATEWAY_REDIRECT_ERROR`	An error occurred during a gateway redirect.
81	`GATEWAY_LIMIT_EXCEEDED`	A limit was exceeded at the gateway.
82	`GATEWAY_GENERAL_DECLINE`	The transaction was declined for an unspecified reason by the gateway.

General Decline Codes

Code	Description
`3001`	Downstream service timeout.
`3006`	Merchant has no supported card networks.
`3007`	Configuration not found.
`3010`	No processors available.
`3011`	BIN Risk Check result blocked.
`3012`	Payment transaction not found for refund.
`3013`	Payment transaction has non-success status.

Field Has Invalid State Codes

Code	Description
`4001`	Created date is missing.
`4002`	Email is missing.
`4008`	Transaction entity must be present on outbox message.
`4009`	No pending cascading step found.
`4010`	No root node found.
`4011`	No matching route condition or default node found.
`4012`	No routing configuration found.
`4014`	Customer type condition is invalid.
`4015`	PSP was not assigned.
`4016`	External MID was not assigned.

Country Decline Codes

Code	Description
`100`	Country code is blocked.
`101`	Country origin type not supported.
`102`	Country restriction mode not supported.
`103`	Country code is missing when "open all" is not enabled.
`104`	Country code is not allowed.
`105`	Multiple countries detected.

Domain Decline Codes

Code	Description
`201`	Domain not allowed.
`202`	Domain referer missing or empty.
`203`	Domain referer has an invalid format.
`204`	Domain referer not in allowed list.

Risk Decline Codes

Code	Description
`300`	Overall risk declined.
`301`	Risk AVS declined.
`302`	Risk billing address declined.
`303`	Risk browser declined.
`304`	Risk chargeback declined.
`305`	Risk country declined.
`306`	Risk country mismatch declined.
`307`	Risk CVV declined.
`308`	Risk device declined.
`309`	Risk email address declined.
`310`	Risk email domain declined.
`311`	Risk email local part declined.
`312`	Risk issuer ID number declined.
`313`	Risk order amount declined.
`314`	Risk phone number declined.
`315`	Risk shipping address declined.
`316`	Risk shipping address distance to IP location declined.
`317`	Risk time of day declined.

Activable Decline Codes

Code	Description
`400`	Merchant account is inactive.
`401`	Account is inactive.
`402`	External MID is inactive.
`403`	Entity activation status undefined.
`404`	Could not route transaction to upstream.

Other Decline Codes

3DS Errors

Code	Description
`1001`	Authentication failed.
`1002`	Authentication failed due to timeout.
`1003`	Authentication failed due to invalid response.
`1004`	Authentication aborted by the user.
`1005`	Authentication aborted by the issuer.
`1006`	Authentication abandoned by the user.
`1007`	3DS redirect error.
`1008`	3DS redirect due to timeout.

Failed Sub-Reasons

Code	Description
`1010`	Downstream Timeout.
`1011`	Declined due to invalid CVV.
`1012`	Declined due to invalid expiry date.
`1013`	Declined due to invalid card number.
`1014`	Declined due to invalid amount.
`1015`	Declined due to invalid currency.
`1016`	Declined due to invalid merchant.
`1017`	Declined due to invalid transaction.
`1018`	Declined due to unsupported brand.
`1019`	Declined due to limit exceeded.
`1020`	Declined due to suspected fraud.
`1021`	Declined with "Do Not Honor" response.
`1022`	Declined due to invalid card BIN.
`1023`	Declined due to communication error.
`1024`	Declined due to Credit Card Bin Map Error.

For further inquiries regarding decline codes, contact the iQono support team.

Initiating a Payout Transaction

This documentation provides guidance on initiating a card payout transaction using the iQono API. By sending a POST request, you can transfer funds to a specified card. Once the payout request is processed, a webhook (callback) containing the transaction details will be sent to your server.

API Endpoint

Live

POST https://api.iqono.com/v1/payouts/card

Sandbox

POST https://live.iqono.com/v1/payouts/card

Request Headers:

Content-Type: application/json
Authorization: Bearer <AUTH_TOKEN>
Replace <AUTH_TOKEN> with the access token obtained from the Authorization Service.

Request Body:

The request should be in JSON format and include the following parameters:

Field	Type	Required	Description
`requestId`	String	Yes	Unique identifier for the payout request.
`mid`	String	Yes	Merchant account ID to associate the payout.
`userEmail`	String	Yes	Email address of the recipient.
`amount`	String	Yes	The amount to be transferred.
`card`	Object CardDetails	Yes	Contains card information (see CardDetails Object below).
`billingDetails`	Object (BillingDetails)	No	Contains billing details such as name, address, and contact info (see BillingDetails Object).
`callbackUrl`	String	No	URL to receive the status update of the payout.
`metadata`	Map<String, String>	No	Additional key-value metadata for custom use.

CardDetails Object

Field	Type	Required	Description
`cardHolder`	String	Yes	Name of the cardholder as printed on the card.
`expMonth`	String	Yes	Expiration month of the card (MM format).
`expYear`	String	Yes	Expiration year of the card (YYYY format).
`number`	String	Yes	Card number in string format.
`cvv`	String	No	Card verification code (CVV/CVC).

BillingDetails Object

Field	Type	Required	Description
`firstName`	String	No	First name of the customer.
`lastName`	String	No	Last name of the customer.
`address`	String	No	Billing address line 1.
`postalCode`	String	No	Postal code.
`city`	String	No	Billing city.
`state`	String	No	Billing state or province.
`countryCode`	String	No	Billing country (ISO Alpha-2 format, e.g., US, FR).
`phone`	String	No	Customer’s phone number.
`email`	String	No	Customer’s email address.

Example Request

curl -X POST "https://api.iqono.com/v1/payouts/card" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -d '{
    "requestId": "req12345",
    "mid": "merchant001",
    "userEmail": "[email protected]",
    "amount": "100.00",
    "card": {
      "cardHolder": "John Doe",
      "expMonth": "12",
      "expYear": "2025",
      "number": "4111111111111111",
    },
    "billingDetails":{
      "firstName": "John",
      "lastName": "Doe",
    	"phone": "+1234567890",
    	"email": "[email protected]",
      "countryCode: "AU"
    },
    "callbackUrl": "https://yourserver.com/callback",
    "metadata": {
      "customKey1": "customValue1",
      "customKey2": "customValue2"
    }
  }'

Response Details

The payout endpoint provides structured responses to indicate the success or failure of the request.

Response Body

Field	Type	Required	Description
`transactionId`	String	Yes	Unique identifier for the transaction.
`transactionStatus`	String	Yes	Current status of the transaction (e.g., NEW, PENDING, FAILED, etc.).
`declineCode`	Int	No	Decline code if the transaction fails.

Example Successful Response

HTTP Status: 200 OK
Response Body:

{
  "transactionId": "txn12345",
  "transactionStatus": "PENDING",
  "declineCode": null
}

Example Failed Response

HTTP Status: 200 OK
Response Body:

{
  "transactionId": "txn12345",
  "transactionStatus": "FAILED",
  "declineCode": 101
}

Callback: Merchant Payout DTO

Once the payout is processed, a webhook will be sent to the callbackUrl specified in the request. The callback provides details about the payout and its status.

Payout Callback DTO

The callback object includes the following fields:

Field	Type	Required	Description
`transactionId`	String	Yes	The unique identifier for the payout transaction.
`requestId`	String	Yes	The original request ID provided when initiating the payout.
`mid`	String	Yes	Merchant ID associated with the payout.
`transactionStatus`	Enum	Yes	The status of the payout (e.g., PENDING, SUCCEED, FAILED).
`declineCode`	Integer	No	Code indicating the reason for failure (if applicable).
`cardMask`	String	Yes	Masked card number (e.g., 4111********1111).
`cardHolder`	String	Yes	Name of the cardholder (if available).
`totalAmount`	Double	Yes	The total amount transferred.
`callbackUrl`	String	No	The URL where the callback was sent.
`createdAt`	String	Yes	Timestamp when the payout transaction was created.

Example Callback Object

{
  "transactionId": "txn12345",
  "requestId": "req67890",
  "mid": "merchant001",
  "transactionStatus": "SUCCEED",
  "declineCode": null,
  "cardMask": "411111******1111",
  "cardHolder": "John Doe",
  "totalAmount": 100.0,
  "callbackUrl": "https://yourserver.com/callback",
  "createdAt": "2024-01-01T12:00:00Z"
}