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.
| Statut Reason Code | Description |
|---|---|
| BANK-DEPOSIT-FAILED-INSTRUMENT | The deposit used unacceptable payment instrument. |
| BANK-DEPOSIT-NAME-MISMATCH | The sender name does not match wallet owner. |
| DW-UNSUPPORTED-BANK | Bank is not supported by the payment provider. |
| DW-BANK-DECLINE | Declined by the processing bank. |
| DW-DEPOSIT-NOT-CONFIRMED | The deposit has not been confirmed. |
| DW-TRANSFER-NOT-ENOUGH-BALANCE | The sending customer has insufficient balance for the transaction. |
| TRANSFER_AUTH_HOLD_AMOUNT_MISMATCH | The provided authorization hold blocks a lower amount than the requested for the transfer |
| TRANSFER_AUTH_HOLD_CURRENCY_MISMATCH | The requested authorization hold blocks an amount in a different currency from the one requested |
| DW-TRANSFER-DUPLICATED-MERCHANT-REF | Duplicate merchant reference provided. |
| DW-TRANSFER-INVALID-CURRENCY | The transfer was requested for a currency different that of the sender. |
| DW-TRANSFER-LIMIT-EXCEEDED | The sending customer exceeds/has exceeded their transfer limit for the transaction/for a period of time |
| DW-TRANSFER-GENERAL-ERROR | Error during processing the transfer. Transaction was not created. |
| DW-TRANSFER-NOT-ALLOWED | Either the sender or recipient are restricted for transfers |
| RISK_ENGINE_DECLINE | Fraud suspected |
| CUSTOMER_RESTRICTED | Customer is restricted |
| INSUFFICIENT_FUNDS | Customer has insufficient funds for the operation |
| OTHER | Some other unidentified reason. |
| DW-DEPOSIT-PROVIDER-ERROR | Payment provider error while processing the transaction |
| DW-DEPOSIT-BANK-CHANGE-NOT-ALLOWED | Customer tried to change the payment bank |
| DW-DEPOSIT-AUTH-FAILED | Customer authentication at provider have failed |
| DW-DEPOSIT-BANK-UNAVAILABLE | Payment bank was not available |
| DW-DEPOSIT-ACCOUNT-MISMATCH | Account mismatch at payment provider |
| DW-DEPOSIT-ACCOUNT-NOT-FOUND | Payment provider did not found customer account |
| DW-DEPOSIT-INVALID-USER-INPUT | Customer provided invalid input |
| DW-DEPOSIT-PENDING-CONFIRMATION | Customer did not confirm the deposit |
| DW-DEPOSIT-ATTEMPT-LIMIT-EXCEEDED | Customer achieved deposit attempt limits |
| DW-DEPOSIT-LIMIT-EXCEEDED | Deposit limits reached |
| EXTERNAL_PROCESSING_GATEWAY_SYSTEM_ERROR | The 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 and 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 descirbed in dedicated section.
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 500 | 1000 | An internal error occurred. |
| 502 | 1001 | An error occurred with the external processing gateway. |
| 500 | 1002 | An internal error occurred. |
| 500 | 1003 | An internal error occurred. |
| 500 | 1007 | An internal error occurred. |
| 500 | 1008 | An internal error occurred. |
| 429 | 1200 | The API call has been denied as it has exceeded the permissible call rate limit. |
| 402 | 3047 | The transaction was declined because the amount exceeds the ceiling limit. |
| 402 | 3048 | The transaction was declined because the amount is less than the floor limit. |
| 402 | 3054 | The transaction was declined due to suspected fraud. |
| 401 | 5000 | Your 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. |
| 400 | 5001 | The submitted currency code is invalid or your account does not support this currency. |
| 400 | 5003 | You submitted an invalid amount with your request. |
| 400 | 5004 | You submitted an invalid account type with your request. |
| 400 | 5005 | You submitted an invalid operation type with your request. |
| 400 | 5010 | The submitted country code is invalid. |
| 400 | 5016 | The merchant account you provided cannot be found. |
| 400 | 5017 | The merchant account you provided is disabled. |
| 402 | 5021 | Your transaction request has been declined. |
| 400 | 5023 | The request is not parseable. |
| 409 | 5031 | The transaction you have submitted has already been processed. |
| 401 | 5040 | Your merchant account is not configured for the transaction you attempted. |
| 400 | 5042 | The merchant reference number is missing or invalid or it exceeds the maximum permissible length. |
| 400 | 5068 | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. |
| 404 | 5269 | The ID(s) specified in the URL do not correspond to the values in the system. |
| 403 | 5270 | The credentials provided with the request do not have permission to access the requested data. |
| 406 | 5271 | You requested a response in the 'Accept' header that is in an unsupported format. |
| 406 | 5272 | The 'Content-Type' you specified in request header was submitted in an unsupported format. |
| 404 | 5273 | Your client reached our application but we were unable to service your request due to an invalid URL. |
| 401 | 5275 | The authentication credentials provided with the request have expired. |
| 401 | 5276 | The authentication credentials provided with the request provided have been disabled. |
| 401 | 5277 | The authentication credentials provided with the request have been locked due to multiple authentication failures. |
| 401 | 5278 | The authentication credentials provided with the request were not accepted for an unknown reason. |
| 401 | 5279 | The authentication credentials are invalid. |
| 401 | 5280 | The required authentication credentials were not provided. |
| 405 | 5281 | The request uses an action (for example, GET, POST, or PUT) that is not supported by the resource. |
| 400 | 5283 | The requested operation can only be executed on a Payment Handle with the status of PAYABLE. |
| 409 | 5284 | An entity with the specified identifier(s) already exists. |
| 400 | 5501 | The profile does not have an active credit card. |
| 400 | 5502 | Either the payment token is invalid or the corresponding profile or bank account is not active. |
| 400 | 7510 | You submitted invalid bank account information for your banking scheme. |
Embedded Wallets Errors
Embedded Wallets specific errors have codes, prefixed by DW prefix.
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 400 | DW-NO-SUCH-CUSTOMER | Customer was not found. |
| 500 | DW-INTERNAL-SERVER-ERROR | Internal Server Error. |
| 503 | DW-SERVICE-UNAVAILABLE | Service Unavailable. |
| 409 | DW-CUSTOMER-NOT-ALLOWED | Operation not allowed for this customer. |
| 409 | DW-CORPORATE-CUSTOMER-NOT-ALLOWED | Operation not allowed for corporate customers. |
| 405 | DW-OPERATION-NOT-ALLOWED | Operation is not allowed in your account. Contact Paysafe for further details. |
Customer Management Errors
Authentication Errors
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 400 | DW-AUTHENTICATION-FAILURE | The authentication process was unsuccessful. |
| 409 | DW-AUTHENTICATION-NOT-ALLOWED | The authentication process is not allowed. |
| 412 | DW-VALIDATION-FAILURE | The validation process was unsuccessful. |
| 412 | DW-SCREENING-FAILURE | The screening process was unsuccessful. |
Wallet Errors
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 400 | DW-TERMS-AND-CONDITIONS-NOT-ACCEPTED | Terms and conditions are not accepted. |
| 400 | DW-CUSTOMER-BAD-REQUEST | Bad request for customer operation. |
| 400 | DW-CUSTOMER-COUNTRY-NOT-SUPPORTED | Country is not supported. |
| 400 | DW-CUSTOMER-CURRENCY-NOT-SUPPORTED | Currency is not supported for the specified country. |
| 400 | DW-CUSTOMER-ID-SHOULD-BE-NUMERIC | CustomerId should be numeric value. |
| 400 | DW-CUSTOMER-ID-SHOULD-BE-VALID | CustomerId is not supported. |
| 400 | DW-CUSTOMER-ACCOUNT-ID-SHOULD-BE-VALID | AccountId is not supported. |
| 400 | DW-CUSTOMER-TRANSACTION-ID-SHOULD-BE-VALID | TransactionId is not supported. |
| 400 | DW-CUSTOMER-EMAIL-CHANGE-NOT-SUPPORTED | Email change is not supported. |
| 400 | DW-CUSTOMER-BIRTH-DATE-CHANGE-NOT-SUPPORTED | Birth date change is not supported. |
| 400 | DW-SIGNATURE-HEADER-REQUIRED | Signature header is required. |
| 400 | DW-HMAC-SIGNATURE-INVALID | Signature is invalid. |
| 400 | DW-CUSTOMER-KYC-NOT-COMPLETED | Invalid KYC status. |
| 400 | DW-CUSTOMER-KYC-ID-VERIFICATION-NOT-COMPLETED | Invalid ID verification status. |
| 400 | DW-CUSTOMER-KYC-ADDRESS-VERIFICATION-NOT-COMPLETED | Invalid Address verification status. |
| 400 | DW-CUSTOMER-KYC-FACE-MATCH-NOT-COMPLETED | Invalid Face match status. |
| 400 | DW-INVALID-MOBILE-NUMBER | Mobile number is invalid. |
| 400 | DW-CUSTOMER-EMAIL-AND-MOBILE-MISSING | Both email and mobile are missing. At least one of them should be provided. |
| 400 | DW-SCA-VERIFICATION-FAILED | The transaction was declined because the SCA requirement is not completed. |
| 400 | DW-MISSING-CUSTOMER-DATA | Both customer and legalEntity properties are not provided and exactly one of them is expected. |
| 400 | DW-AMBIGUOUS-CUSTOMER-TYPE | Both customer and legalEntity properties are provided while only one of them is expected to determine the correct type of the customer. |
| 400 | DW-IBAN-NOT-ASSIGNABLE | Iban can not be assigned to the provided account. |
| 400 | DW-CUSTOMER-FIRSTNAME-INVALID | Invalid first name. |
| 400 | DW-CUSTOMER-LASTNAME-INVALID | Invalid last name. |
| 400 | DW-LEGALENTITY-REPRESENTATIVE-FIRSTNAME-INVALID | Invalid representative first name. |
| 400 | DW-LEGALENTITY-REPRESENTATIVE-MIDDLE_NAME-INVALID | Invalid representative middle name. |
| 400 | DW-LEGALENTITY-REPRESENTATIVE-LAST-NAME-INVALID | Invalid representative last name. |
| 400 | DW-LEGALENTITY-DIRECTOR-FIRST-NAME-INVALID | Invalid director first name. |
| 400 | DW-LEGALENTITY-DIRECTOR-MIDDLE-NAME-INVALID | Invalid director middle name. |
| 400 | DW-LEGALENTITY-DIRECTOR-LAST-NAME-INVALID | Invalid director last name. |
| 403 | DW-CUSTOMER-IP-COUNTRY-SANCTIONED | Customer's IP country falls into the list of sanctioned countries. |
| 403 | DW-CUSTOMER-IP-COUNTRY-NON-SERVICED | Customer's IP country falls into the list of non-serviced countries. |
| 409 | DW-MOBILE-NUMBER-ALREADY-EXISTS | Mobile number already exists. |
| 409 | DW-CUSTOMER-EMAIL-ALREADY-EXISTS | Email address already exists. |
| 409 | DW-CUSTOMER-ALREADY-ONBOARDED | Customer with the same details has already been onboarded. |
| 409 | DW-CUSTOMER-CONFLICT | There was a conflict (validation error). Check body for details. |
| 409 | DW-ACCOUNTS-BALANCES-NOT-EMPTY | There are accounts with non-empty balances. |
| 409 | DW_CUSTOMER_REGISTRATION_TYPE_MISMATCH | Trying to create a customer, which is already onboarded with the same externalId and a different registration type. |
| 422 | DW-DUPLICATE-ACCOUNT-CURRENCIES | More than one account in same currency is not allowed. |
Restrictions Errors
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 400 | DW-WALLET-ID-NOT-FOUND | Wallet with the requested ID was not found. |
| 409 | DW-CUSTOMER-ALREADY-ACTIVATED | Customer is already activated. |
| 409 | DW-CUSTOMER-ALREADY-DEACTIVATED | Customer is already deactivated. |
Transfer Errors
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 400 | DW-TRANSFER-INVALID-CURRENCY | The transfer was requested for a currency different that of the sender. |
| 400 | DW-TRANSFER-FEE-NOT-SUPPORTED | Fees not supported for transfers. |
| 400 | DW-TRANSFER-SELF-TRANSFER | Recipient and sender are identical. |
| 400 | DW-TRANSFER-EXPIRED-QUOTE | Exchange rates quote has expired. |
| 400 | DW-TRANSFER-INVALID-QUOTE | Exchange rates quote is invalid. |
| 400 | DW-TRANSFER-FORBIDDEN-REASON | Transfer can't be performed with provided reason. |
| 400 | DW-TRANSFER-INVALID-STATUS-UPDATE | Invalid transfer status change. |
| 400 | DW-TRANSFER-LIMIT-EXCEEDED | The sending customer exceeds/has exceeded their transfer limit. |
| 400 | DW-TRANSFER-NOT-ENOUGH-BALANCE | The sending customer has insufficient balance for the transaction. |
| 404 | DW-TRANSFER-NOT-FOUND | No transfer matching the provided parameters was found. |
| 400 | DW-TRANSFER-DUPLICATED-MERCHANT-REF | Duplicate merchant reference provided. |
| 400 | DW-TRANSFER-PREVIEW-EXPIRED | Transfer preview expired. |
| 400 | DW-TRANSFER-SELF-TRANSFER | Transfer recipient and sender are identical. |
| 400 | DW-TRANSFER-NOT-ALLOWED | Either sender or recipient are restricted for transfers. |
Authorization Hold Errors
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 404 | DW-NO-MATCHING-ACCOUNTS | Could not find matching accounts for customer. |
| 404 | DW-AUTHORIZATION-HOLD-NOT-FOUND | Could not find authorization hold. |
| 400 | DW-INVALID-AUTHORIZATION-HOLD-STATUS | Invalid authorization hold status requested. |
| 404 | DW-CUSTOMER-ACCOUNT-FOR-CURRENCY-NOT-FOUND | Couldn't find an account matching the specified customer id and currency. |
| 404 | DW-ACCOUNT-NOT-FOUND | Couldn't find account with specified id. |
| 400 | DW-INSUFFICIENT-BALANCE-FOR-AUTHORIZATION-HOLD | Customer does not have sufficient balance for authorization hold. |
| 400 | DW-CUSTOMER-IS-RESTRICTED-FOR-TRANSFERS | Cannot create an authorization hold for customer that cannot transfer money. |
Deposit Errors
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 400 | DW-INVALID-OR-EXPIRED-PAYMENT-INSTRUMENT | The payment instrument is either invalid or expired. |
| 409 | DW-PAYMENT-INSTRUMENT-ALREADY-EXISTS | The payment instrument already exists. |
| 400 | DW-BANK-ACCOUNT-NOT-VERIFIED | The bank account is not verified. |
| 400 | DW-PAYMENT-METHOD-NOT-AVAILABLE | This payment method is not available. |
| 400 | DW-PAYMENT-INSTRUMENT-NOT-FOUND | This payment instrument is not found. |
| 500 | DW-SLIP-NOT-CREATED | There was an error while creating the slip. |
| 403 | DW-PERMISSION-TO-DEPOSIT | You do not have permission to deposit. |
| 400 | DW-PAYMENT-INSTRUMENT-NOT-CREATED | We are unable to create the payment instrument. |
| 400 | DW-INVALID-PAYMENT-OPTION | The payment option provided is invalid. |
| 400 | DW-SLIP-NOT-FOUND | The deposit slip was not found. |
| 500 | DW-DEPOSIT-NOT-FINALIZED | There was an error while finalizing the deposit. |
| 400 | DW-INVALID-ACCOUNT-CURRENCY | The provided currency is not valid. |
| 404 | DW-CUSTOMER-DELETED-OR-HAS-NO-ACTIVE-EWALLET-ACCOUNT | Customer is deleted or has no active e-wallet account. |
| 400 | DW-INVALID-TRANSACTION-STATUS | The transaction status is invalid. |
| 500 | DW-DEPOSIT-RESPONSE-NOT-CREATED | Error while creating deposit response. |
| 404 | DW-CUSTOMER-BRAND-MISMATCH | No such customer in provided brand. |
| 400 | DW-NEGATIVE-FEE | Invalid fee value. Negative fee is not accepted. |
| 400 | DW-INVALID-FEE-RANGE | Invalid fee value. Fee must be less or equal to transaction amount. |
| 400 | DW-PAYMENT-INSTRUMENT-INVALID-TYPE | The provided instrument type is invalid. |
| 400 | DW-INSTRUMENT-ID-SHOULD-BE-NUMERIC | InstrumentId should be numeric value. |
| 400 | DW-INSTRUMENT-BALANCE-NOT-ENOUGH | The payment instrument has insufficient balance for the transaction. |
Withdrawal Errors
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 400 | DW-INVALID-SLIP-PROVIDED | Provided slip does not belong to the customer. |
| 403 | DW-PERMISSION-TO-WITHDRAW | You do not have permission to withdraw. |
| 400 | DW-BANK-VALIDATION-FAILED | Bank validation failed. |
| 400 | DW-BANK-DECLINE | Declined by the processing bank. |
| 400 | DW-BANK-PROCESSING-FAILED | The system is unable to send this request to the processing bank. |
| 400 | DW-INVALID-WITHDRAW-ACCOUNT | Withdrawal from this account is not supported. |
Instrument errors
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 400 | DW-INVALID-INSTRUMENT-TYPE-FOR-VERIFICATION | The provided instrument type is not supported for instrument verification. |
| 400 | DW-BANK-ACCOUNT-LIMIT-EXCEEDED | Customer has reached the limit number of verified bank accounts and open payment instrument verification sessions. |
Prepaid Cards
Create Card
| HTTP STATUS CODE | ERROR CODE | MESSAGE |
|---|---|---|
| 400 | DW-PREPAID-CARDS-NOT-SUPPORTED-CURRENCY | Provided currency is not supported by your program. |
| 400 | DW-PREPAID-CARDS-PROGRAM-NOT-SUPPORTED | Program is not supported. |
| 400 | DW-PREPAID-CARDS-TERMS-NOT-ACCEPTED | Please ensure that both the Terms and Conditions and eDisclosure have been accepted. |
Activate Card
| HTTP STATUS CODE | ERROR CODE | MESSAGE |
|---|---|---|
| 400 | DW-PREPAID-CARDS-ARGUMENT-MISMATCH | The information provided is inconsistent. Please verify the fields for accuracy. |
Get Card Details
| HTTP STATUS CODE | ERROR CODE | MESSAGE |
|---|---|---|
| 400 | DW-PREPAID-CARDS-ARGUMENT-MISMATCH | The provided information is inconsistent. Please verify the fields for accuracy. |
Update Card Status
| HTTP STATUS CODE | ERROR CODE | MESSAGE |
|---|---|---|
| 400 | DW-PREPAID-CARDS-STATUS-NOT-ALLOWED | Card status is not allowed for the current card type. |
| 400 | DW-PREPAID-CARDS-STATUS-ALREADY-APPLIED | Current card status is the same as the request. |
| 400 | DW-PREPAID-CARDS-STATUS-IRREVERSIBLE | Current card status is irreversible. |
Webhook errors
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 400 | DW-NOTIFICATION-RESEND-TASK-BAD-REQUEST | Bad request for notification resend task operation. |
| 400 | DW-NOTIFICATION-RESEND-TASK-MISSING-REQUIRED-PARAMETERS | The request for notification resend request is missing required parameters. |
| 400 | DW-NOTIFICATION-RESEND-TASK-INVALID-REQUEST-TIMEFRAME | The defined timeframe for notification resend request is invalid. It is too long or in the future. |
| 400 | DW-NOTIFICATION-RESEND-TASK-TOO-MANY-FILTERS-APPLIED | There are too many filters specified. Only one should be applied. |
Transfer errors
| Error Code | Message |
|---|---|
| TRANSFER_NOT_ENOUGH_BALANCE | The sending customer has insufficient balance for the transaction. |
| TRANSFER_AUTH_HOLD_AMOUNT_MISMATCH | The provided authorization hold blocks a lower amount than the requested for the transfer. |
| TRANSFER_AUTH_HOLD_NOT_FOUND | The requested authorization hold was not found. |
| TRANSFER_AUTH_HOLD_STATUS_MISMATCH | The requested authorization hold has either been released or used. |
| TRANSFER_AUTH_HOLD_CURRENCY_MISMATCH | The requested authorization hold blocks an amount in a different currency from the one requested. |
| DW-TRANSFER-NOT-ALLOWED | Either sender or recipient are restricted for transfers. |
| DW-TRANSFER-LIMIT-EXCEEDED | The sending customer exceeds/has exceeded their transfer limit. |
| DW_NO_SUCH_CUSTOMER | Either the sender or recipient was not found. |
| DW-TRANSFER-INVALID-CURRENCY | The transfer was requested for a currency different that of the sender. |
| DW-TRANSFER-GENERAL-ERROR | Error during processing the transfer. Transaction was not created. |
| DW-TRANSFER-DUPLICATE-MERCHANT-REF | Duplicate merchant reference provided. |
| BANK-DECLINE | Declined by the processing bank. Please check the bank account details of the request. |
| BANK-TECHNICAL-FAILURE | Unable to send the transfer to the processing bank at this moment. Please submit another withdrawal request. |
Refund errors
| HTTP Status Code | Error Code | Message |
|---|---|---|
| 409 | DW-REFUND-NOT-ALLOWED | Transaction is non refundable. |
| 409 | DW-REFUND-STATUS-NOT-ALLOWED | Deposit transaction is in non refundable status. |
| 409 | DW-REFUND-INVALID-AMOUNT | Invalid refund amount. Refund amount must be lower or equal to deposit amount |
| 409 | DW-REFUND-INVALID-CURRENCY | Invalid refund amount. Refund must match the deposit currency. |
| 409 | DW-REFUND-INVALID-TRANSACTION-REFERENCE | Refund can only be made on deposit transactions. |
| 409 | DW-REFUND-NOT-EXISTS | Missing refund transaction. |
| 409 | DW-REFUND-CUSTOMER-MISMATCH | The customer of the refund must match the customer of the deposit transaction. |
Was this page helpful?
On this Page