When creating mandates/DDIs, please note that:
- Mandates/DDIs must be created under a specific scheme (e.g. the SEPA CORE or Bacs scheme) and must also be linked to a Creditor Scheme ID (CSID) in SEPA or a Service User Number (SUN) for Bacs.
- To determine your CSID/SUN use the List Scheme service.
- Depending on the configuration of your Creditor Scheme your mandates/DDI will be created in a specific status.
- Regardless of the scheme, Direct Debit payments can only be created against an ACTIVE mandate/DDI.
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:
A Note on the Mandate Identifier in the Bacs Scheme
A unique mandate (DDI) identifier (also known as the Core Reference in Bacs), the
mandateId is applied automatically when you call the Create Mandate/DDI endpoint.
If required you may also specify this identifier in your request.
If you want to assign your own
mandateId when adding a mandate/DDI against the Bacs scheme, please note:
mandateIdmust > 6 alphanumeric characters. ABC-12-3 for example would be evaluated as having a length = 6 characters (ABC123; the Hyphens are not included in the character count).
- The total length of the
mandateIdcannot exceed 18 characters.
- It cannot consist of all the same characters e.g. all zeros.
- It must be unique for the sort code, account number and SUN.
- The following non-alphanumeric characters are supported and may be used in the identifier:
- Full stop(.)
- Slash (/)
- Hyphen (-)
- Blank space ( )
- It cannot begin with the letters DDIC.
The DDI Reference and End-to-End Identifiers in Bacs
Later when you create a Direct Debit payment against your DDI, in the Bacs scheme, the transaction will use the DDI reference (
mandateId) as its starting code.
So for a mandate/DDI =
ABCDEF123, its linked transactions could have identifiers as follows:
For this reason we recommend that your
mandateId should not use all 18 characters as this will mean that reconciling individual transactions later will be made more difficult (as in this case all transactions would have the same
mandateId; your DDI reference will be correctly formatted and you can be confident that your reference will not be in breach of any Bacs guidelines, which could potentially result in failed payments later.
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).
schemeIdin your request and not the actual creditor scheme ID or SUN. This identifier will be similar to this: abxq9kq52l - so in this case you would call POST /schemes/abxq9kq52l/mandates. See List Schemes for more on this.