Direct Debit Errors
JSON error responses from the Direct Debit API include information in the body of the response similar to the following:
{
"error":{
"code":"5016",
"message":"The merchant account submitted with your request could not be found",
"details":[
"Account 89983659 does not exist"
],
"links":[
{
"rel":"errorinfo",
"href":"https://developer.paysafe.com/en/rest-api/direct-debit/test-and-go-live/direct-debit-errors/#ErrorCode5016"
}
]
}
}
{
"error":{
"code":"5270",
"message":"The credentials provided with the request do not have permission to access the data requested.",
"links":[
{
"rel":"errorinfo",
"href":"https://developer.paysafe.com/en/rest-api/direct-debit/test-and-go-live/direct-debit-errors/#ErrorCode5270"
}
]
}
}
The error object consists of the following elements:
| Element | Type | Required? | ||
|---|---|---|---|---|
| code | string | The error code. Also shown in the X-Application-Status-Code response header. | Yes | |
| message | string | The error message describing the error. | Yes | |
| details | string array | Further details about the error. | Optional | |
| links (Array of rel:href pairs) | rel | string | The type of link: "errorinfo". | Yes |
| href | string | The URL within the Developer Center that contains a description of the error. | Yes | |
To save you having to parse the response body to find the error information, you can retrieve the error code from the X-Application-Status-Code response header.
This is a summary of all errors that could be returned when using the Direct Debit API, including HTTP Status Codes.
HTTP Status Code Summary
| Code Range | Description |
|---|---|
| 1xx: Informational | Communicates transfer protocol–level information. |
| 2xx: Success | Indicates that the client’s request was accepted. |
| 3xx: Redirection | Indicates that the client must take some additional action in order to complete the request. |
| 4xx: Client Error | Indicates that the client has made an error with the request. |
| 5xx: Server Error | Indicates that an error occurred on the server side. |
Common HTTP Response Status Codes
| Code | Description |
|---|---|
| 200 OK | Everything worked as expected. |
| 201 Created | The request was successful. Paysafe created a new resource and the response body contains the representation. |
| 202 Accepted | This indicates that the client’s request will be handled asynchronously. It tells the client that the request appears valid, but it still may have problems once it is processed. |
| 204 No Content | This is usually returned in response to a PUT, POST, or DELETE request when the REST API declines to send back any status message or representation in the body of the response message. |
| 304 Not Modified | The client's cached version of the representation is still up to date. |
| 400 Bad Request | This often indicates that a required parameter is missing or that a parameter is invalid. This is a generic client-side error status, used when no other 4xx error code is appropriate. |
| 401 Unauthorized | This indicates that the client tried to operate on a protected resource without providing the proper authorization. They may have provided the wrong credentials or none at all. |
| 402 Payment Required | The parameters were valid but the request failed. |
| 404 Not Found | The requested resource does not exist. |
| 405 Method Not Allowed | The client tried to POST or PUT to a resource that would not accept it. |
| 415 Unsupported Media Type | The request is in a format not supported by the requested resource for the requested method. |
| 429 Too Many Requests | The application is sending too many simultaneous requests. |
| 500 Internal Server Error | An error occurred with an internal server. |
| 502 External Server Error | We received an invalid response from the upstream gateway in attempting to fulfill the request. |
Common Errors
| 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. |
| 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 parsable. |
| 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 (e.g., GET, POST, or PUT) that is not supported by the resource. |
| 400 | 5501 | The profile does not have an active credit card. |
| 400 | 5500 | Either the payment token is invalid or the corresponding profile or bank account is not active. |
Direct Debit Errors
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | 2004 | The Direct Debit transaction cannot be found. |
| 400 | 2011 | You have submitted a mandate reference that does not exist. |
| 400 | 2012 | You have submitted a mandate reference that is not active yet. |
| 400 | 2013 | The mandate reference does not have a valid status. |
| 400 | 2014 | The mandate reference is already in use for the specified bank account information. |
| 400 | 2017 | The payment token bank scheme does not match the merchant account bank scheme. |
| 402 | 4002 | The transaction was declined by our risk management department. |
| 400 | 2019 | The specified bank and account information is currently under INVALID state. |
| 400 | 2008 | You have submitted an invalid routing or transit number. |
Return Codes
Occasionally, a Direct Debit API request will be successful, but can fail at the banking network level, e.g., due to insufficient funds or bank account closure. In such cases, the bank scheme provides a Return Code as an explanation. Because Direct Debit requests can take up to 7 days to clear, you cannot be notified of errors such as these via the API response.
However, you can use the Paysafe Merchant Back Office to run reports to view Return Codes in the case where a Direct Debit request has failed.
| Code | Description | Bank Scheme |
|---|---|---|
| 900 | Validation Rejection | EFT |
| 901 | Not sufficient funds (debits only) | EFT |
| 902 | Cannot trace | EFT |
| 903 | Payment stopped/recalled | EFT |
| 904 | Post dated/stale dated | EFT |
| 905 | Account closed | EFT |
| 906 | Account transferred | EFT |
| 907 | No chequing privileges | EFT |
| 908 | Funds not cleared | EFT |
| 909 | Currency/Account Mismatch | EFT |
| 910 | Payor/payee deceased | EFT |
| 911 | Account frozen | EFT |
| 912 | Invalid/incorrect account number | EFT |
| 914 | Incorrect payor/payee name | EFT |
| 915 | Refused by payor/payee | EFT |
| 916 | Not in accordance with Agreement - Personal | EFT |
| 917 | Agreement Revoked - Personal | EFT |
| 918 | No Pre-Notification - Personal | EFT |
| 919 | Not in accordance with Agreement - Business | EFT |
| 920 | Agreement Revoked - Business | EFT |
| 921 | No Pre-Notification - Business | EFT |
| 922 | Customer Initiated Return Credit Only | EFT |
| 990 | Institution in Default | EFT |
| 998 | No Return Agreement | EFT |
| 4 | TRANSACTION TYPE is invalid or blank. See Appendix 3 for a list of CPA Transaction Types. | EFT |
| 5 | AMOUNT is blank, or not greater than zero. | EFT |
| 6 | DUE DATE is invalid or blank. | EFT |
| 7 | INSTITUTION (route and/or transit) is not in the correct format, does not exist or is blank. | EFT |
| 8 | ACCOUNT NUMBER is not a valid format for the specified INSTITUTION. | EFT |
| 9 | ITEM TRACE NO. is invalid. | EFT |
| 10 | STORED TRANSACTION TYPE is invalid or blank. | EFT |
| 11 | ORIGINATOR SHORT NAME is blank. | EFT |
| 12 | PAYOR/PAYEE NAME is blank. | EFT |
| 13 | ORIGINATOR LONG NAME is blank. | EFT |
| 14 | Originating Direct Clearer ID is invalid or blank. | EFT |
| 15 | CROSS REFERENCE is blank. | EFT |
| 16 | INSTITUTION FOR RETURNS (route and/or transit) is invalid or blank. It should specify your credit union. | EFT |
| 19 | Original item trace number is invalid or blank. | EFT |
| 21 | DATA ELEMENT ID is invalid or blank. | EFT |
| E | Accepted but errors were noted | EFT |
| M | Rejected, message authentication code (MAC) failed | EFT |
| P | Partially accepted, at least one transaction set was rejected | EFT |
| R | Rejected | EFT |
| W | Rejected, assurance failed validity tests | EFT |
| X | Rejected, content after decryption could not be analyzed | EFT |
| TR | Rejected by 824 | EFT |
| YE | Transaction code unauthorised for originating Account | BACS |
| 0 | Refer to Payer | BACS |
| 1 | Instruction cancelled by payer | BACS |
| 2 | Payer Deceased | BACS |
| 3 | Account Transferred | BACS |
| 4 | Advance Notice Disputed | BACS |
| 5 | No Account | BACS |
| 6 | No Instruction | BACS |
| 7 | Amount Differs | BACS |
| 8 | Amount not yet due | BACS |
| 9 | Presentation Overdue | BACS |
| A | Service User Differs | BACS |
| B | Account Closed | BACS |
| E | Instruction amended | BACS |
| AE | Originating sort code and/or Account number invalid (bank originated) | BACS |
| BE | Originating sort code and/or Account number invalid (customer originated) | BACS |
| CE | Destination sort code and originating sort code and/or Account number invalid (bank originated) | BACS |
| DE | Destination sort code and originating sort code and/or Account number invalid (customer originated) | BACS |
| EE | Destination sort code invalid | BACS |
| FE | Account type and originating sort code and/or Account number invalid (bank originated) | BACS |
| GE | Account type and originating sort code and/or Account number invalid (customer originated) | BACS |
| HE | Destination sort code and Account type and originating sort code and/or Account number invalid (bank originated) | BACS |
| IE | Destination sort code and Account type and originating sort code and/or Account number invalid (customer originated) | BACS |
| JE | Destination sort code and Account type invalid | BACS |
| KE | Account type invalid | BACS |
| LE | Destination Account number and destination Account name and other fields invalid | BACS |
| ME | Destination Account number and destination Account name invalid | BACS |
| NE | Contra record was amended | BACS |
| OE | Reference number was invalid | BACS |
| PE | Originating Account does not support the file currency | BACS |
| QE | Automated reversal due to an error | BACS |
| RE | Reversal of another item (same day) | BACS |
| SE | Automated recall | BACS |
| TE | Originating Account invalid and was substituted with the default main Account details, but this Account does not support the file currency (customer originated) | BACS |
| UE | Unpaid direct debit reference was in error (bank originated) | BACS |
| XE | Originator's service user number invalid (bank originated) | BACS |
| ZE | Unpaid direct debit reference and other fields were in error (bank originated) | BACS |
| 1I | Amount and / or date of Direct Debit differ from Advance Notice | BACS |
| 2I | No Advance Notice received by Payer/or the amount quoted is disputed | BACS |
| 3I | DDI cancelled by paying bank | BACS |
| 4I | Payer has cancelled DDI direct with service user | BACS |
| 5I | AUDDIS service users only - No Instruction held. Payer disputes having given authority | BACS |
| 6I | AUDDIS service users only - Signature on DDI is fraudulent or not in accordance with account authorised signature(s) | BACS |
| 7I | Claim raised at service users request after Direct Debit applied to payers account | BACS |
| 8I | Service user name disputed. Payer does not recognise service user collecting Direct Debit | BACS |
| CC | Requested by originator | BACS |
| 0C | Invalid details | BACS |
| 2C | Beneficiary deceased | BACS |
| 3C | Account transferred | BACS |
| 5C | No account | BACS |
| BC | Account closed | BACS |
| C | Account transferred to a different branch of bank / building society | BACS |
| D | Advance notice disputed | BACS |
| F | Invalid account type | BACS |
| G | Bank will not accept Direct Debits on account | BACS |
| H | Instruction has expired | BACS |
| I | Payer reference is not unique | BACS |
| K | Instruction cancelled by paying bank | BACS |
| L | Incorrect payer's account details | BACS |
| M | Transaction code / user status incompatible | BACS |
| N | Transaction disallowed at payer's branch | BACS |
| O | Invalid reference | BACS |
| P | Payer's Name not present | BACS |
| Q | Service user's name blank | BACS |
| R | Instruction re-instated (maximum 2 months from original DDI cancellation date) | BACS |
| AC01 | Account identifier incorrect | SEPA |
| UPAY | Undue payment | SEPA |
| AC06 | Account blocked | SEPA |
| AC13 | Invalid debtor account type | SEPA |
| AG01 | Direct debit forbidden | SEPA |
| AG02 | Invalid bank operation code | SEPA |
| AGNT | Incorrect agent | SEPA |
| AM04 | Insufficient funds | SEPA |
| AM05 | Duplication | SEPA |
| BE04 | Missing creditor address | SEPA |
| BE05 | Unrecognized creditor | SEPA |
| CURR | Incorrect currency | SEPA |
| CUST | Recall by customer | SEPA |
| CUTA | Recall due to investigation request | SEPA |
| DT01 | Invalid date | SEPA |
| DUPL | Duplicate payment | SEPA |
| ED05 | Settlement failed | SEPA |
| FF01 | Invalid file format | SEPA |
| FF05 | Direct debit type incorrect | SEPA |
| FRAD | Fraud | SEPA |
| MD01 | No valid mandate | SEPA |
| MD02 | Mandate data missing or incorrect | SEPA |
| MD06 | Disputed authorized transaction | SEPA |
| MD07 | Debtor deceased | SEPA |
| MS02 | Refusal by debtor | SEPA |
| MS03 | Reason not specified | SEPA |
| PY01 | Not routable | SEPA |
| RC01 | Bank identifier incorrect | SEPA |
| RR01 | Missing debtor account or identification | SEPA |
| RR02 | Missing debtor name or address | SEPA |
| RR03 | Missing creditor name or address | SEPA |
| RR04 | Regulatory reason | SEPA |
| SL01 | Specific service offered by debtor agent | SEPA |
| TECH | Payment in error due to technical problem | SEPA |
| TM01 | Invalid cut off time | SEPA |
| AC04 | Account closed | SEPA |
| RT not found | ACH | |
| CONFIG | Client configuration problem | ACH |
| LIMIT | The maximum amount per check was exceeded. | ACH |
| INVACCT | Invalid account type. | ACH |
| INVDIR | Invalid direction. | ACH |
| NOPOP | Merchant not configured or not allowed to run POP transactions - Electronic Check Conversion. | ACH |
| PAPER | Paper draft and can't send paper. | ACH |
| PARSE | Parsing problem | ACH |
| THOMSON | Reject due to Thomson database. | ACH |
| UNKMER | Unknown merchant. | ACH |
| DEMO | Demonstration transaction/ or merchant. | ACH |
| R90 | Invalid MOD digit | ACH |
| R91 | Invalid ABA. Not nine (9) characters or numeric | ACH |
| R92 | ABA not active | ACH |
| R93 | Invalid Tran Code SEC combo | ACH |
| R94 | Invalid amount for pre-note Tran Code | ACH |
| R95 | Amount is zero (0) | ACH |
| R96 | Not a valid Tran code | ACH |
| R97 | Not a valid SEC code | ACH |
| R98 | Account decryption error | ACH |
| R99 | OFAC possible match | ACH |
| R37 | Source Document Presented for Payment | ACH |
| R38 | StopPayment on Source Document | ACH |
| R39 | Improper Source Document | ACH |
| R53 | Item and ACH Entry Presented for Payment | ACH |
| R75 | Original Return not a Duplicate | ACH |
| R76 | No Errors Found | ACH |
| R83 | Foreign Receiving DFI Unable to Settle | ACH |
| R84 | Entry Not Processed by OGO | ACH |
| R01 | Insufficient funds | ACH |
| R02 | Account closed | ACH |
| R03 | No account/unable to locate | ACH |
| R04 | Invalid account number | ACH |
| R05 | Reserved | ACH |
| R06 | Return requested by ODFI | ACH |
| R07 | Authorization revoked Note 2 | ACH |
| R08 | Stop payment | ACH |
| R09 | Uncollected funds | ACH |
| R10 | Not authorizedNote 2 | ACH |
| R11 | Check truncation entry return | ACH |
| R12 | Branch sold to another DFI | ACH |
| R13 | RDFI not qualified to participate/or invalid route | ACH |
| R14 | Payee deceased | ACH |
| R15 | Beneficiary deceased | ACH |
| R16 | Account frozen | ACH |
| R17 | File record edit criteria | ACH |
| R18 | Improper effective entry date | ACH |
| R19 | Amount field error | ACH |
| R20 | Non transaction account | ACH |
| R21 | Invalid company ident. | ACH |
| R22 | Invalid individual ID number | ACH |
| R23 | Credit entry refused by receiver | ACH |
| R24 | Duplicate entry | ACH |
| R25 | Addenda error | ACH |
| R26 | Mandatory field error | ACH |
| R27 | Trace number error | ACH |
| R28 | Routing # check digit error | ACH |
| R29 | Corp cust. adviser not auth. | ACH |
| R30 | RDFI non-part truncation prob | ACH |
| R31 | Permissible return entry | ACH |
| R32 | RDFI non-settlement | ACH |
| R33 | Return of XCK entry | ACH |
| R34 | Limited participation DFI | ACH |
| R35 | Return of improper debit entry | ACH |
| R36 | Return of improper credit entry | ACH |
| R40 | Return of ENR entry by Fed. Gov. | ACH |
| R41 | Invalid transaction code | ACH |
| R42 | Routing #/check digit error | ACH |
| R43 | Inv. DFI acct. number | ACH |
| R44 | Inv. Individual ED number | ACH |
| R45 | Inv. individual name/company name | ACH |
| R46 | Inv. rep. payee indicator | ACH |
| R47 | Duplicate enrollment | ACH |
| R50 | State Law affecting RCK acceptance | ACH |
| R51 | Item is ineligible (RCK) | ACH |
| R52 | Stop payment on item (RCK) | ACH |
| R61 | Dishonor | ACH |
| R62 | Dishonor | ACH |
| R63 | Dishonor | ACH |
| R64 | Dishonor | ACH |
| R65 | Dishonor | ACH |
| R66 | Dishonor | ACH |
| R67 | Dishonor | ACH |
| R68 | Dishonor | ACH |
| R69 | Dishonor | ACH |
| R70 | Dishonor | ACH |
| R71 | ContestedNote 4 | ACH |
| R72 | ContestedNote 4 | ACH |
| R73 | ContestedNote 4 | ACH |
| R74 | ContestedNote 4 | ACH |
| R80 | Cross- border payment coding error | ACH |
| R81 | Non-participant in cross-border pgm. | ACH |
| R82 | Invalid foreign RDFI ID | ACH |