Skip to main content

Error Handling

Transaction Failure Status Reason

For failed transactions Embedded Wallet provides additional details for the failure reason in the Transaction update event and in the Transaction object.

The corresponding fields are:

  • Transaction.statusReason - In transactions API.
  • TransactionUpdate.statusReason - In webhooks API.

The possible status reasons might be the same as HTTP Error responses or dedicated ones if the transaction fails asynchronously.

Status Reason CodeDescription
BANK-DEPOSIT-FAILED-INSTRUMENTThe deposit used unacceptable payment instrument.
BANK-DEPOSIT-NAME-MISMATCHThe sender name does not match wallet owner.
DW-UNSUPPORTED-BANKBank is not supported by the payment provider.
DW-BANK-DECLINEDeclined by the processing bank.
DW-DEPOSIT-NOT-CONFIRMEDThe deposit has not been confirmed.
DW-TRANSFER-NOT-ENOUGH-BALANCEThe sending customer has insufficient balance for the transaction.
TRANSFER_AUTH_HOLD_AMOUNT_MISMATCHThe provided authorization hold blocks a lower amount than the requested for the transfer.
TRANSFER_AUTH_HOLD_CURRENCY_MISMATCHThe requested authorization hold blocks an amount in a different currency from the one requested.
DW-TRANSFER-DUPLICATED-MERCHANT-REFDuplicate merchant reference provided.
DW-TRANSFER-INVALID-CURRENCYThe transfer was requested for a currency different that of the sender.
DW-TRANSFER-LIMIT-EXCEEDEDThe sending customer exceeds/has exceeded their transfer limit for the transaction/for a period of time.
DW-TRANSFER-GENERAL-ERRORError during processing the transfer. Transaction was not created.
DW-TRANSFER-NOT-ALLOWEDEither the sender or recipient are restricted for transfers.
RISK_ENGINE_DECLINEFraud suspected.
CUSTOMER_RESTRICTEDCustomer is restricted.
INSUFFICIENT_FUNDSCustomer has insufficient funds for the operation.
OTHERSome other unidentified reason.
DW-DEPOSIT-PROVIDER-ERRORPayment provider error while processing the transaction.
DW-DEPOSIT-BANK-CHANGE-NOT-ALLOWEDCustomer tried to change the payment bank.
DW-DEPOSIT-AUTH-FAILEDCustomer authentication at provider have failed.
DW-DEPOSIT-BANK-UNAVAILABLEPayment bank was not available.
DW-DEPOSIT-ACCOUNT-MISMATCHAccount mismatch at payment provider.
DW-DEPOSIT-ACCOUNT-NOT-FOUNDPayment provider did not found customer account.
DW-DEPOSIT-INVALID-USER-INPUTCustomer provided invalid input.
DW-DEPOSIT-PENDING-CONFIRMATIONCustomer did not confirm the deposit.
DW-DEPOSIT-ATTEMPT-LIMIT-EXCEEDEDCustomer achieved deposit attempt limits.
DW-DEPOSIT-LIMIT-EXCEEDEDDeposit limits reached.
EXTERNAL_PROCESSING_GATEWAY_SYSTEM_ERRORThe external processing gateway has reported a system error.

HTTP Response Errors

This section covers API error responses and their meaning.

When possible additional error details are returned in error response body in ErrorDetails object.

Here is an example of error response 400, containing further details.

{
"error": {
"code": "5068",
"message": "Field error(s)",
"details": [
"Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected."
],
"fieldErrors": [
{
"field": "currencyCode",
"error": "currencyCode must not be null"
}
]
}
}

Common Errors

Common errors are returned by various API endpoints. Errors for specific endpoint are described in dedicated section.

HTTP Status CodeError CodeDescription
5001000An internal error occurred.
5021001An error occurred with the external processing gateway.
5001002An internal error occurred.
5001003An internal error occurred.
5001007An internal error occurred.
5001008An internal error occurred.
4291200The API call has been denied as it has exceeded the permissible call rate limit.
4023047The transaction was declined because the amount exceeds the ceiling limit.
4023048The transaction was declined because the amount is less than the floor limit.
4023054The transaction was declined due to suspected fraud.
4015000Your merchant account authentication failed. Either your store ID/password is invalid or the IP address from which you are sending the transaction has not been authorized.
4005001The submitted currency code is invalid or your account does not support this currency.
4005003You submitted an invalid amount with your request.
4005004You submitted an invalid account type with your request.
4005005You submitted an invalid operation type with your request.
4005010The submitted country code is invalid.
4005016The merchant account you provided cannot be found.
4005017The merchant account you provided is disabled.
4025021Your transaction request has been declined.
4005023The request is not parseable.
4095031The transaction you have submitted has already been processed.
4015040Your merchant account is not configured for the transaction you attempted.
4005042The merchant reference number is missing or invalid or it exceeds the maximum permissible length.
4005068Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected.
4045269The ID(s) specified in the URL do not correspond to the values in the system.
4035270The credentials provided with the request do not have permission to access the requested data.
4065271You requested a response in the 'Accept' header that is in an unsupported format.
4065272The 'Content-Type' you specified in request header was submitted in an unsupported format.
4045273Your client reached our application but we were unable to service your request due to an invalid URL.
4015275The authentication credentials provided with the request have expired.
4015276The authentication credentials provided with the request provided have been disabled.
4015277The authentication credentials provided with the request have been locked due to multiple authentication failures.
4015278The authentication credentials provided with the request were not accepted for an unknown reason.
4015279The authentication credentials are invalid.
4015280The required authentication credentials were not provided.
4055281The request uses an action (for example, GET, POST, or PUT) that is not supported by the resource.
4005283The requested operation can only be executed on a Payment Handle with the status of PAYABLE.
4095284An entity with the specified identifier(s) already exists.
4005501The profile does not have an active credit card.
4005502Either the payment token is invalid or the corresponding profile or bank account is not active.
4007510You submitted invalid bank account information for your banking scheme.

Embedded Wallets Errors

Embedded Wallets specific errors have codes, prefixed by DW prefix.

HTTP Status CodeError CodeMessage
400DW-NO-SUCH-CUSTOMERCustomer was not found.
500DW-INTERNAL-SERVER-ERRORInternal Server Error.
503DW-SERVICE-UNAVAILABLEService Unavailable.
409DW-CUSTOMER-NOT-ALLOWEDOperation not allowed for this customer.
409DW-CORPORATE-CUSTOMER-NOT-ALLOWEDOperation not allowed for corporate customers.
405DW-OPERATION-NOT-ALLOWEDOperation is not allowed in your account. Contact Paysafe for further details.

Customer Management Errors

Authentication Errors

HTTP Status CodeError CodeMessage
400DW-AUTHENTICATION-FAILUREThe authentication process was unsuccessful.
409DW-AUTHENTICATION-NOT-ALLOWEDThe authentication process is not allowed.
412DW-VALIDATION-FAILUREThe validation process was unsuccessful.
412DW-SCREENING-FAILUREThe screening process was unsuccessful.

Wallet Errors

HTTP Status CodeError CodeMessage
400DW-TERMS-AND-CONDITIONS-NOT-ACCEPTEDTerms and conditions are not accepted.
400DW-CUSTOMER-BAD-REQUESTBad request for customer operation.
400DW-CUSTOMER-COUNTRY-NOT-SUPPORTEDCountry is not supported.
400DW-CUSTOMER-CURRENCY-NOT-SUPPORTEDCurrency is not supported for the specified country.
400DW-CUSTOMER-ID-SHOULD-BE-NUMERICCustomerId should be numeric value.
400DW-CUSTOMER-ID-SHOULD-BE-VALIDCustomerId is not supported.
400DW-CUSTOMER-ACCOUNT-ID-SHOULD-BE-VALIDAccountId is not supported.
400DW-CUSTOMER-TRANSACTION-ID-SHOULD-BE-VALIDTransactionId is not supported.
400DW-CUSTOMER-EMAIL-CHANGE-NOT-SUPPORTEDEmail change is not supported.
400DW-CUSTOMER-BIRTH-DATE-CHANGE-NOT-SUPPORTEDBirth date change is not supported.
400DW-SIGNATURE-HEADER-REQUIREDSignature header is required.
400DW-HMAC-SIGNATURE-INVALIDSignature is invalid.
400DW-CUSTOMER-KYC-NOT-COMPLETEDInvalid KYC status.
400DW-CUSTOMER-KYC-ID-VERIFICATION-NOT-COMPLETEDInvalid ID verification status.
400DW-CUSTOMER-KYC-ADDRESS-VERIFICATION-NOT-COMPLETEDInvalid Address verification status.
400DW-CUSTOMER-KYC-FACE-MATCH-NOT-COMPLETEDInvalid Face match status.
400DW-INVALID-MOBILE-NUMBERMobile number is invalid.
400DW-CUSTOMER-EMAIL-AND-MOBILE-MISSINGBoth email and mobile are missing. At least one of them should be provided.
400DW-SCA-VERIFICATION-FAILEDThe transaction was declined because the SCA requirement is not completed.
400DW-MISSING-CUSTOMER-DATABoth customer and legalEntity properties are not provided and exactly one of them is expected.
400DW-AMBIGUOUS-CUSTOMER-TYPEBoth customer and legalEntity properties are provided while only one of them is expected to determine the correct type of the customer.
400DW-IBAN-NOT-ASSIGNABLEIban can not be assigned to the provided account.
400DW-CUSTOMER-FIRSTNAME-INVALIDInvalid first name.
400DW-CUSTOMER-LASTNAME-INVALIDInvalid last name.
400DW-LEGALENTITY-REPRESENTATIVE-FIRSTNAME-INVALIDInvalid representative first name.
400DW-LEGALENTITY-REPRESENTATIVE-MIDDLE_NAME-INVALIDInvalid representative middle name.
400DW-LEGALENTITY-REPRESENTATIVE-LAST-NAME-INVALIDInvalid representative last name.
400DW-LEGALENTITY-DIRECTOR-FIRST-NAME-INVALIDInvalid director first name.
400DW-LEGALENTITY-DIRECTOR-MIDDLE-NAME-INVALIDInvalid director middle name.
400DW-LEGALENTITY-DIRECTOR-LAST-NAME-INVALIDInvalid director last name.
403DW-CUSTOMER-IP-COUNTRY-SANCTIONEDCustomer's IP country falls into the list of sanctioned countries.
403DW-CUSTOMER-IP-COUNTRY-NON-SERVICEDCustomer's IP country falls into the list of non-serviced countries.
409DW-MOBILE-NUMBER-ALREADY-EXISTSMobile number already exists.
409DW-CUSTOMER-EMAIL-ALREADY-EXISTSEmail address already exists.
409DW-CUSTOMER-ALREADY-ONBOARDEDCustomer with the same details has already been onboarded.
409DW-CUSTOMER-CONFLICTThere was a conflict (validation error). Check body for details.
409DW-ACCOUNTS-BALANCES-NOT-EMPTYThere are accounts with non-empty balances.
409DW_CUSTOMER_REGISTRATION_TYPE_MISMATCHTrying to create a customer, which is already onboarded with the same externalId and a different registration type.
422DW-DUPLICATE-ACCOUNT-CURRENCIESMore than one account in same currency is not allowed.
400DW-REGISTRATION-DECLINED-BY-RISK-ENGINERegistration declined by the Risk engine.

Restrictions Errors

HTTP Status CodeError CodeMessage
400DW-WALLET-ID-NOT-FOUNDWallet with the requested ID was not found.
409DW-CUSTOMER-ALREADY-ACTIVATEDCustomer is already activated.
409DW-CUSTOMER-ALREADY-DEACTIVATEDCustomer is already deactivated.

Transfer Errors

HTTP Status CodeError CodeMessage
400DW-TRANSFER-INVALID-CURRENCYThe transfer was requested for a currency different that of the sender.
400DW-TRANSFER-FEE-NOT-SUPPORTEDFees not supported for transfers.
400DW-TRANSFER-SELF-TRANSFERRecipient and sender are identical.
400DW-TRANSFER-EXPIRED-QUOTEExchange rates quote has expired.
400DW-TRANSFER-INVALID-QUOTEExchange rates quote is invalid.
400DW-TRANSFER-FORBIDDEN-REASONTransfer can't be performed with provided reason.
400DW-TRANSFER-INVALID-STATUS-UPDATEInvalid transfer status change.
400DW-TRANSFER-LIMIT-EXCEEDEDThe sending customer exceeds/has exceeded their transfer limit.
400DW-TRANSFER-NOT-ENOUGH-BALANCEThe sending customer has insufficient balance for the transaction.
404DW-TRANSFER-NOT-FOUNDNo transfer matching the provided parameters was found.
400DW-TRANSFER-DUPLICATED-MERCHANT-REFDuplicate merchant reference provided.
400DW-TRANSFER-PREVIEW-EXPIREDTransfer preview expired.
400DW-TRANSFER-SELF-TRANSFERTransfer recipient and sender are identical.
400DW-TRANSFER-NOT-ALLOWEDEither sender or recipient are restricted for transfers.

Authorization Hold Errors

HTTP Status CodeError CodeMessage
404DW-NO-MATCHING-ACCOUNTSCould not find matching accounts for customer.
404DW-AUTHORIZATION-HOLD-NOT-FOUNDCould not find authorization hold.
400DW-INVALID-AUTHORIZATION-HOLD-STATUSInvalid authorization hold status requested.
404DW-CUSTOMER-ACCOUNT-FOR-CURRENCY-NOT-FOUNDCouldn't find an account matching the specified customer id and currency.
404DW-ACCOUNT-NOT-FOUNDCouldn't find account with specified id.
400DW-INSUFFICIENT-BALANCE-FOR-AUTHORIZATION-HOLDCustomer does not have sufficient balance for authorization hold.
400DW-CUSTOMER-IS-RESTRICTED-FOR-TRANSFERSCannot create an authorization hold for customer that cannot transfer money.

Deposit Errors

HTTP Status CodeError CodeMessage
400DW-INVALID-OR-EXPIRED-PAYMENT-INSTRUMENTThe payment instrument is either invalid or expired.
409DW-PAYMENT-INSTRUMENT-ALREADY-EXISTSThe payment instrument already exists.
400DW-BANK-ACCOUNT-NOT-VERIFIEDThe bank account is not verified.
400DW-PAYMENT-METHOD-NOT-AVAILABLEThis payment method is not available.
400DW-PAYMENT-INSTRUMENT-NOT-FOUNDThis payment instrument is not found.
500DW-SLIP-NOT-CREATEDThere was an error while creating the slip.
403DW-PERMISSION-TO-DEPOSITYou do not have permission to deposit.
400DW-PAYMENT-INSTRUMENT-NOT-CREATEDWe are unable to create the payment instrument.
400DW-INVALID-PAYMENT-OPTIONThe payment option provided is invalid.
400DW-SLIP-NOT-FOUNDThe deposit slip was not found.
400DW-DUPLICATE-MERCHANT-REF-NUMDuplicate merchant reference.
500DW-DEPOSIT-NOT-FINALIZEDThere was an error while finalizing the deposit.
400DW-INVALID-ACCOUNT-CURRENCYThe provided currency is not valid.
404DW-CUSTOMER-DELETED-OR-HAS-NO-ACTIVE-EWALLET-ACCOUNTCustomer is deleted or has no active e-wallet account.
400DW-INVALID-TRANSACTION-STATUSThe transaction status is invalid.
500DW-DEPOSIT-RESPONSE-NOT-CREATEDError while creating deposit response.
404DW-CUSTOMER-BRAND-MISMATCHNo such customer in provided brand.
400DW-NEGATIVE-FEEInvalid fee value. Negative fee is not accepted.
400DW-INVALID-FEE-RANGEInvalid fee value. Fee must be less or equal to transaction amount.
400DW-PAYMENT-INSTRUMENT-INVALID-TYPEThe provided instrument type is invalid.
400DW-INSTRUMENT-ID-SHOULD-BE-NUMERICInstrumentId should be numeric value.
400DW-INSTRUMENT-BALANCE-NOT-ENOUGHThe payment instrument has insufficient balance for the transaction.
400DW-DEPOSIT-EXPIREDThe deposit request has expired.
404DW-ENTITY-NOT-FOUNDEntity not found.
409DW-MERCHANT-FEE-FX-NOT-ALLOWEDMerchant fee currency conversion not allowed.
400DW-INVALID-DEPOSIT-STATUSThe deposit status is invalid.
500DW-MERCHANT-FEE-ROUTE-NOT-CONFIGUREDNo merchant fees transaction route configuration found.
500DW-DEPOSIT-PAYMENT-ROUTE-NOT-CONFIGUREDNo deposit payment provider transaction route configuration found.
400DW-EXCEEDED-MAX-NUM-OF-CARDSThe customer has already reached the maximum number of added or removed credit cards.
400DW-DUPLICATE-CARDThis card is registered to another account. Contact us for assistance.

Withdrawal Errors

HTTP Status CodeError CodeMessage
400DW-INVALID-SLIP-PROVIDEDProvided slip does not belong to the customer.
403DW-PERMISSION-TO-WITHDRAWYou do not have permission to withdraw.
400DW-BANK-VALIDATION-FAILEDBank validation failed.
400DW-BANK-DECLINEDeclined by the processing bank.
400DW-BANK-PROCESSING-FAILEDThe system is unable to send this request to the processing bank.
400DW-INVALID-WITHDRAW-ACCOUNTWithdrawal from this account is not supported.
400DW-UPDATE-INVALID-STATUSInvalid status in update request.
400DW-WITHDRAWAL-EXPIREDWithdrawal expired.
400DW-INVALID-TRANSACTION-STATUSThe transaction status is invalid.

Instrument errors

HTTP Status CodeError CodeMessage
400DW-INVALID-INSTRUMENT-TYPE-FOR-VERIFICATIONThe provided instrument type is not supported for instrument verification.
400DW-BANK-ACCOUNT-LIMIT-EXCEEDEDCustomer has reached the limit number of verified bank accounts and open payment instrument verification sessions.

SCA Authentication Errors

HTTP Status CodeError CodeMessage
404DW-SCA-EVENT-NOT-FOUNDSCA authentication event was not found.
429DW-SCA-ATTEMPTS-EXCEEDEDSCA authentication attempts exceeded.

Prepaid Cards

Create Card

HTTP STATUS CODEERROR CODEMESSAGE
400DW-PREPAID-CARDS-NOT-SUPPORTED-CURRENCYProvided currency is not supported by your program.
400DW-PREPAID-CARDS-PROGRAM-NOT-SUPPORTEDProgram is not supported.
400DW-PREPAID-CARDS-TERMS-NOT-ACCEPTEDPlease ensure that both the Terms and Conditions and eDisclosure have been accepted.
400DW-PREPAID-CARDS-MAX-ALLOWED-CARD-TYPE-REACHEDThe current limit for creating this type of card has been reached.
400DW-PREPAID-CARDS-DELIVERY-COUNTRY-NOT-SUPPORTEDThe provided country in the delivery address is not supported.
400DW-PREPAID-CARDS-RESTRICTED-CUSTOMERCustomer account has restrictions.
400DW-PREPAID-CARDS-ACCOUNT-VS-DELIVERY-ADDRESS-STATE-MISMATCHAccount address state and delivery address state must be the same.
400DW-PREPAID-CARDS-NOT-SUPPORTED-CURRENCYProvided currency is not supported by your program.

Activate Card

HTTP STATUS CODEERROR CODEMESSAGE
400DW-PREPAID-CARDS-ARGUMENT-MISMATCHThe information provided is inconsistent. Please verify the fields for accuracy.

Get Card Details

HTTP STATUS CODEERROR CODEMESSAGE
400DW-PREPAID-CARDS-ARGUMENT-MISMATCHThe provided information is inconsistent. Please verify the fields for accuracy.

Update Card Status

HTTP STATUS CODEERROR CODEMESSAGE
400DW-PREPAID-CARDS-STATUS-NOT-ALLOWEDCard status is not allowed for the current card type.
400DW-PREPAID-CARDS-STATUS-ALREADY-APPLIEDCurrent card status is the same as the request.
400DW-PREPAID-CARDS-STATUS-IRREVERSIBLECurrent card status is irreversible.

Webhook errors

HTTP Status CodeError CodeMessage
400DW-NOTIFICATION-RESEND-TASK-BAD-REQUESTBad request for notification resend task operation.
400DW-NOTIFICATION-RESEND-TASK-MISSING-REQUIRED-PARAMETERSThe request for notification resend request is missing required parameters.
400DW-NOTIFICATION-RESEND-TASK-INVALID-REQUEST-TIMEFRAMEThe defined timeframe for notification resend request is invalid. It is too long or in the future.
400DW-NOTIFICATION-RESEND-TASK-TOO-MANY-FILTERS-APPLIEDThere are too many filters specified. Only one should be applied.

Transfer errors

Error CodeMessage
TRANSFER_NOT_ENOUGH_BALANCEThe sending customer has insufficient balance for the transaction.
TRANSFER_AUTH_HOLD_AMOUNT_MISMATCHThe provided authorization hold blocks a lower amount than the requested for the transfer.
TRANSFER_AUTH_HOLD_NOT_FOUNDThe requested authorization hold was not found.
TRANSFER_AUTH_HOLD_STATUS_MISMATCHThe requested authorization hold has either been released or used.
TRANSFER_AUTH_HOLD_CURRENCY_MISMATCHThe requested authorization hold blocks an amount in a different currency from the one requested.
DW-TRANSFER-NOT-ALLOWEDEither sender or recipient are restricted for transfers.
DW-TRANSFER-LIMIT-EXCEEDEDThe sending customer exceeds/has exceeded their transfer limit.
DW_NO_SUCH_CUSTOMEREither the sender or recipient was not found.
DW-TRANSFER-INVALID-CURRENCYThe transfer was requested for a currency different that of the sender.
DW-TRANSFER-GENERAL-ERRORError during processing the transfer. Transaction was not created.
DW-TRANSFER-DUPLICATE-MERCHANT-REFDuplicate merchant reference provided.
BANK-DECLINEDeclined by the processing bank. Please check the bank account details of the request.
BANK-TECHNICAL-FAILUREUnable to send the transfer to the processing bank at this moment. Please submit another withdrawal request.

Refund errors

HTTP Status CodeError CodeMessage
409DW-REFUND-NOT-ALLOWEDTransaction is non refundable.
409DW-REFUND-STATUS-NOT-ALLOWEDDeposit transaction is in non refundable status.
409DW-REFUND-INVALID-AMOUNTInvalid refund amount. Refund amount must be lower or equal to deposit amount
409DW-REFUND-INVALID-CURRENCYInvalid refund amount. Refund must match the deposit currency.
409DW-REFUND-INVALID-TRANSACTION-REFERENCERefund can only be made on deposit transactions.
409DW-REFUND-NOT-EXISTSMissing refund transaction.
409DW-REFUND-CUSTOMER-MISMATCHThe customer of the refund must match the customer of the deposit transaction.