API Reason Codes
This document showcases the possible API Reason Codes you can expect to receive for various resources:Payments
, Refunds
, Payouts
, Recoveries
, Adjustments
, and Disputes
. If you interface with these endpoints, any Reason Code you come across will be listed below, and will provide context around API information like pending
and failure
API status
.Payment Failure Values
Values you can expect when interfacing with the/payments
endpoint, specifically for the failure case.reason_code | reason_message | detail_code | detail_message | Platform Action |
---|---|---|---|---|
NOT_CAPTURED | Failed to capture the payment | See credit card payment failure details possible values | See credit card payment failure details possible values | Respond according to recommended action associated with the returned failure details |
ECHECK_FRAUD | Failed to capture the payment due to suspected fraud | See ACH payment failure details possible values | See ACH payment failure details possible values | Respond according to recommended action associated with the returned failure details |
BANK_NOT_CONFIRMED | Failed to capture the payment due to incorrect information | See ACH payment failure details possible values | See ACH payment failure details possible values | Respond according to recommended action associated with the returned failure details |
BANK_SYSTEM_ERROR | Failed to capture the payment due to bank system error | See ACH payment failure details possible values | See ACH payment failure details possible values | Respond according to recommended action associated with the returned failure details |
PAYMENT_EXPIRED | Failed to capture the payment as it has expired | request_expired | The payment request has expired. Please refer to Payments documentation for details on when payment request expires. | Verify whether the payment was supposed to go through with the merchant and payer. If the payment was supposed to be captured, re-try the payment and be sure to capture it within the 7 day timeframe. |
REVIEW | Failed to capture the payment. | risk_review | The payment could not be captured as it failed risk review | No action recommended. Let the merchant know that the payer will need to find an alternate method of payment. |
UNKNOWN | Failed to capture the payment due to unknown reasons. | unknown | The payment could not be captured for unknown reasons | Reach out to WePay Support for assistance. |
POS_ERROR | Failed to complete the POS request | See Card Present payment failure detail possible values. | See Card Present payment failure detail possible values. | Follow the guidance specific to the details. |
Example
{
"reason_code": "REVIEW",
"reason_message": "Failed to capture the payment.",
"details": {
"detail_code": "risk_review",
"detail_message": "The payment could not be captured as it failed risk review."
}
}
Credit Card Payment Failure Details
reason_code | message | detail_code | detail_message |
---|---|---|---|
NOT_CAPTURED | Failed to capture the payment | invalid_address | The address could not be verified |
invalid_card_number | The card number is invalid | ||
invalid_card_type | The card type is invalid | ||
card_not_supported | The card type does not support this purchase | ||
incorrect_cid | The CVC number is incorrect | ||
decline_insufficient_funds | The card has insufficient funds for this transaction | ||
decline_card_stolen | The card cannot be used for this transaction (it may have been reported stolen) | ||
decline_card_inactive | The card cannot be used for this transaction (it may have been reported inactive) | ||
decline_credit_limit | The card has reached its balance or credit limit available | ||
decline_general | The card has been declined for unknown reasons | ||
card_expired | The card has expired | ||
card_invalid_data | One or more fields associated with this transaction has invalid data | ||
card_missing_fields | The card data is missing required fields | ||
system_failure | Issuer or host system could not be reached | ||
excessive_authorizations | The card has exceeded its withdrawal limit | ||
account_cannot_transact | The card or the account its connected to cannot transact | ||
bank_failure | The bank declined this transaction for unknown reasons | ||
no_payment_attempted | Payment could not be captured for unknown reasons | ||
failed_permanently | Payment could not be captured for unknown reasons | ||
unexpected | Payment could not be captured for unknown reasons | ||
undefined | Payment could not be captured for unknown reasons | ||
debit_card_not_accepted | Debit card is not accepted for this transaction | ||
exceeded_token_amount_limit | This transaction exceeds the token amount limit | ||
token_currency_mismatch | This transaction does not match the currency specified in the token | ||
processor_timed_out | The processor was unavailable so we could not capture the payment | ||
processor_declined | The payment was declined by processor for unknown reasons |
ACH Payment Failure Details
reason_code | message | detail_code | detail_message | Notes |
---|---|---|---|---|
BANK_NOT_CONFIRMED | Failed to capture the payment due to incorrect information | R01 | Insufficient funds in account | |
R02 | Account is closed | This payment method will be deleted, but the status will be set to unverified . | ||
R03 | No account on file | This payment method will be deleted, but the status will be set to unverified . | \||
R04 | Invalid account number | This payment method will be deleted, but the status will be set to unverified . | ||
R06 | Returned at request of originating bank | |||
R07 | Authorization revoked by customer | This payment method will be deleted. | ||
R08 | Payment stopped | This payment method will be deleted. | ||
R09 | Insufficient collected funds in account being charged | |||
R10 | Customer Advises Originator is Not Known to Receiver and/or Is Not Authorized by Receiver to Debit Receiver's Account. | This payment method will be deleted. | ||
R11 | Advise that the merchant work with the payer to resolve the Advises Entry Not In Accordance with the Terms of the Authorization | |||
R12 | Account sold to another financial institution | |||
R13 | Invalid ACH routing number | This payment method will be deleted, but the status will be set to unverified . | ||
R14 | Representative payee deceased or cannot continue in that capacity | This payment method will be deleted. | ||
R15 | Beneficiary or account holder other than representative payee deceased | This payment method will be deleted. | ||
R16 | Account funds have been frozen | This payment method will be deleted. | ||
R17 | Item returned because of invalid data | This payment method will be deleted, but the status will be set to unverified . | ||
R19 | Amount error | |||
R20 | Account does not allow ACH transactions or limit has been exceeded | This payment method will be deleted, but the status will be set to unverified . | ||
R23 | Credit entry refused by receiver | This payment method will be deleted. | ||
R28 | Routing / Transit number check digit error | This payment method will be deleted, but the status will be set to unverified . | ||
R29 | Corporate customer advises not authorized | This payment method will be deleted. | ||
R30 | RDFI not participant in check truncation program | |||
R31 | Permissible return entry | |||
R32 | Receiving bank non-settlement | |||
R33 | Return of item | |||
R34 | Limited participation originating bank | |||
R35 | Return of improper debit entry | |||
R36 | Return of improper credit entry | |||
R40 | Return of item by government agency | |||
R41 | Invalid Transaction Code | |||
R42 | Routing/transit number check digit error | |||
R43 | Invalid account number | |||
R47 | Duplicate enrollment | |||
R50 | State law affecting RCK acceptance | |||
R70 | Permissible return entry not accepted | |||
R71 | Misrouted dishonored return - incorrect routing/transit # in RDFI id field | |||
R72 | Untimely return - dishonored return was not sent within the established timeframe | |||
R73 | Timely original return - RDFI certifies the original return entry was sent within established timeframe for original returns | |||
R74 | Corrected return - RDFI is correcting a previous return entry that was dishonored because it contained incomplete or incorrect information | |||
R75 | Original return not a duplicate | |||
R76 | No errors found | |||
R80 | Cross-border payment coding error | |||
R81 | Non-participant in cross-border program | |||
R82 | Invalid foreign RDFI identification | |||
R83 | Foreign RDFI unable to settle | |||
R84 | Cross-border entry not processed by originating gateway operator | |||
P01 | Customized reject code for Chase TS reject reason: MOD CHECK ON RDFI-ID FAILED | This payment method will be deleted. | ||
BANK_SYSTEM_ERROR | Failed to capture the payment due to bank system error | 754 | Bank account has been closed | |
763 | Invalid account number | |||
765 | Customer has not authorized bank to accept these transactions | |||
R18 | Improper effective entry date | |||
R21 | Invalid company identification | |||
R22 | Invalid individual ID | |||
R24 | Duplicate entry | |||
R25 | Addenda record error | |||
R26 | Mandatory field error | |||
R27 | Trace number error | |||
R28 | Routing/transit number check digit error | |||
R37 | Source document presented for payment | |||
R38 | Stop payment on source document | |||
R39 | Improper source document | |||
R44 | Invalid individual ID | |||
R45 | Invalid individual or company name | |||
R46 | Invalid payee indicator code | |||
R51 | Item is ineligible, notice not provided, signature not genuine, or original item altered for adjustment entry | |||
R52 | Stop payment on item | |||
R53 | Item and ACH entry presented for payment | |||
R61 | Misrouted return - RDFI has placed incorrect routing/transit # in RDFI id field | |||
R67 | Duplicate return | |||
R68 | Untimely return - the return was not sent within the established timeframe | |||
R69 | Field errors | |||
R94 | Administrative return item was processed and resubmitted as a photocopy | |||
R95 | Administrative return item was processed and resubmitted as a MICR-Split | |||
R97 | Administrative return item was processed and resubmitted with corrected dollar amount | |||
R98 | Indicates a return PAC (pre-authorized check); RDFI provides a text reason and indicated a new account number on the PAC itself | |||
R99 | Indicates a return PAC (pre-authorized check); RDFI provides a text reason on the PAC itself for which there is no equivalent return reason code | |||
ECHECK_FRAUD | Failed to capture the payment due to suspected fraud | R05 | Unauthorized debit to consumer account | |
R10 | Customer advises not authorized or amount incorrect | |||
R14 | Payee is deceased | |||
R15 | Account holder is deceased | |||
R29 | Corporate customer advised not authorized |
Card Present Payment Failure Details
reason_code | message | detail_code | detail_message |
---|---|---|---|
POS_ERROR | Failed to complete the POS request | already_refunded | The original POS transaction has already been refunded. |
amount_exceeded | The requested amount in the transaction is higher than the original POS amount. | ||
not_yet_captured | The original POS transaction has not been captured yet. | ||
already_captured | The original POS transaction has already been captured. | ||
already_cancelled | The original POS transaction has already been cancelled. |
Payment Pending Values
Reason codes for a payment in the pending state. These are only available as response values that WePay will send to your platform.
reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
PENDING_CAPTURE | Payment pending capture | manual_capture | The payment is pending a manual capture |
UNKNOWN | Payment is pending due to unknown reasons | unknown | The payment is pending due to unknown reasons |
PROCESSING | Payment is being processed | processing | The payment currently under processing |
REVIEW | Payment is currently in review | risk_review | The payment is currently pending risk review |
ECHECK_SUBMISSION | Payment processing is pending echeck submission | echeck_submission | The payment is currently pending echeck submission |
BANK_VERIFICATION | Payment is pending bank verification | bank_verification | The payment is currently pending bank verification |
Refunds Failure Values
Values you can expect when interfacing with the/refunds
endpoint, specifically for the failure case.reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
UNKNOWN | Failed to refund the payment due to unknown reasons | unknkown | The payment could not be refunded for unknown reasons |
REVIEW | Failed to refund the payment | risk_review | The payment could not be refunded as it failed risk review |
Refunds Pending Values
Values you can expect when interfacing with the/refunds
endpoint, specifically for the pending case.reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
UNKNOWN | Refund is pending due to unknown reasons | unknown | The refund is pending due to unknown reasons |
REVIEW | Refund is currently in review | risk_review | The refund is currently pending risk review |
PROCESSING | Refund is being processed | processing | The refund is currently under processing |
Payouts Failure Values
Values you can expect when interfacing with the/payouts
endpoint, specifically for the failure case.reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
SUSPECTED_FRAUD | Payout was rejected due to suspected fraud | suspected_payer_fraud | The payout was rejected due to suspected payer fraud |
suspected_merchant_fraud | The payout was rejected due to suspected merchant fraud | ||
account_compromised | The payout was rejected as the account has been compromised | ||
VERIFICATION | Payout was rejected as we were unable to verify the information | unable_to_verify_controlling_owner | The payout was rejected as we were unable to verify the controlling owner of the account |
unable_to_verify_payer | The payout was rejected as we were unable to verify one of the payments in this payout | ||
unable_to_verify_owner_payer | The payout was rejected as we were unable to verify the controlling owner of the account and one of the payments in this payout | ||
OTHER | Payout was rejected for miscellaneous reasons | against_tos | Account violated our Terms of Service |
account_cannot_go_negative | The payout was rejected as it would have caused account to go negative | ||
high_risk_account | The payout was rejected for risk reasons | ||
name_mismatch | The payout was rejected as the name on the account didn't match | ||
admin_kyc_mismatch | The KYC country of the admin does not match the currency of the payout | ||
other | The payout failed due to unknown reasons | ||
UNKNOWN | Payout was rejected due to unknown reasons | unknown | The payout failed due to unknown reasons |
Payouts Pending Values
Values you can expect when interfacing with the/payouts
endpoint, specifically for the pending case.reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
REVIEW | Payout is under review | risk_review | The Payout is currently under risk review |
PROCESSING | Payout is being processed | processing | The Payout is currently under processing |
Recoveries Failure Values
Values you can expect when interfacing with the/recoveries
endpoint, specifically for the failure case.reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
BANK_REJECT | Rejected by the bank | insufficient_funds | The recovery attempt failed due to insufficient funds in the bank account |
UNKNOWN | Failed due to unknown reasons | unknown | The recovery attempt failed due to unknown reasons |
Recoveries Pending Values
Values you can expect when interfacing with the/recoveries
endpoint, specifically for the pending case.reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
PROCESSING | Recovery is being processed | processing | The recovery is currently under processing |
UNKNOWN | Recovery is pending due to unknown reasons | unknown | The recovery is pending due to unknown reasons |
Adjustments Values
Values you can expect when interfacing with the/adjustments
endpoint, specifically for the pending case.reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
BALANCE_TRANSFER | Balance transfer between accounts. | balance_transfer | Balance transfer between two accounts owned by the same partner/merchant. |
CHARGEBACK | Chargeback Adjustment. | other | Chargeback Adjustment (full amount). |
partial_chargeback_reversals | Chargeback Adjustment (partial amount). | ||
chargeback_fee_reimbursements | Reimbursement of Chargeback Fee. | ||
ESCHEATMENT | Adjustment due to abandoned funds. | lien_or_levy | Court order requirement to withhold/collect funds owed. |
escheatment | Abandoned funds escheated to state of account-holder. | ||
REIMBURSEMENTS_AND_CORRECTIONS | Adjustment for reimbursement or corrections. | correction_to_fee_schedules | Correction to Fee Schedule. |
processing_fee_reimbursements | Reimbursement of Processing Fee. | ||
revshare_disbursements | Revenue Share Disbursement. | ||
inadvertent_refunds | Refund erroneously made due to WePay Error. | ||
bank_overdraft_fee | Reimbursement of Bank Overdraft Fee. | ||
negative_account_balance_recovery | WePay Recovery of Negative Account Balance. | ||
negative_account_balance_to_zero | Negative Account Balance Brought to Zero. | ||
system_issues | WePay Bug or System Flaws. | ||
FEES | Adjustment for fees. | billing_statement_fees | Fees associated with a billing statement. |
MISCELLANEOUS | Adjustment due to miscellaneous reasons. | miscellaneous | Other Adjustment. |
Disputes Values
Values you can expect when interfacing with the/disputes
endpoint. We surface the card level error codes we receive. We group card level errors as detail_code
, and apply a higher level grouping under reason_code
. We return these in the response field reason
. Find dispute reason codes according to the card network.Visa
reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
FRAUD | The payer identified the transaction as fraudulent. | 10.1 | EMV Liability Shift Counterfeit Fraud |
10.2 | EMV Liability Shift Non-Counterfeit Fraud | ||
10.3 | Other Fraud-Card Present Enviroment | ||
10.4 | Other Fraud-Card Absent Enviroment | ||
10.5 | Visa Fraud Monitoring Program | ||
RECOGNITION | The payer did not recognize the transaction | 11.1 | Card Recovery Bulletin |
11.2 | Declined Authorization | ||
11.3 | No Authorization | ||
PROCESSING_ERROR | The payment processor reported an error processing this transaction | 12.1 | Late Presentment |
12.2 | Incorrect Transaction Code | ||
12.3 | Incorrect Currency | ||
12.4 | Incorrect Account Number | ||
12.5 | Incorrect Amount | ||
12.6 | Duplicate Processing/ Paid by Other Means | ||
12.6.1 | Duplicate Processing | ||
12.6.2 | Paid by Other Means | ||
12.7 | Invalid Data | ||
13.8 | Original Credit Transaction Not Accepted | ||
SERVICES_NOT_PROVIDED | The payer claims the service was not provided | 13.1 | Merchandise/Services Not Received |
13.2 | Cancelled Recurring | ||
13.6 | Credit Not Processed | ||
13.7 | Canceled Merchandise/Services | ||
13.9 | Non-Receipt of Cash or Load Transaction Value | ||
NOT_AS_DESCRIBED | The payer claims the item was not as described | 13.3 | Not as Described or Defective Merchandise/Services |
13.4 | Counterfeit Merchandise | ||
13.5 | Misrepresentation |
Mastercard
reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
FRAUD | The payer identified the transaction as fraudulent | 4837 | No cardholder authorization |
4840 | Fraudulent processing of transactions | ||
4847 | Requested/required authorization not obtained and fraudulent transaction | ||
4849 | Questionable merchant activity | ||
4862 | Counterfeit transaction magnetic stripe POS fraud | ||
4863 | Cardholder does not recognize-potential fraud | ||
4870 | Chip liability shift | ||
4871 | Chip/PIN liability shift | ||
RECOGNITION | The payer did not recognize the transaction | 6321 | Cardholder does not recognize transaction |
PROCESSING_ERROR | The payment processor reported an error processing this transaction | 4835 | Card not valid or expired |
4807 | Warning bulletin file | ||
4808 | Requested/required authorization not obtained | ||
4812 | Account number not on file | ||
4831 | Transaction amount differs | ||
4834 | Duplicate processing | ||
4842 | Late presentment | ||
4846 | Correct transaction currency code not provided | ||
4850 | Credit posted as a purchase | ||
4860 | Credit not processed | ||
SERVICES_NOT_PROVIDED | The payer claims the service was not provided | 4841 | Cancelled recurring transaction |
4855 | Goods or services not provided | ||
4859 | Addendum, no-show, or ATM dispute | ||
6305 | Cardholder does not agree with billed amount | ||
NOT_AS_DESCRIBED | The payer claims the item was not as described | 4853 | Cardholder dispute-defective/not as described |
4854 | Cardholder dispute-not elsewhere classified (U.S. region only) |
AmEx
reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
FRAUD | The payer identified the transaction as fraudulent | F10 | Missing Imprint |
F14 | Missing Signature | ||
F22 | Expired or Not Yet Valid Card | ||
F29 | Card Not Present | ||
FR2 | Fraud Full Recourse Program | ||
FR4 | Immediate Chargeback Program | ||
FR6 | Partial Immediate Chargeback Program | ||
RECOGNITION | The payer did not recognize the transaction | F25 | Unauthorized charge |
F24 | No Card Member Authorization | ||
PROCESSING_ERROR | The payment processor reported an error processing this transaction | P01 | Unassigned Card Number |
P03 | Credit Processed as Charge | ||
P04 | Charge Processed as Credit | ||
P05 | Incorrect Transaction Amount | ||
P07 | Late Presentment | ||
P08 | Duplicate Charge | ||
P22 | Nonmatching Card Number | ||
P23 | Currency Discrepancy | ||
SERVICES_NOT_PROVIDED | The payer claims the service was not provided | C05 | Goods/Services Cancelled |
C28 | Cancelled Recurring Billing | ||
C08 | Goods/Services Not Received | ||
NOT_AS_DESCRIBED | The payer claims the item was not as described | C04 | Goods/Services Returned or Refused |
C31 | Goods/Services Not as Described | ||
C32 | Goods/Services Damaged or Defective |
Discover, JCB, Diners
reason_code | reason_message | detail_code | detail_message |
---|---|---|---|
FRAUD | The payer identified the transaction as fraudulent | 7010 | Fraud - Card Present Transaction |
7030 | Fraud - Card Not Present Transaction | ||
RECOGNITION | The payer did not recognize the transaction | 4752 | Declined Authorization |
4754 | No Authorization | ||
PROCESSING_ERROR | The payment processor reported an error processing this transaction | 4753 | Invalid Card Number |
4534 | Duplicate Processing | ||
4542 | Late Presentation | ||
4550 | Credit Posted as Card Sale | ||
4586 | Altered Amount Dispute | ||
SERVICES_NOT_PROVIDED | The payer claims the service was not provided | 4755 | Non-receipts of Goods or Services |
4541 | Automatic Payment Dispute | ||
NOT_AS_DESCRIBED | The payer claims the item was not as described | 4553 | Quality of Goods or Services Dispute |
INQUIRY | A chargeback inquiry was opened | unknown | A chargeback inquiry was opened against the transaction |
UNKNOWN | A chargeback was opened with unknown reason | unknown | A chargeback was posted against the transaction for unspecified reason |