API Details
The Create Direct Debit request must:
- Include the resource identifier Creditor Scheme ID (CSID) or Service User Number (SUN) (see the List Creditor Scheme request)
- Reference an active mandate (its resource ID)
- A successful request will result in a Direct Debit being set up in
READY_FOR_EXPORT
status: the payment is created but has not yet been forwarded to SEPA Clearing or to Bacs Clearing for processing (see Direct Debit Statuses for more information).
Idempotency
The Idempotency check is only against successful requests, so where a previous call has resulted in any of the following HTTP Response Codes, that Idempotency key may be reused without any issue:
401
403
404
408
500
501
503
A Note on Payment References in the Bacs Scheme
When creating a Direct Debit against a Bacs DDI, please note:
- Your payment must include a reference that includes your DDI (the Core Reference). Note that the reference you provide:
- IMPORTANT! Must include the
mandateId
i.e. the DDI reference as its initial characters; so if your DDI Reference (mandateId
) isABCDEF123
then valid reference values would beABCDEF123-01
,ABCDEF12302
,ABCDEF123/456
, for example. If required you may simply always provide the same reference:ABCDEF123
. - Must be at least 6 alphanumeric characters in length and cannot exceed a total of 18 characters.
- Cannot begin with
DDIC
(this is reserved for PSP use). - Should only be composed of upper-case characters.
- IMPORTANT! Must include the
- If you don’t pass a reference, Nuapay will automatically generate one for you and store the DDI Reference as the
structuredRemittanceInformation.reference
. A uniqueendToEndId
is also generated. - If you you provide an
endToEndId
this will be saved as thestructuredRemittanceInformation.reference
subject to a duplicate check. - If an
endToEndId
and astructuredRemittanceInformation.reference
are provided in your request, thestructuredRemittanceInformation.reference
is used as the DDI (Core) Reference. - If you only provide a
structuredRemittanceInformation.reference
, Nuapay will generate anendToEndId
and thestructuredRemittanceInformation.reference
is used as the Core Reference. - The following non-alphanumeric characters are supported and may be used in the
endToEndId
identifier:- Full stop(.)
- Slash (/)
- Hyphen (-)
- Blank space ( )
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.