Create Payment

API Details

The Create Payment service:

• Generates an Open Banking payment object.
• Returns a unique paymentId with an (initial) status of PENDING (in Checkout and Redirect Mode) or PENDING_APPROVAL (in Self-Hosted and Self-Hosted-Callback modes).
• See PISP Implementation Options for more on the available modes.

Idempotency in Payment Requests

The Idempotency check is only against successful payments, so where a previous payment request 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

Remittance Reference

You have the option to provide your own remittance reference to your transactions (the default) or, if you would prefer, a unique system-generated remittance reference may be automatically applied. This reference unambiguously refers to the payment transaction.

If your configuration requires that merchant-generated references must be provided, please note that:

• For GB payments remittanceInformation.refererence must be a maximum of 18 characters
• For non-GB payments, 35 characters are allowed.

Payment identifiers have two attributes:

• The reference itself
• The reference’s time to live (default is 3 days)

Note that:

• The reference must be unique per merchant account within the defined time to live (default = 3 days).
• Where you reuse a reference, which was linked to a previously generated payment, and it is referenced within the time-to-live limit, your request will result in a:
  • 422 response: Duplicate Reference provided.

Supported Characters

Remittance can use the following characters:

• All alphanumeric characters (upper- and lower-case).
• A set of special characters.

The following are all allowed:

End-to-End Identifiers

If you want to provide an endToEndIdentification note that for:

• EUR currency transactions, the max length allowable is 35 characters.
• GBP currency transactions allow a max length of 31 characters.

The Debtor Account

Handling of the Debtor Account varies based on the Open Banking Scheme:

The /payments service allows you to provide the PSU account information (i.e. the debtorAccount) as an IBAN or as a Sort Code and Account number (for GB accounts).

The schemeName under the debtorAccountobject, can be provided in two ways, as:

• IBAN
• SortCodeAccountNumber

Where IBAN is used the PSU’s IBAN is provided for identification:

"debtorAccount": {
   "identification": "GB34BARC20051122334455",
   "schemeName": "IBAN"
}

Where SortCodeAccountNumber is used the Sort Code and Account number are concatenated and provided for identification.

Example: Sort Code = 12-34-56 & Account = 87654321 gives:

"debtorAccount": {
   "identification": "12345687654321",
   "schemeName": "SortCodeAccountNumber"
}

If you do not specify an account in this request, and assuming the PSU has more than one account, the ASPSP will typically allow the user to select any of his/her accounts for the payment, via a drop-down.

The Account Name

The debtorAccount name allows up to 70 characters but note:

• For FPS transactions, the maximum account name length is 35 characters. If you have used > 35 characters, the name will be truncated before sending to the Scheme.
• For SEPA transactions up to 70 characters may be provided.

Address Details

In STET:

• Certain STET ASPSPs require that you provide the debtor address in your payment request.
• It is also possible to pass the merchant (creditor) address in your request if required.
• If no creditor address details are provided, but are required for the selected ASPSP, the Nuapay TPP will pass the address stored against the merchant’s profile.

Setting an Execution Date

Use requestedExecutionDate if you want to specify a future-dated payment.

Note that:

• The payment must be initiated against a STET-supporting ASPSP.
• The payment can have a date up to 30 days into the future.
• The date cannot be in the past; if a past date is provided a T0058 error is triggered: “Requested Execution Date cannot be post cut-off time or in the past.”
• The Requested date specified may be a non-processing date (a holiday or weekend); the TPP does not validate this.
• Dates must be passed as YYYY-MM-DD.

Creditor Accounts

In some cases you might want to specify the creditor/beneficiary account (i.e. your merchant account) into which funds will be credited following a successful payment.

You can provide your creditor account information:

• As an IBAN

  OR

• as a Sort Code and Account number (for GB accounts in UK Open Banking).

To do this use the schemeName under the creditorAccountobject as one of the following:

• IBAN
• SortCodeAccountNumber

Where IBAN is used your creditor’s IBAN is provided for identification:

"creditorAccount": {
   "identification": "GB34BARC20051122334455",
   "schemeName": "IBAN"
}

Where SortCodeAccountNumber is used the Sort Code and Account number are concatenated and provided for identification.

Example: Sort Code = 12-34-56 & Account = 87654321 gives:

"creditorAccount": {
   "identification": "12345687654321",
   "schemeName": "SortCodeAccountNumber"
}

Note that:

For GB Payments:

1. The only allowed account country format is GB.
2. UK Faster Payments is the only allowed payment scheme.
3. The account format is sort code and account number.

For EUR payments:

1. IBAN is the only allowed account format.
2. SEPA Credit Transfer and SEPA Instant Credit Transfer are allowed payment schemes.
3. The Payment Scheme corresponds to the currently available Local Instrument/ Payment Type configuration at API level and ASPSP level. Merchant requests that contains a payment scheme that is different to the scheme set at the ASPSP level will be rejected.
4. Creditor Account IBAN/sortCodeAccountNumber validations in terms of account validity are the same as for debtorAccount.

Risk Object

For UK Open Banking, with the release of the OBIE Specification v3.1.10, the Risk object has been enhanced and includes the following Transaction Risk Indicators (TRIs).

What are TRIs and why are they needed?

• TRIs refer to particular payment payload fields included in the Risk section of the JSON object, which are passed to your payer’s bank.
• These risk indicators are then used by the target bank to enhance its security of payments for customers through the detection and prevention of fraud.
• In addition, the improved risk scoring can provide support for various banks’ vulnerable customers by allowing the implementation of gambling blocks on Open Banking payments, for example.

The following ‘paymentContextCode’ values are available in v3.1.10 of the OBIE specification:

• BillingGoodsAndServicesInAdvance
• BillingGoodsAndServicesInArrears
• PispPayee
• EcommerceMerchantInitiatedPayment
• FaceToFacePointOfSale
• TransferToSelf
• TransferToThirdParty

It is possible to:

• Manually provide any of these values in your payment request (in risk > paymentContextCode).
• Configure values that are automatically passed in all your requests. If all your payments fall under a specific payment context and merchant category then this is the better option. Discuss your requirements with your Account Manager.

The following matrix describes how the values for paymentContextCode and merchantCategoryCode are handled, whether they are provided in the API request or if they have been configured for your organisation:

Timeout Setting

It is possible to configure the timeout period for your payments. This is the time allowed from when the payment is initially created to when it is approved at the ASPSP.

The timeout period that is set for a given payment may be:

• Set in the API request
• If not provided in the API, it may be taken from your merchant configuration.
• If no default time has been configured for you then the global default time is used.

The following is the priority order for timeout configuration:

If you want to use a default custom timeout for all your payments, please contact your Account Manager.

To set the timeout in the API, set the required time value (in seconds) for paymentTimeout.

Multiple Authorisations

• In some cases a PSU may have an account that requires multiple authorisations to make a payment.
• In this case, the multiAuthorisation object is returned with details of the additional autorisations that are required.
• The payment will initially be in SETTLEMENT_PENDING
• As Nuapay TPP cannot determine when these additional authorisations are applied (the other authorising party or parties will typically authorise via their ASPSP’s banking portal), the system will continue to poll for a payment status update.
• The system will poll for the payment status and if the payment has expired (after 24 hours), but its status is not AUTHORISED or REJECTED, one attempt per day will be made to retrieve the final status.

A Note on Time Standards

Dates are formatted as ISO-8601 Date and Time in UTC (so daylight saving time is not observed).

So the creationDateTime returned in a 201 response, for example, would be formatted as follows:

A Note on Customer IP Address

For clients using SELF-HOSTED and SEL-HOSTED-CALLBACK integrations we recommend that you provide a value for Customer-IP-Address, when making EUR payments.

Failure to supply this value may result in a payment status of CONSENT_API_REJECTED, for payments processed at some EU banks.

Create Payment Endpoint

LIVE     https://api.nuapay.com/tpp
SANDBOX  https://sandbox.nuapay.com/tpp