API Details
Direct Debit payments can fail at various stages in their lifecycle.
Where you are creating payments via the API you will be informed in your API response when there is an error in your request.
The List Failed Direct Debits API allows you to query any Bank-related rejects (i.e. any R-Transactions received after your DD payments have been exported to SEPA Clearing or to Bacs).
It also allows you to list any Technical Rejects that you may have had (you will only have Technical Rejects if you are importing payments via file upload; API requests do not result in Technical Rejects).
Failed payments can be grouped into three basic types:
| Type | Description |
|---|---|
| Technical Rejects | If you are importing payments into Nuapay via a file upload, some payments may be rejected for failing business validation rules. You may receive a DD001 code, for example, if you reference a mandate/DDI that does not exist. Note that there are no Technical Rejects for API or UI-based payments. In the case of an API request the response will indicate in real time that the payment has failed (if you have provided an incorrect mandate or DDI reference in your Create Direct Debit call, for example, you will receive a 7021 error code). |
| Pre-settlement Failures | Payments that are created and exported that the Payer’s bank then rejects or refuses before the collection date. Only applicable to SEPA schemes. |
| Post-settlement Failures | Payments that are exported and accepted but the bank then fails after the collection date. |
API Details
The List Failed Direct Debits request allows you to return a list of all:
- Technical rejects (only possible if you are processing files).
- Pre-settlement Rejects/Refusals (only in SEPA schemes).
- Post-settlement Returns/Refunds.
We recommend that you schedule to run this request at various times in the lifecycle of your Direct Debits, to ensure that you have the current statuses of your payments before and after the collection date.
Alternatively, you could implement a Webhook for R-Transactions (see details of the Direct Debit R-Transaction Webhooks for more).
When working with our APIs, please use the Sandbox URI when testing and the Live URI when you move to Production.
LIVE https://api.nuapay.com SANDBOX https://sandbox.nuapay.com/
If you haven't done so already and would like to do some testing, please Request Sandbox Access
Important: Endpoints and Webhooks may be extended from time to time and any changes we make will follow our Versioning and Backward Compatibility rules. This means that the code that you write today must be designed to be robust enough to handle any future changes (where a new object is added to (or removed from) a specific API response, for example).
schemeId/ mandateId/ directDebitId in your requests and not the actual creditor scheme ID/SUN or Unique Mandate Reference or Direct Debit identifier. Resource identifiers are short alphanumeric strings, similar to this: abxq9kq52l. Depending on the request you may need 1, 2 or all 3 of these resource identifiers in your URI.