My Nuapay Configuration
To get set up on the system:
- Contact our support team: api.support@nuapay.com
- Provide us with some basic details (your name, business area, etc.)
- We'll register you and send you the following:
- An API Key
- A test Creditor Scheme ID
- A test Merchant account
- A link to our testing environment
When you register for the service you will be assigned a Nuapay IBAN. This is a virtual account that you will use as your merchant account when processing mandates and Direct Debit payments.
When you make direct debit settlements the funds you collect are initially credited to this virtual IBAN. On the settlement date the funds are then debited from this account and credited to your physical (real-world account) via a Credit Transfer. This is automatically handled by Nuapay in the majority of cases but may be manually manged by you if required - please discuss the available options with you Account Manager.
Fees may be taken from each collection or you may opt to have your fees handled outside of the settlement cycle.
If you want fees to be taken from each settlement cycle, your credit would be calculated like this for a given settlement date:
- Credit (10 transactions): €100
- Rejects: €10
- Fee for Transaction: €1
- Fee for Reject: €2
- Credit Due on settlement date: €87
Alternatively fees may be charged separately and collected monthly. In this model your payments would be handled like this:
- Credit (10 transactions): €100
- Rejects: €10
- Credit Due on settlement date: €90
Your fees (€3) would then be charged to you separately with this amount being deducted from your nominated account on the 14th of the following month.
If you want to have your fees handled like this you will need to sign a mandate with Nuapay so that we can collect your fees via Direct Debit each month.
Mandates
If you have modified a mandate and altered key mandate details you may need to re-send it to your payer for authorisation; Nuapay will set the mandate to Pending automatically. If not dispatched for re-signature your payer could contest a debit from his/her account and argue that authorisation was never provided.
If you require that your mandate should remain in Active status you can set the mandateInfo.resendMandateForSignature flag to DO_NOT_SEND (see Update Mandate for more on this).
NOTE: If the mandate is currently in Pending status and you want to activate it, use Activate Mandate.
When you cancel a mandate all Direct Debit payments linked to that mandate are cancelled. The mandate cannot be reused. If you want to cancel all the payments in a fixed-length schedule but still be able to use the mandate later, use Revoke All Direct Debits.
Note: For an open-ended schedule this operation will only revoke the current READY FOR EXPORT payment, a new payment will be added automatically based on the payment frequency defined. For an open-ended schedule use the Cancel Payment Schedule service.
When a mandate is suspended all its linked Direct Debits are put into cancelled status. Unlike a cancel operation, a mandate that is suspended may be re-activated later.
Note: It is not currently possible to suspend a mandate via the API but this can be done via the Nuapay user interface.
Bacs DDIs go into READY_FOR_EXPORT status initially. Once passed to the AUDDIS service a DDi moves to EXPORTED and provided it is not returned by the service, it goes to ACTIVE status on Day 3 of the lodgement cycle.
Note: It is not currently possible to suspend a mandate via the API but this can be done via the Nuapay user interface.
Direct Debit Payments
The collection date (also referred to as the Settlement Date and the Value Date) is the date on which funds are debited from your payers' bank account and credited to your Nuapay account and (optionally - see the note below) credited from there to your external, non-Nuapay bank account.
Note: If you are configured as a Self-Managed originator then you control when funds are moved from your Nuapay account; your funds stay on your account until you initiate a funds transfer either via the API or via the Nuapay User Interface. If you are not Self-Managed then your settlement amount is automatically swept to your external account on the collection date.
Direct Debit payments are initially created in READY FOR EXPORT status. They move to EXPORTED and then to ACCEPTED, if all goes well. If the transactions is rejected (either before the settlement date or after the settlement date ) then the status may be updated to REJECTED, REFUSED, RETURNED, etc. See Direct Debit Statuses for more on this
A re-presentation lets you re-try to settle a Direct Debit payment that has been rejected. When you re-present a payment (see Re-present Failed Direct Debits) the original failed Direct Debit's status is updated to REPRESENTED; this payment is no longer used at this point.
A new payment (in READY FOR EXPORT status) is created that attempts to collect the original payment.
Direct Debit payments are typically exported 2 days before the collection date. From this point onward debtor banks will begin to process the transactions and you will begin to see a certain portion of payments being rejected.
The List Failed Direct Debits call allows you to track the status of all your failed payments and allows you to manage how best to handle them (you may need to re-present a payment or you may need to contact your payer if an incorrect IBAN has been provided, for example)
As per the SEPA standard for Direct Debit processing, payments must be grouped into a standardised ISO format XML file. The standard XLS file this is the PAIN.008.001.02 file (generally referred to as a PAIN.008 or Pain8). This format is used in the Customer-to-Bank space.
Prior to their settlement date, all Direct Debit payments are then grouped into PACS.003 files, used in the Bank-to-Bank space, and passed on to Clearing and from there out to all your payers' banks for further processing.
For security reasons our APIs use a unique identifier to reference Nuapay objects (mandates, Direct Debits, Creditor Schemes, etc.). These may be referred to as encoded IDs in some code snippets.
Failed Payments (R-Transactions)
A Reject is received before the settlement date; a Return is received after the settlement date. When your Nuapay settlement is calculated your gross credit will be debited by the value of any pre-settlement rejects that have been processed. Any Return transactions that are processed after the settlement date will be debited against your next collection.
AUTHORISED: In the case of an authorised refund the payer has claimed a refund for a transaction within an 8 week period of the initial debit on his/her account. The payer must be credited - you as a merchant cannot contest this, as per the SEPA CORE scheme rules.
UNAUTHORISED: An unauthorised refund can occur after 8 weeks and within 13 months of the debit. In this scenario the payer's bank will lodge a request with your bank to provide proof of a mandate. Your bank will seek this proof from you and pass it to the payer's bank. If the payer's bank is satisfied that the mandate is valid then they will not seek to debit your account for the refund amount. If the mandate is not provided or the payer's bank deem that no mandate (and payer authorisation) was in place they will initiate a debit on your account to credit your payer's account.
A REFUSAL is a pre-settlement R-transaction. A payer may refuse your direct debit based on specific settings that they may have applied to their bank account. For example the payer may have set a limit on the value of collections that may be debited in a single transaction. If your debit exceeds this limit then this will result in a REFUSAL (typically an MS02 - see SEPA Error Codes for more information)
It is possible to re-present any failed payment but we recommend that you only attempt to re-present failed payments with error code AM04 and MS03.
See Re-present Failed Direct Debits for more details.
Technical rejects refer to transactions that fail for business validation reason when imported via file upload only.
When interacting with Nuapay via the API you will not receive technical rejects.
Webhooks
You can configure your Webhook notifications to retry for a period of time e.g. for 1 day. Notifications that fail to be delivered will be retried every 30 minutes until successful or until the configured retry period is reached.
Yes it is possible to receive notification out of sequence however every notification includes an eventTimestamp (a Unix Epoch value), which will allow you to determine the correct ordering of notifications.
Use the Retrieve Payment endpoint to determine the status of any given payment.
Webhook messages are always dispatched individually.
Nuapay will timeout after 10 seconds if the receiving endpoint has not responded.
Technical
This error is generally related to you application's default security protocol type being set too low. We recommend TLS 1.2 or above. Check out codeshare.co.uk for more information on how to reolve this.