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 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 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 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.
400	DW-DUPLICATE-MERCHANT-REF-NUM	Duplicate merchant reference.
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.
400	DW-DEPOSIT-EXPIRED	The deposit request has expired.
404	DW-ENTITY-NOT-FOUND	Entity not found.
409	DW-MERCHANT-FEE-FX-NOT-ALLOWED	Merchant fee currency conversion not allowed.

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.
400	DW-UPDATE-INVALID-STATUS	Invalid status in update request.
400	DW-WITHDRAWAL-EXPIRED	Withdrawal expired.
400	DW-INVALID-TRANSACTION-STATUS	The transaction status is invalid.

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.