status payments.status payments.gatewayCode payments.gatewayDescription We already have doco on our status and that should be referenced here. But we need to expand on gatewayCode and gatewayDescription for card payments. These will contain the payment card network response codes and descriptions used by Visa and Mastercard: https://developer.visa.com/request_response_codes#action_code https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/response-error-codes/#network-response-codes

These are essentially identical except:

Mastercard also includes a Merchant Advice Code when the network response code is one of: 79, 82 or 83. We have not yet exposed this level of detail. Visa makes use of additional descriptors like N7 code which specially indicates that the CVV is invalid and the R* codes which are used for recurring purchases.

I'd like to list each code and description. We also need to note that we use two special gatewayCodes: 1000: for approved transactions 9999: for declined transactions where we cannot specify the decline reason (for fraud or security reasons)

Blocked cards

We should also include a section on blocked cards. Declined cards are sorted into different categories. Depending on the decline reason, the card PAN (Primary Account Number) can be one of: never retried - these cards will be blocked after the first attempt, usually reserved due to suspected fraud by the card issuer retried but with updated authorisation data - such as expiry or CVV but not more than 15 retries of the PAN in a 30 day rolling period retried later - using the same card details Categories are: Category 1: Issuer Will Never Approve: Codes in this category indicate that the card is invalid, never existed, or blocked. These will be blocked after the first attempt. We're not permitted to unblock these cards, else we face scheme penalties. gatewayCode 03 - Invalid merchant 04 - Pickup card 07 - Pickup card, special conditions 12 - Invalid transaction 15 - No such issuer 41 - Pickup card lost card 43 - Pickup card stolen card 57 - Transaction not permitted to cardholder 62 - Restricted card 78 - No account 93 - Transaction cannot be completed R0 - Stop payment order R1 - Revocation of authorization order R3 - Revocation of all authorization Category 2: Issuer Cannot Approve at this Time: Codes in this category can indicate several reasons that the Issuer cannot authorize the purchase at the time. These will be blocked if attempted 15 or more times in a 30 day rolling period. gatewayCode 19 - Re-enter transaction 51 - Insufficient funds 59 - Suspected fraud 61 - Exceeds withdrawal amount limits 65 - Exceeds withdrawal frequency 75 - Allowable PIN-entry tries exceeded 86 - ATM malfunction 91 - Issuer or switch is inoperative 96 - System malfunction N3 - Cash service not available N4 - Cash request exceeds issuer limit Category 3: Issuer Cannot Approve based on Details Provided: Codes in this category indicate that the Issuer cannot approve based on the details provided, such as an incorrect Card Verification Value 2 (CVV2) or expiration date. These will be blocked if attempted 15 or more times in a 30 day rolling period. gatewayCode 14 - Invalid account number 54 - Expired card 55 - Incorrect PIN 82 - Negative Online CAMCardholder N7 - Decline for CVV2 Failure-Visa Category 4: Generic Response Codes: All other Response Codes, many of which are technical and limited value/meaning to merchants all other gatewayCodes