Search Overlay

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.

Error Code (FAILED_REASON_CODE) Description (FAILED_REASON_DETAILS)
BANK-DEPOSIT-FAILED-INSTRUMENT The deposit used unacceptable payment instrument.
BANK-DEPOSIT-NAME-MISMATCH The sender name does not match wallet owner.
DW-BANK-DECLINE Declined by the processing bank.
DW-DEPOSIT-NOT-CONFIRMED The deposit has not been confirmed.
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.
TRANSFER_PARTY_NOT_FOUND Either the sender or recipient was not found.
TRANSFER_DUPLICATE_MERCHANT_REF Merchant reference is already in use.
TRANSFER_REQUEST_INVALID_CURRENCY Transfer request currency is different from sender account currency
TRANSFER_LIMIT_EXCEEDED The sending customer exceeds/has exceeded their transfer limit for the transaction/for a period of time
TRANSFER_GENERAL_ERROR Error during processing the transfer. Transaction was not created.
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 Message
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.

Digital Wallet Errors

Digital Wallet 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

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.
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.

Restricted 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

Wallet Errors

HTTP Status Code Error Code Message
400 DW-TRANSFER-INVALID-CURRENCY Invalid currency
400 DW-TRANSFER-FEE-NOT-SUPPORTED Fees not supported for transfers
400 DW-TRANSFER-SELF-TRANSFER Recipient and sender are identical

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.

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.

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
TRANSFER_NOT_ALLOWED Either the sender or recipient are restricted for transfers
TRANSFER_LIMIT_EXCEEDED The sending customer exceeds/has exceeded their transfer limit for the transaction/for a period of time
TRANSFER_PARTY_NOT_FOUND Either the sender or recipient was not found
TRANSFER_REQUEST_INVALID_CURRENCY The transfer was requested for a currency different that of the sender
TRANSFER_GENERAL_ERROR Error during processing the transfer. Transaction was not created.
TRANSFER_DUPLICATE_MERCHANT_REF Duplicate merchant reference provided. Transfer was failed.
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-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.