NAV
bash java

Introduction

Welcome to the Nuapay REST API. Processing Direct Debits (DDs) or Credit Transfers (CTs) via API is a simple way to integrate these payment methods into your systems. This API reference provides information on available endpoints and how to interact with them.

For Direct Debits once you have been configured with a Creditor Scheme ID just add the mandate, add the Direct Debit or Direct Debit Schedule and watch your payments come in. If you’re new to Direct Debits refer to our Developer Documentation for an overview of the Direct Debit process.

For Credit Transfers, add the Beneficiary then add the Credit Transfer and your payment is sent out. If you’re new to Credit Transfers refer to this Credit Transfer Payments Overview.

Getting Started

To register for the service and get your API key, visit https://www.nuapay.com/request-api-sandbox/ or e-mail: api.support@nuapay.com

If you prefer to talk to someone, call 00353 (0)1 901 2398.

We'll have you up and running in no time.

API Endpoints

Once you have your API key, you can send requests to the following endpoints:

Live: https://api.nuapay.com

UAT: https://sandbox.nuapay.com/

Our APIs are RESTful and we use JSON format for submitting and retrieving data.

To view all available Nuapay REST endpoints, see the Resources sections below.

Security

Authentication

To authorize, use this code:

# With curl, you can just pass BASIC auth header 
# (-u option) with each request
$ curl 'https://api.nuapay.com/schemes/46pkx7o9n5/mandates' 
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686:
// With java client library use following code to set up your ApiKey
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

RetrieveMandateResponse retrieveMandateResponse = 
    new MandateServiceDefault(serviceConfig)
        .retrieveMandate("46pkx7o9n5", "46pkx7o9n5");

Make sure to replace bb09c2b6a... with your API key.

Access to the API is controlled by HTTP Basic authentication.

Provide your API key as the basic authentication username, encoded in Base64. No password needs to be provided, however the request must be made from an allowed IP address configured in Nuapay.

API authentication header format:

Authorization: Basic Base64(<API_Key>:)

All API requests must be made over HTTPS, calls made over plain HTTP will fail. All API requests must be authenticated.

Output Encoding Rules

The code converts untrusted input into a safe form where the input is displayed as data to the user without executing as code in the browser.

The implementation is based off the OWASP recommendations.

JWS-Signature Header

Example JWS-Signature Header


JWS-Signature: eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCIsImlhdCIsImlzcyJdLCJraWQiOiIxNzk2NDU1MDI1IiwiaXNzIjoiT1VcdTAwM2ROdWFwYXkgQVBJLExcdTAwM2RMb25kb24sT1x1MDAzZE51YXBheSxDXHUwMDNkR0IsQ05cdTAwM2RvbWdkMzZkcG1rIiwiYWxnIjoiUlMyNTYiLCJpYXQiOjB9..wE6Cal9Hh62YKjjD4BbQpdPc1IwtteZ-ys3aiOWJDVLFdVxnJ0pEvcsK1nfRnfiiqCOB9PbapNrpG1e3jdWA3y-bm0KphLE52PEwhWZkD-x3WeFyxAeZT_Ma7Fem08k31ifMLMPYkXAyUDUfCao4DHJQHmOWQuDawYC4lH4qtiI

The JWS-signature header is used to verify requests made to certain endpoints, it is generated based on the request body to be sent, a customer private key and X.509 certificate issued by Nuapay.

For details on how to generate a private key and obtaining an X.509 certificate see the security section of the Developer Resource pages.

The JWS-signature is required when using the following POST / PUT endpoints,

Optionally the JWS-signature can also be applied to the following POST / PUT endpoints,

The JWS-signature is not required for GET endpoints.

Resources

Returned Resources

Example response with single entity


{
  "uri" : "/files/23qzxn1f7m",
  "data" : {
    "id" : "23qzxn1f7m",
    "uri" : "/files/23qzxn1f7m",
    "originalFileName": "originalFileName.xml",
    "newFileName": "newFileName.xml.QUEUED"
  }
}

Example response with collection


{
  "uri" : "/schemes/8g3o2yyk2w/mandates",
  "data" : [ {
    "id" : "46pkxn8e9n",
    "uri" : "/schemes/8g3o2yyk2w/mandates/46pkxn8e9n",
    "mandateId" : "b8b7ee91-b403-4ecb-9d98-059746dd8149",
    "debtorName" : "Debtor Name",
    "debtorIBAN" : "GB94SELN00999976543215",
    "debtorMobileNumber" : "0360321312312",
    "mandateStatus" : "ACTIVE",
    "creationDate" : "2015-07-21"
  } 
  ],
  "page" : {
    "pageNumber" : 1,
    "pageSize" : 1,
    "totalElements" : 1,
    "totalPages" : 1
  },
  "sort" : [ ]
}

All resources returned by endpoints are contained within a resource envelope.

For single entities, the JSON envelope has the following structure:

JSON Path Type Description
uri String Resource URI
data.id String Resource ID
data.uri String Resource URI
data.* Resource content

For collections, the JSON envelope contains the following structure:

JSON Path Type Description
uri String Collection resource URI
data Collection Collection of resources
data[].id String Resource ID
data[].uri String Resource URI
data[].* Resource content
data.page Pagination object Meta-data related to pagination
data.sort Sort object Meta-data related to sorting (currently empty)

Resource IDs

The ID is part of resource URI and in this documentation is marked as such by placing it between curly brackets. Sample scheme resource URI is /schemes/{schemeId}/mandates/{mandateId} where schemeId and mandateId are the Scheme and Mandate Resource IDs accordingly.

Returned Resources data[].id element contains the Resource ID. In above example Mandate Resource needs to be retrieved to get the mandateId and Creditor Scheme Resource needs to be retrieved to get schemeId.

Example Link array,

{
  "links": [
    {
      "resourceType": "balances",
      "id": null,
      "uri": "/accounts/cdxt17zj1l/balances"
    },
    {
      "resourceType": "beneficiary",
      "id": "j29pkqiaby",
      "uri": "/beneficiaries/j29pkqiaby"
    }      
  ]
}

'Links' referrs to an array that can appear in the endpoint response contaning the ID and URI of linked resources.

Where no linked resources exists the 'Links' will be presented as an empty array.

The link array has the following structure:

JSON Path Type Description
links.resourceType Stringenum The type of the linked resource, relevant types will be defined in the endpoint object(s)
links.id String ID of the linked resource
links.uri String URI of the linked resource

Direct Debits APIs

This section contains descriptions of APIs to allow for management of Direct Debits.

Creditor Schemes

The Creditor Schemes associated to the Merchant. Each scheme will have a unique Creditor Scheme ID and a Scheme Type, CORE, B2B etc.

Creditor Scheme Object

Example JSON structure describing the Creditor Scheme

{
   "creditorSchemeId": "1",
   "schemeType": "CORE"
}
Parameter Type Description
creditorSchemeId String Creditor Scheme ID
schemeType String Scheme Type

List Creditor Schemes

Example request

$ curl 'https://api.nuapay.com/schemes'
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686:
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

List<CreditorSchemeResource> creditorSchemes = 
    new CreditorSchemeServiceDefault(serviceConfig)
        .listCreditorSchemes().getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/schemes",
  "data": [
    {
      "id": "abxq9kq52l",
      "uri": "/schemes/abxq9kq52l",
      "creditorSchemeId": "BE31ZZZ12345",
      "schemeType": "CORE"
    }
  ]
}

A GET request is used to retrieve a collection of Creditor Schemes.

Definition

GET /schemes

Returns

Returns 200 OK response code and JSON structure representing a collection of Creditor Scheme objects.

In case of failure, an error is returned within the error structure (see Errors section).

Mandates

Mandates are associated to a Creditor Scheme (CORE or B2B) and enable the collection of funds from a debtor’s account to a creditor’s account via a Direct Debit.

To access a mandate use the following URL:

https://api.nuapay.com/schemes/{CS_ID}/mandates/{MANDATE_ID}

where

Mandate Object

Example JSON structure describing a mandate

{
    "debtor" : {
      "name" : "Debtor Name",
      "address" : {
        "line1" : "Debtor Address Line1",
        "line2" : "Debtor Address Line2",
        "town" : " Debtor Town",
        "postCode" : "123123",
        "state" : "Debtor State",
        "country" : "IE"
      },
      "language" : "fr_BE",
      "email" : "debtor@email.com",
      "phoneNumber" : "0360123123123",
      "mobileNumber" : "0360321312312"
    },
    "mandateInfo" : {
      "mandateId" : "1234567899",
      "contractReference" : "Contract Reference",
      "signatureLocation" : "Signature Location",
      "signatureDate" : "2015-07-21",
      "electronicSignatureDetails": {
        "authorizationMethod": "SMS_PASSWORD",
        "authorizationToken": "1234",
        "authorizationEmail": "debtor@email.com",
        "authorizationMobileNumber": "0360321312312",
        "ipAddress": "192.168.8.1",
        "geographicLocation": "Geo Location"
      },
      "mandateType" : "RCUR",
      "status" : "PENDING",
      "creationDate" : "2015-07-21"
    },
    "debtorAccount" : {
      "iban" : "GB94SELN00999976543215",
      "bic" : "SELNGB21"
    },
    "creditorAccount" : {
      "iban" : "GB47SELN00999912345678",
      "bic" : "SELNGB21"
    }
}
Path Type Description
debtor.namerequired Stringmax 70 chars Debtor Name
debtor.address.line1optional Stringmax 70 chars Debtor Address Line 1
debtor.address.line2optional Stringmax 70 chars Debtor Address Line 2
debtor.address.townoptional Stringmax 70 chars Debtor Address City/Town
debtor.address.postCodeoptional Stringmax 16 chars Debtor Address Post Code
debtor.address.stateoptional Stringmax 70 chars Debtor Address State/Province/County
debtor.address.countryoptional Stringenum ISO 3166-1 alpha-2 code
debtor.languageoptional Stringenum Communication language. One of (en, pt, nl, fr, it, es, de, sk, fr_BE, nl_BE)
debtor.emailoptional Stringmax 254 chars Debtor Email Address
debtor.phoneNumberoptional Stringmax 30 chars Debtor Phone Number
debtor.mobileNumberoptional Stringmax 30 chars Debtor Mobile Phone
mandateInfo.contractReferenceoptional Dateyyyy-mm-dd Contract Reference
mandateInfo.signatureLocationoptional Dateyyyy-mm-dd Response parameter only. Signature Location
mandateInfo.signatureDateoptional Dateyyyy-mm-dd Response parameter only. Signature Date
mandateInfo.electronicSignatureDetails.authorizationMethodoptional Stringenum Possible values: CHECK_BOX, SMS_PASSWORD, EMAIL_PASSWORD
mandateInfo.electronicSignatureDetails.authorizationTokenoptional Stringmax 35 chars Authentication Token (OTP)
mandateInfo.electronicSignatureDetails.authorizationEmailoptional Stringmax 254 chars Authentication Email Address
mandateInfo.electronicSignatureDetails.authorizationMobileNumberoptional Stringmax 30 chars Authentication Phone Number
mandateInfo.electronicSignatureDetails.ipAddressoptional String max 39 chars Authentication IP Address
mandateInfo.electronicSignatureDetails.geographicLocationoptional String max 70 chars Authentication Geographic Location
mandateInfo.mandateTypeoptional Stringenum Either OOFF or RCUR
mandateInfo.status Stringenum Response parameter only. One of possible mandate statuses (ACTIVE, CANCELLED, COMPLETE, PENDING, UNREADABLE, UNSIGNED, SCREENING, SUSPENDED, READY_FOR_EXPORT, EXPORTED)
mandateInfo.creationDate Dateyyyy-mm-dd Response parameter only. Date when the mandate was created
debtorAccount.ibanrequired Stringmax 34 chars Debtor Account IBAN
debtorAccount.bicoptional Stringmax 11 chars Debtor Account BIC
creditorAccount.ibanrequired Stringmax 34 chars Creditor Account IBAN
creditorAccount.bicoptional Stringmax 11 chars Creditor Account BIC

Mandate List Object

Example JSON structure describing a list mandate object

{
    "mandateId" : "BEL000049995012C",
    "debtorName" : "Debtor Name",
    "debtorIBAN" : "GB94SELN00999976543215",
    "debtorMobileNumber" : "0360321312312",
    "mandateStatus" : "ACTIVE",
    "creationDate" : "2015-07-21"
  }
Path Type Description
mandateId Stringmax 35 chars Mandate Reference (UMR)
debtorName Stringmax 70 chars Debtor Name
debtorIBAN Stringmax 34 chars Debtor Account IBAN
debtorMobileNumber Stringmax 30 chars Debtor Mobile Phone
mandateStatus Stringenum One of the possible mandate statuses (ACTIVE, CANCELLED, COMPLETE, PENDING, UNREADABLE, UNSIGNED, SCREENING, SUSPENDED, READY_FOR_EXPORT, EXPORTED)
creationDate Dateyyyy-mm-dd Date when the mandate was created

Create Mandate

Example request

$ curl 'https://api.nuapay.com/schemes/abxq9d8v2l/mandates' -i \
  -u 9bede398fb43c9b8658c476fb85f5ba3cb430b309c1d82262f1a2a5d70a88b5d: \
  -X POST -H 'Content-Type: application/json' -d \
   '{
     "debtor": {
     "name": "Debtor Name", 
     "address": { 
       "line1": "Debtor Address Line1", 
       "line2": "Debtor Address Line2", 
       "town": "Debtor Town", 
       "postCode": "123123", 
       "state": "Debtor State", 
       "country": "IE" 
      }, 
     "language": "en", 
     "email": "debtor@email.com", 
     "phoneNumber": "0360123123123", 
     "mobileNumber": "0360321312312" 
     }, 
     "mandateInfo": { 
       "mandateId": "tstMndtAA987", 
       "contractReference": "Contract Reference", 
       "signatureLocation": "Signature Location", 
       "signatureDate": "2015-07-21", 
       "electronicSignatureDetails": { 
         "authorizationMethod": "SMS_PASSWORD", 
         "authorizationToken": "1234", 
         "authorizationEmail": "debtor@email.com", 
         "authorizationMobileNumber": "0360321312312", 
         "ipAddress": "192.168.8.1", 
         "geographicLocation": "Geo Location" 
       }, 
       "mandateType": "RCUR" 
     }, 
     "debtorAccount": { 
       "iban": "GB94SELN00999976543215", 
       "bic": "SELNGB21" 
     }, 
     "creditorAccount": { 
       "iban": "GB47SELN00999912345678", 
       "bic": "SELNGB21" 
     } 
   }'
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

CreateMandateRequest createMandateRequest = 
        new CreateMandateRequest()
            .withMandate(
                new Mandate()
                    .withDebtor(
                            new Debtor()
                                .withName("Debtor Name")
                                .withAddress(
                                        new Address()
                                            .withLine1("Debtor Address Line1")
                                            .withLine2("Debtor Address Line2")
                                            .withTown("Debtor Town")
                                            .withPostCode("123123")
                                            .withState("Debtor State")
                                            .withCountry("IE")
                                        )
                                .withLanguage("fr_BE")
                                .withEmail("debtor@email.com")
                                .withPhoneNumber("0360123123123")
                                .withMobileNumber("0360321312312")
                                )
                    .withMandateInfo(
                            new MandateInfo()
                                .withMandateId("1234567899")
                                .withContractReference("Contract Reference")
                                .withSignatureLocation("Signature Location")
                                .withSignatureDate(DateUtils.toDate("2015-07-21"))
                                .withMandateType(MandateType.RCUR)
                                )
                    .withDebtorAccount(
                            new BasicAccount()
                                .withIban("GB94SELN00999976543215")
                            )
                    .withCreditorAccount(
                            new BasicAccount()
                                .withIban("GB47SELN00999912345678")
                            )
                );

MandateResource mandateResource = 
    new MandateServiceDefault(serviceConfig)
        .createMandate("46pkx7o9n5", createMandateRequest)
        .getData();

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{  
  "uri":"/schemes/abxq9d8v2l/mandates/abxqj8892l",
  "data":{  
    "id":"abxqj8892l",
    "uri":"/schemes/abxq9d8v2l/mandates/abxqj8892l",
      "debtor":{  
        "name":"JoeDoe",
        "address":{  
          "line1":"L1",
          "line2":"L2",
          "town":"T1",
          "postCode":"123123",
          "state":"S1",
          "country":"IE"
        },
        "language":"en",
        "email":"debtor@email.com",
        "phoneNumber":"0360123123123",
        "mobileNumber":"0360321312312"
      },
      "debtorAccount":{  
        "iban":"GB47SELN00999912345678",
        "bic":"SELNGB21"
      },
      "creditorAccount":{  
        "iban":"IE72TURU99100404712507",
        "bic":"TURUIE21"
      },
      "mandateInfo":{  
        "mandateId":"tstMndtAA987",
        "contractReference":"Contract Reference",
        "signatureLocation":"Signature Location",
        "signatureDate":"2015-07-21",
        "mandateType":"RCUR",
        "electronicSignatureDetails":{  
          "authorizationMethod":"SMS_PASSWORD",
          "authorizationToken":"1234",
          "authorizationEmail":"debtor@email.com",
          "authorizationMobileNumber":"0360321312312",
          "ipAddress":"192.168.8.1",
          "geographicLocation":"Geo Location"
        },
        "status":"ACTIVE",
        "creationDate":"2018-06-18"
      },
      "links":[ ]
   }
}

A POST request is used to create mandates. The request must contain the application/json content type. In the request body you must provide a JSON structure describing the Mandate.

The request can be run in 'Validate' mode, for the case of eMandates flow. In such case 'x-request-mode' = 'validate' header is provided. If provided, then 'Validation' mode logic is triggered, mandate is not created in the call.

Definition

POST /schemes/{CS_ID}/mandates

Arguments

JSON Path Type Description
rootrequired Mandate JSON structure describing a mandate (See Mandate Object section)

Returns

Returns 201 Created response code, a URI to the created resource and a JSON structure representing the created resource.

In case of failure, an error is returned within the error structure (see Errors section).

Retrieve Mandate

Example request

$ curl 'https://api.nuapay.com/schemes/46pkx7o9n5/mandates/w24y3dya2p' 
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686:
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

MandateResource mandateResource = 
    new MandateServiceDefault(serviceConfig)
        .retrieveMandate("46pkx7o9n5", "46pkx7o9n5")
        .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri" : "/schemes/46pkx7o9n5/mandates/w24y3dya2p",
  "data" : {
    "id" : "w24y3dya2p",
    "uri" : "/schemes/46pkx7o9n5/mandates/w24y3dya2p",
    "debtor" : {
      "name" : "Debtor Name",
      "address" : {
        "line1" : "Debtor Address Line1",
        "line2" : "Debtor Address Line2",
        "town" : " Debtor Town",
        "postCode" : "123123",
        "state" : "Debtor State",
        "country" : "IE"
      },
      "language" : "fr_BE",
      "email" : "debtor@email.com",
      "phoneNumber" : "0360123123123",
      "mobileNumber" : "0360321312312"
    },
    "mandateInfo" : {
      "mandateId" : "1234567899",
      "contractReference" : "Contract Reference",
      "signatureLocation" : "Signature Location",
      "signatureDate" : "2015-07-21",
      "mandateType" : "RCUR",
      "status" : "PENDING",
      "creationDate" : "2015-07-21"
    },
    "debtorAccount" : {
      "iban" : "GB94SELN00999976543215",
      "bic" : "SELNGB21"
    },
    "creditorAccount" : {
      "iban" : "GB47SELN00999912345678",
      "bic" : "SELNGB21"
    }
  }
}

A GET request is used to retrieve mandate.

Definition

GET /schemes/{CS_ID}/mandates/{MANDATE_ID}

Returns

Returns 200 OK response code and a JSON structure representing the queried mandate resource.

In case of failure, an error is returned within the error structure (see Errors section).

Retrieve Mandate Document

Example request

$ curl 'https://api.nuapay.com/schemes/46pkx7o9n5/mandates/w24y3dya2p/document' 
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686:
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

byte[] image = new MandateServiceDefault(serviceConfig)
                    .retrieveMandateDocument("46pkx7o9n5", "46pkx7o9n5");

Example response

HTTP/1.1 200 OK
Content-Type: application/pdf
<<<<pdf-content>>>>

A GET request is used to retrieve a mandate PDF, JPEG or GIF file.

Definition

GET /schemes/{CS_ID}/mandates/{MANDATE_ID}/document

Returns

Returns 200 OK response code and a PDF, JPEG or GIF file as response content.

In case of failure, an error is returned within the error structure (see Errors section).

Upload Mandate Document

Example request

$ curl 'https://api.nuapay.com/schemes/w24y3dya2p/mandates/abxq9kq52l/document' -X POST \ 
  -u e8fe452a46e8ccb2fa72d8c91e2228d6ce41e652bce32dc63dd29f184cbca82e: \ 
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@Mandate-file.pdf;type=application/pdf'
  -F \
  'json={
    "fileName":"Mandate.pdf"
    };type=application/json'
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("7394645c6830a2732f9c90500841e18023e08c52ac9f879b62520564ccd29807");

byte[] fileContent = ...

MandateResource mandateResource = 
    new MandateServiceDefault(serviceConfig)
        .updateMandateDocument(
            "w24y3dya2p", "abxq9kq52l", 
            new UpdateMandateDocumentRequest().withFileName("mandate123.pdf"), 
            fileContent)
        .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p",
  "data": {
    "id": "w24y3dya2p",
    "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p"
  }
}

A POST request used to upload a mandate image in PDF, GIF or JPEG format. A request must contain the multipart/form-data content type with a json part containing input parameters in a JSON structure, a file part with file content and a 'file content type'. Note that if json part is not provided file part will be used to derive file name.

Accepted file content types:

Definition

POST /schemes/{CS_ID}/mandates/{MANDATE_ID}/document

Arguments

JSON Path Type Description
fileNameoptional Stringmax 39 chars Specifies the image file name, if not provided uses the name of the uploaded file

Returns

Returns 200 OK response code.

In case of failure, an error is returned within the error structure (see Errors section).

List Mandates

Example request

$ curl 'https://api.nuapay.com/schemes/46pkx7o9n5/mandates/?debtoriban=GB94SELN00999976543215&debtorname=Debtor&createdatefrom=2015-07-01&createdateto=2015-07-06&mandateid=BEL000049995012C&mandatestatus=ACTIVE&mandatestatus=PENDING' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

ListMandatesRequestParameters listMandatesRequestParameters = 
    new ListMandatesRequestParameters()
        .withDebtorIban("GB94SELN00999976543215")
        .withDebtorName("Debtor")
        .withCreateDateFrom(DateUtils.toDate("2015-07-29"))
        .withCreateDateTo(DateUtils.toDate("2015-07-29"))
        .withMandateId("BEL000049995012C")
        .withMandateStatus(MandateStatus.ACTIVE);

List<MandateSummaryResource> mandateSummaryList = 
    new MandateServiceDefault(serviceConfig)
        .listMandates("46pkx7o9n5", listMandatesRequestParameters)
        .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri" : "/schemes/46pkx7o9n5/mandates",
  "data" : [ {
    "id" : "46pkxn8e9n",
    "uri" : "/schemes/8g3o2yyk2w/mandates/46pkxn8e9n",
    "mandateId" : "BEL000049995012C",
    "debtorName" : "Debtor Name",
    "debtorIBAN" : "GB94SELN00999976543215",
    "debtorMobileNumber" : "0360321312312",
    "mandateStatus" : "PENDING",
    "creationDate" : "2015-07-21"
  }, {
    "id" : "nx9kndaejm",
    "uri" : "/schemes/8g3o2yyk2w/mandates/nx9kndaejm",
    "mandateId" : "BEL000049995012S",
    "debtorName" : "Debtor Name",
    "debtorIBAN" : "GB94SELN00999976543215",
    "debtorMobileNumber" : "0360321312312",
    "mandateStatus" : "ACTIVE",
    "creationDate" : "2015-07-21"
  }, {
    "id" : "vw7kj9gey5",
    "uri" : "/schemes/8g3o2yyk2w/mandates/vw7kj9gey5",
    "mandateId" : "BEL000049995012X",
    "debtorName" : "Debtor Name",
    "debtorIBAN" : "GB94SELN00999976543215",
    "debtorMobileNumber" : "0360321312312",
    "mandateStatus" : "ACTIVE",
    "creationDate" : "2015-07-21"
  } ],
  "page" : {
    "pageNumber" : 1,
    "pageSize" : 20,
    "totalElements" : 3,
    "totalPages" : 1
  },
  "sort" : [ ]
}

A GET request is used to retrieve a collection of mandates. Can return mandates associated to the Creditor Scheme and organization.

Definition

To return mandates for a particular Creditor Scheme, use

GET /schemes/{CS_ID}/mandates

To return all mandates for an organization, use

GET /mandates

Arguments

Request parameter Description
debtoriban optional Debtor IBAN
debtorname optional Debtor Name
createdatefrom optional Format yyyy-mm-dd.
createdateto optional Format yyyy-mm-dd.
mandateid optional Mandate UMR
mandatestatus optional One of possible mandate statuses (ACTIVE, CANCELLED, COMPLETE, PENDING, UNREADABLE, UNSIGNED, SCREENING, SUSPENDED, READY_FOR_EXPORT, EXPORTED). Note number of statuses can be queried within single request by providing multiple occurance of the parameter.

Returns

Returns 200 OK response code and a JSON structure representing a collection of List mandate objects.

In case of failure, an error is returned within the error structure (see Errors section).

Update Mandate

Example request

$ curl 'https://api.nuapay.com/schemes/46pkx7o9n5/mandates/ne8y69wwpo' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X PUT -H 'Content-Type: application/json' -d  \
  '{
    "debtor" : {
      "name" : "Debtor Name",
      "address" : {
        "line1" : "Debtor Address Line1",
        "line2" : "Debtor Address Line2",
        "town" : " Debtor Town",
        "postCode" : "123123",
        "state" : "Debtor State",
        "country" : "IE"
      },
      "language" : "fr_BE",
      "email" : "debtor@email.com",
      "phoneNumber" : "0360123123123",
      "mobileNumber" : "0360321312312"
    },
    "mandateInfo" : {
      "mandateId" : "1234567899",
      "contractReference" : "Contract Reference",
      "signatureLocation" : "Signature Location",
      "signatureDate" : "2015-07-21",
      "mandateType" : "RCUR"
    },
    "debtorAccount" : {
      "iban" : "GB94SELN00999976543215",
      "bic" : "SELNGB21"
    },
    "creditorAccount" : {
      "iban" : "GB47SELN00999912345678",
      "bic" : "SELNGB21"
    }
    }'
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

UpdateMandateRequest updateMandateRequest = 
        new UpdateMandateRequest()
        .withMandate(
                new Mandate()
                .withDebtor(
                        new Debtor()
                        .withName("Debtor Name")
                        .withAddress(
                                new Address()
                                .withLine1("Debtor Address Line1")
                                .withLine2("Debtor Address Line2")
                                .withTown("Debtor Town")
                                .withPostCode("123123")
                                .withState("Debtor State")
                                .withCountry("IE")
                                )
                        .withLanguage("fr_BE")
                        .withEmail("debtor@email.com")
                        .withPhoneNumber("0360123123123")
                        .withMobileNumber("0360321312312")
                        )
                .withMandateInfo(
                        new MandateInfo()
                        .withMandateId("1234567899")
                        .withContractReference("Contract Reference")
                        .withSignatureLocation("Signature Location")
                        .withSignatureDate(DateUtils.toDate("2015-07-21"))
                        .withMandateType(MandateType.RCUR)
                        )
                .withDebtorAccount(
                        new BasicAccount()
                        .withIban("GB94SELN00999976543215")
                        .withBic("SELNGB21")
                        )
                .withCreditorAccount(
                        new BasicAccount()
                        .withIban("GB47SELN00999912345678")
                        .withBic("SELNGB21")
                        )
                )
        .withResendMandateForSignature(ResendMandateForSignature.DEFAULT);

MandateResource mandateResource = 
    new MandateServiceDefault(serviceConfig)
        .updateMandate("46pkx7o9n5", "ne8y69wwpo", updateMandateRequest)
        .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p",
  "data": {
    "id": "w24y3dya2p",
    "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p",
     "debtor" : {
      "name" : "Debtor Name",
      "address" : {
        "line1" : "Debtor Address Line1",
        "line2" : "Debtor Address Line2",
        "town" : " Debtor Town",
        "postCode" : "123123",
        "state" : "Debtor State",
        "country" : "IE"
      },
      "language" : "fr_BE",
      "email" : "debtor@email.com",
      "phoneNumber" : "0360123123123",
      "mobileNumber" : "0360321312312"
    },
    "mandateInfo" : {
      "mandateId" : "1234567899",
      "contractReference" : "Contract Reference",
      "signatureLocation" : "Signature Location",
      "signatureDate" : "2015-07-21",
      "mandateType" : "RCUR",
      "status" : "PENDING",
      "creationDate" : "2015-07-21"
    },
    "debtorAccount" : {
      "iban" : "GB94SELN00999976543215",
      "bic" : "SELNGB21"
    },
    "creditorAccount" : {
      "iban" : "GB47SELN00999912345678",
      "bic" : "SELNGB21"
    }
  }
}

A PUT request used to update mandates. The request must contain the application/json content type. In the request body you must provide a JSON structure describing the Mandate.

NOTE: Where an optional JSON object property is not provided it is treated as null. Where an existing resource representation contains a value under that property it will get overwritten.

Definition

PUT /schemes/{CS_ID}/mandates/{MANDATE_ID}

Arguments

JSON Path Type Description
root required Mandate JSON structure describing the mandate (See Mandate Object section)
mandateInfo.resendMandateForSignature optional Stringenum DEFAULT: Only alter the Mandate Status from ACTIVE to PENDING if a Key Field is altered in the Request
SEND: Always alter Mandate status from ACTIVE back to PENDING regardless of the update
DO_NOT_SEND: Never alter the Mandate status from ACTIVE to PENDING, regardless of the update

Returns

Returns 200 OK response code and JSON structure representing the updated mandate resource.

In case of failure, an error is returned within the error structure (see Errors section).

Activate Mandate

Example request

$ curl 'https://api.nuapay.com/schemes/46pkx7o9n5/mandates/ne8y69wwpo/activate' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X POST -H 'Content-Type: application/json' -d \
  '{
    "signatureDate": "2015-07-21",
    "signatureLocation": "Signature Location",
    "electronicSignatureDetails": {
      "authorizationMethod": "SMS_PASSWORD",
      "authorizationToken": "1234",
      "authorizationEmail": "debtor@email.com",
      "authorizationMobileNumber": "0360321312312",
      "ipAddress": "192.168.8.1",
      "geographicLocation": "Geo Location"
    }
  }'
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

ActivateMandateRequest activateMandateRequest = 
        new ActivateMandateRequest()
        .withSignatureDate(DateUtils.toDate("2015-07-21"))
        .withSignatureLocation("Signature Location")
        .withElectronicSignatureDetails(
                new ElectronicSignatureDetails()
                .withAuthorizationMethod("SMS_PASSWORD")
                .withAuthorizationToken("1234")
                .withAuthorizationEmail("debtor@email.com")
                .withAuthorizationMobileNumber("0360321312312")
                .withIpAddress("192.168.8.1")
                .withGeographicLocation("Geo Location")
                );

MandateResource mandateResource = 
    new MandateServiceDefault(serviceConfig)
        .activateMandate("46pkx7o9n5", "ne8y69wwpo", activateMandateRequest)
        .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/activate",
  "data": {
    "id": "w24y3dya2p",
    "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p",
        "debtor" : {
      "name" : "Debtor Name",
      "address" : {
        "line1" : "Debtor Address Line1",
        "line2" : "Debtor Address Line2",
        "town" : " Debtor Town",
        "postCode" : "123123",
        "state" : "Debtor State",
        "country" : "IE"
      },
      "language" : "fr_BE",
      "email" : "debtor@email.com",
      "phoneNumber" : "0360123123123",
      "mobileNumber" : "0360321312312"
    },
    "mandateInfo" : {
      "mandateId" : "1234567899",
      "contractReference" : "Contract Reference",
      "signatureLocation" : "Signature Location",
      "signatureDate" : "2015-07-21",
      "mandateType" : "RCUR",
      "status" : "ACTIVE",
      "creationDate" : "2015-07-21"
    },
    "debtorAccount" : {
      "iban" : "GB94SELN00999976543215",
      "bic" : "SELNGB21"
    },
    "creditorAccount" : {
      "iban" : "GB47SELN00999912345678",
      "bic" : "SELNGB21"
    }
  }
}

A POST request is used to activate mandates. A request must contain the application/json content type. In the request body you must provide a JSON structure describing the Mandate.

Definition

POST /schemes/{CS_ID}/mandates/{MANDATE_ID}/activate

Arguments

JSON Path Type Description
signatureDateoptional Dateyyyy-mm-dd Signature Date
signatureLocationoptional Stringmax 70 chars Signature Location
electronicSignatureDetails.authorizationMethodoptional Stringenum Possible values: CHECK_BOX, SMS_PASSWORD, EMAIL_PASSWORD
electronicSignatureDetails.authorizationTokenoptional Stringmax 35 chars Authentication Token (OTP)
electronicSignatureDetails.authorizationEmailoptional Stringmax 254 chars Authentication Email Address
electronicSignatureDetails.authorizationMobileNumberoptional Stringmax 30 chars Authentication Phone Number
electronicSignatureDetails.ipAddressoptional String max 39 chars Authentication IP Address
electronicSignatureDetails.geographicLocationoptional String max 70 chars Authentication Geographic Location

Returns

Returns 200 OK response code and a JSON structure representing the altered mandate resource.

In case of failure, an error is returned within the error structure (see Errors section).

Cancel Mandate

Example request

$ curl 'https://api.nuapay.com/schemes/46pkx7o9n5/mandates/ne8y69wwpo/cancel' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X POST -H 'Content-Type: application/json' \
  -d '{"operationReason":"Reason for cancellation"}'
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

CancelMandateRequest cancelMandateRequest = 
        new CancelMandateRequest()
            .withOperationReason("Reason for cancellation");

MandateResource mandateResource = 
    new MandateServiceDefault(serviceConfig)
        .cancelMandate("46pkx7o9n5", "ne8y69wwpo", cancelMandateRequest)
        .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p",
  "data": {
    "id": "w24y3dya2p",
    "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p",
    "debtor" : {
      "name" : "Debtor Name",
      "address" : {
        "line1" : "Debtor Address Line1",
        "line2" : "Debtor Address Line2",
        "town" : " Debtor Town",
        "postCode" : "123123",
        "state" : "Debtor State",
        "country" : "IE"
      },
      "language" : "fr_BE",
      "email" : "debtor@email.com",
      "phoneNumber" : "0360123123123",
      "mobileNumber" : "0360321312312"
    },
    "mandateInfo" : {
      "mandateId" : "1234567899",
      "contractReference" : "Contract Reference",
      "signatureLocation" : "Signature Location",
      "signatureDate" : "2015-07-21",
      "mandateType" : "RCUR",
      "status" : "CANCELLED",
      "creationDate" : "2015-07-21"
    },
    "debtorAccount" : {
      "iban" : "GB94SELN00999976543215",
      "bic" : "SELNGB21"
    },
    "creditorAccount" : {
      "iban" : "GB47SELN00999912345678",
      "bic" : "SELNGB21"
    }
  }
}

A POST request is used to cancel mandate.

Definition

POST /schemes/{CS_ID}/mandates/{MANDATE_ID}/cancel

Arguments

JSON Path Type Description
operationReasonrequired Stringmax 140 chars Reason for cancellation

Returns

Returns 200 OK response code and JSON structure representing the altered mandate resource.

In case of failure, an error is returned within the error structure (see Errors section).

Direct Debits

Direct debits are the financial transactions associated to the mandate.

To access direct debits use the following URL:

https://api.nuapay.com/schemes/{CS_ID}/mandates/{MANDATE_ID}/directdebits/{DD_ID}

where

Direct Debit Object

Example JSON structure describing direct debit

{
    "scheduleId": null,
    "endToEndId": "1234567876543234567",
    "paymentAmount": 5000.01,
    "requestedCollectionDate": "2015-08-12",
    "actualCollectionDate": "2015-08-12",
    "exportDate": "2015-08-05",
    "remittanceInformation": "Remittance Information",
    "originalEndToEndId": null,
    "representationAttemptNumber": 0,
    "paymentStatus": "READY_FOR_EXPORT",
    "rejectDetails" : {
      "rejectReason" : null,
      "rejectDescription" : null,
      "rejectType" : null,
      "rejectDate" : null
    },
    "links":[
                        {
               "resourceType": "mandate",
               "id": "ybo8zd8j2q",
               "uri": "/schemes/abxq98zk2l/mandates/ybo8zd8j2q"
            },
                        {
               "resourceType": "scheme",
               "id": "abxq98zk2l",
               "uri": "/schemes/abxq98zk2l"
            }
    ]
}
Path Type Description
scheduleId Stringmax 19 chars This is the customer payment schedule reference that is further used to identify the schedule when filtering direct debits.
endToEndId Stringmax 35 chars Payment Reference
paymentAmount Numbermax 15 digits Payment Amount. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places allowed.
requestedCollectionDate Dateyyyy-mm-dd Requested Settlement Date
actualCollectionDate Dateyyyy-mm-dd Actual Settlement Date
exportDate Dateyyyy-mm-dd Export Date
remittanceInformation Stringmax 140 chars Remittance Information
originalEndToEndId Stringmax 35 chars Return parameter only, non-null only if direct debit is a re-presentation of a different direct debit
representationAttemptNumber Number Return parameter only
paymentStatus Stringenum Return parameter only. One of, READY_FOR_EXPORT, EXPORTING, REVOKED, EXPORTED, ACCEPTED, REVERSED, REFUSED, REJECTED, RETURNED, REFUNDED, CANCELLED, PENDING, REPRESENTED
rejectDetails.rejectReason Stringenum Reason code
rejectDetails.rejectDescription Stringmax 140 chars
rejectDetails.rejectType Stringenum One of Cancellation, Reject, Reversal, Return, Refusal, Authorised Refund, Unauthorised Refund, Reject Reversal, Reject Cancel, Revoke, Return Reject, Refund Reject, Import_Reject.
rejectDetails.rejectDate Dateyyyy-mm-dd The date direct debit was rejected
links.resourceType String Resource Type. One of mandate, scheme, schedule
links.id String Resource Id
links.uri String Resource URI

Failed Direct Debit Object

Example JSON structure describing failed direct debit

{
      "creditorScheme":       {
         "schemeType": "CORE",
         "creditorSchemeId": "1234"
      },
      "mandateInfo":       {
         "mandateId": "MAND000050851137B",
         "domesticMandateId": null
      },
      "directDebitInfo":       {
         "endToEndId": "e2eId",
         "scheduleId": null,
         "paymentAmount": 456,
         "requestedCollectionDate": "2017-06-13",
         "actualCollectionDate": "2017-06-13",
         "exportDate": "2017-06-12",
         "remittanceInfo": null,
         "originalEndToEndId": null,
         "representationAttemptNumber": 0,
         "paymentStatus": "REJECTED"
      },
      "rejectDetails":       {
         "rejectReason": "MD07",
         "rejectDescription": "Debtor deceased.",
         "rejectType": "Reject",
         "rejectDate": "2017-09-12"
      }
  }
Path Type Description
creditorScheme.schemeType Stringenum One of CORE, B2B
creditorScheme.creditorSchemeId Stringmax 35 chars Creditor Scheme ID
mandateInfo.mandateId Stringmax 35 chars Mandate Reference (the Unique Mandate Reference - UMR)
mandateInfo.domesticMandateId Stringmax 35 chars Domestic Mandate Reference
directDebitInfo.endToEndId Stringmax 35 chars Payment Reference
directDebitInfo.scheduleId Stringmax 19 chars This is the customer payment schedule reference. Non-null if the direct debit belongs to a payment schedule
directDebitInfo.paymentAmount Numbermax 15 digits Payment Amount. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places allowed.
directDebitInfo .requestedCollectionDate Dateyyyy-mm-dd Requested Settlement Date
directDebitInfo.actualCollectionDate Dateyyyy-mm-dd Actual Settlement Date
directDebitInfo.exportDate Dateyyyy-mm-dd Export Date
directDebitInfo.remittanceInfo Stringmax 140 chars Remittance Information
directDebitInfo.originalEndToEndId Stringmax 35 chars A Return parameter only; Non-null if the direct debit is a re-presentation of a different direct debit
directDebitInfo.representationAttemptNumber Number Representation Attempt
directDebitInfo.paymentStatus Stringenum One of REFUSED, REFUNDED, REVERSED, REVOKED, CANCELLED, RETURNED, REJECTED, REPRESENTED
rejectDetails.rejectReason Stringenum Reason code
rejectDetails.rejectDescription Stringmax 140 chars
rejectDetails.rejectType Stringenum One of Cancellation, Reject, Reversal, Return, Refusal, Authorised Refund, Unauthorised Refund, Reject Reversal, Reject Cancel, Revoke, Return Reject, Refund Reject, Import_Reject.
rejectDetails.rejectDate Dateyyyy-mm-dd The date direct debit was rejected

Create Direct Debit

Example request

$ curl 'https://api.nuapay.com/schemes/46pkx7o9n5/mandates/w24y3dya2p/directdebits' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X POST -H 'Content-Type: application/json' -d \
  '{
      "requestedCollectionDate": "2015-08-12",
      "paymentAmount": 5000.01,
      "endToEndId": "1234567876543234567",
      "remittanceInformation": "Remittance Information",
      "settlementDateShift": true
   }'
CreateDirectDebitRequest createDirectDebitRequest = 
        new CreateDirectDebitRequest()
            .withRequestedCollectionDate(DateUtils.toDate("2015-08-12"))
            .withPaymentAmount(new BigDecimal("5000.01"))
            .withEndToEndId("5234567876543234567")
            .withRemittanceInformation("Remittance Information");

DirectDebitResource directDebitResource = 
        new DirectDebitServiceDefault(serviceConfig)
            .createDirectDebit("46pkx7o9n5", "46pkx7o9n5", 
                createDirectDebitRequest).getData();

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits/j29p3kpabx",
  "data": {
    "id": "j29p3kpabx",
    "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits/j29p3kpabx",
    "scheduleId": null,
    "endToEndId": "1234567876543234567",
    "paymentAmount": 5000.01,
    "requestedCollectionDate": "2015-08-12",
    "actualCollectionDate": "2015-08-12",
    "exportDate": "2015-08-05",
    "remittanceInformation": "Remittance Information",
    "originalEndToEndId": null,
    "representationAttemptNumber": 0,
    "paymentStatus": "READY_FOR_EXPORT",
    "rejectDetails" : {
      "rejectReason" : null,
      "rejectDescription" : null,
      "rejectType" : null,
      "rejectDate" : null
    },
    "links":[
                        {
               "resourceType": "mandate",
               "id": "w24y3dya2p",
               "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p"
            },
                        {
               "resourceType": "scheme",
               "id": "abxq9kq52l",
               "uri": "/schemes/abxq9kq52l"
            }
    ]

  }
}

A POST request is used to create direct debits. A request must contain the application/json content type. In the request body you must provide a JSON structure describing the Direct Debit.

Definition

POST /schemes/{CS_ID}/mandates/{MANDATE_ID}/directdebits

Arguments

JSON Path Type Description
requestedCollectionDaterequired Date yyyy-mm-dd Requested collection date
paymentAmountrequired Number max 15 digits Payment Amount. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places allowed.
endToEndIdoptional String max 35 alphanum Payment Reference
remittanceInformationoptional String max 140 chars Remittance Information
settlementDateShiftoptional Boolean If true, settlement date shift logic is applied and requestedCollectionDate can be shifted and returned as actualCollectionDate

Returns

Returns 201 Created response code and a JSON structure representing the created resource.

In case of failure, an error is returned within the error structure (see Errors section).

Create Direct Debit & Mandate

Example request

$ curl 'https://api.nuapay.com/schemes/abxq9kq52l/directdebits' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X POST -H 'Content-Type: application/json' -d \
  '{
 "requestedCollectionDate": "2017-09-03",
  "paymentAmount": 5000.01,
  "endToEndId": "12345678876543234567",
  "remittanceInformation": "Remittance Information",
  "settlementDateShift": true,
  "mandate": {
    "debtor": {
      "name": "Debtor Name",
      "address": {
        "line1": "Debtor Address Line1",
        "line2": "Debtor Address Line2",
        "town": " Debtor Town",
        "postCode": "123123",
        "state": "Debtor State",
        "country": "IE"
      },
      "language": "sk",
      "email": "debtor@email.com",
      "phoneNumber": "0360123123123",
      "mobileNumber": "0360321312312"
    },
    "mandateInfo": {
      "contractReference": "Contract Reference",
      "signatureLocation": "Signature Location",
      "signatureDate": "2015-07-21",
      "mandateType": "RCUR"
    },
    "debtorAccount": {
      "iban": "GB94SELN00999976543215",
      "bic": "SELNGB21"
    },
    "creditorAccount": {
      "iban": "GB47SELN00999912345678",
      "bic": "SELNGB21"
    }
  }
}'
CreateDirectDebitAndMandateRequest createDirectDebitAndMandateRequest = 
    new CreateDirectDebitAndMandateRequest()
        .withMandate(new Mandate()
        .withDebtor(
            new Debtor()
                .withName("Debtor Name")
                .withAddress(
                    new Address()
                        .withLine1("Debtor Address Line1")
                        .withLine2("Debtor Address Line2")
                        .withTown("Debtor Town")
                        .withPostCode("123123")
                        .withState("Debtor State")
                        .withCountry("IE")
                    )
                .withLanguage(CommunicationLanguage.fr_BE)
                .withEmail("debtor@email.com")
                .withPhoneNumber("0360123123123")
                .withMobileNumber("0360321312312")
            )
        .withMandateInfo(
            new MandateInfo()
                .withMandateId("1234567899")
                .withContractReference("Contract Reference")
                .withSignatureLocation("Signature Location")
                .withSignatureDate(DateUtils.toDate("2015-07-21"))
                .withMandateType(MandateType.RCUR)
                )
        .withDebtorAccount(
            new BasicAccount()
                .withIban("GB94SELN00999976543215")
            )
        .withCreditorAccount(
            new BasicAccount()
                .withIban("GB47SELN00999912345678")
            ));
createDirectDebitAndMandateRequest
    .withRequestedCollectionDate(DateUtils.toDate("2017-09-03"))
    .withPaymentAmount(new BigDecimal("5000.01"))
    .withEndToEndId("12345678876543234567")
    .withRemittanceInformation("Remittance Information");

DirectDebitAndMandateResource directDebitAndMandateResource = 
    new DirectDebitServiceDefault(serviceConfig)
        .createDirectDebitAndMandate(
            "6bz34xwomd", createDirectDebitAndMandateRequest)
            .getData();

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
   "uri": "/schemes/abxq98zk2l/mandates/wbv7e9dkb7/directdebits/6bz34xwomd",
   "data":    {
      "id": "6bz34xwomd",
      "uri": "/schemes/abxq98zk2l/mandates/wbv7e9dkb7/directdebits/6bz34xwomd",
      "scheduleId": null,
      "endToEndId": "12345678876543234567",
      "paymentAmount": 5000.01,
      "requestedCollectionDate": "2017-09-03",
      "actualCollectionDate": "2017-09-05",
      "exportDate": "2017-08-22",
      "remittanceInformation": "Remittance Information",
      "originalEndToEndId": null,
      "representationAttemptNumber": 0,
      "paymentStatus": "READY_FOR_EXPORT",
      "rejectDetails":       {
         "rejectReason": null,
         "rejectDescription": null,
         "rejectType": null,
         "rejectDate": null
      },
      "links":       [
                  {
            "resourceType": "mandate",
            "id": "wbv7e9dkb7",
            "uri": "/schemes/abxq98zk2l/mandates/wbv7e9dkb7"
         },
                  {
            "resourceType": "scheme",
            "id": "abxq98zk2l",
            "uri": "/schemes/abxq98zk2l"
         }
      ]
   }
}

A POST request is used to create direct debits and mandates within a single request. A request must contain the application/json content type. In the request body you must provide a JSON structure describing the Direct Debit and Mandate.

Definition

POST /schemes/{CS_ID}/directdebits

Arguments

JSON Path Type Description
requestedCollectionDaterequired Date yyyy-mm-dd Requested collection date
paymentAmountrequired Number max 15 digits Payment Amount. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places allowed.
endToEndIdoptional String max 35 alphanum Payment Reference
remittanceInformationoptional String max 140 chars Remittance Information
mandaterequired Object Mandate Object
settlementDateShiftoptional Boolean If true, settlement date shift logic is applied and requestedCollectionDate can be shifted and returned as actualCollectionDate

Returns

Returns 201 Created response code and a JSON structure representing the created Direct Debit.

In case of failure, an error is returned within the error list structure (see Errors section).

Retrieve Direct Debit

Example request

$ curl 'https://api.nuapay.com/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits/j29p3kpabx' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: 
DirectDebitResource directDebitResource = 
    new DirectDebitServiceDefault(serviceConfig)
        .retrieveDirectDebit("abxq9kq52l", "abxq9kq52l", "abxq9kq52l").getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits/j29p3kpabx",
  "data": {
    "id": "j29p3kpabx",
    "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits/j29p3kpabx",
    "scheduleId": null,
    "endToEndId": "1234567876543234567",
    "paymentAmount": 5000.01,
    "requestedCollectionDate": "2015-08-12",
    "actualCollectionDate": "2015-08-12",
    "exportDate": "2015-08-05",
    "remittanceInformation": "Remittance Information",
    "originalEndToEndId": null,
    "representationAttemptNumber": 0,
    "paymentStatus": "READY_FOR_EXPORT",
    "rejectDetails" : {
      "rejectReason" : null,
      "rejectDescription" : null,
      "rejectType" : null,
      "rejectDate" : null
    },
    "links":[
                        {
               "resourceType": "mandate",
               "id": "w24y3dya2p",
               "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p"
            },
                        {
               "resourceType": "scheme",
               "id": "abxq9kq52l",
               "uri": "/schemes/abxq9kq52l"
            }
    ]

  }
}

A GET request is used to retrieve direct debits.

Definition

GET /schemes/{CS_ID}/mandates/{MANDATE_ID}/directdebits/{DD_ID}

Returns

Returns 200 OK response code and a JSON structure representing the queried direct debit resource.

In case of failure, an error is returned within the error structure (see Errors section).

List Direct Debits

Example request

$ curl 'https://api.nuapay.com/schemes/46pkx7o9n5/mandates/w24y3dya2p/directdebits/?actualcollectiondatefrom=2015-07-29&actualcollectiondateto=2015-08-28' \
   -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
ListDirectDebitRequestParameters listDDRequestParameters = 
        new ListDirectDebitRequestParameters()
        .withActualCollectionDateFrom(DateUtils.toDate("2015-07-29"))
        .withActualCollectionDateTo(DateUtils.toDate("2015-08-28"));

List<DirectDebitResource> directDebitResourcesList = 
        new DirectDebitServiceDefault(serviceConfig)
            .listDirectDebits("46pkx7o9n5", "46pkx7o9n5", listDDRequestParameters)
            .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits",
  "data": [
    {
      "id": "j29p3kpabx",
      "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits/j29p3kpabx",
      "scheduleId": null,
      "endToEndId": "1234567876543234567",
      "paymentAmount": 5000.01,
      "requestedCollectionDate": "2015-08-12",
      "actualCollectionDate": "2015-08-12",
      "exportDate": "2015-08-05",
      "remittanceInformation": "Remittance Information",
      "originalEndToEndId": null,
      "representationAttemptNumber": 0,
      "paymentStatus": "READY_FOR_EXPORT",
      "rejectDetails" : {
        "rejectReason" : null,
        "rejectDescription" : null,
        "rejectType" : null,
        "rejectDate" : null
        },
    "links":[
                        {
               "resourceType": "mandate",
               "id": "w24y3dya2p",
               "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p"
            },
                        {
               "resourceType": "scheme",
               "id": "abxq9kq52l",
               "uri": "/schemes/abxq9kq52l"
            }
    ]
    }
  ],
  "page": {
    "pageNumber": 1,
    "pageSize": 20,
    "totalElements": 1,
    "totalPages": 1
  },
  "sort": [
  ]
}

A GET request is used to retrieve collection of direct debits. Can be used to list all direct debits associated to a mandate, scheme or originator.

Definition

List all direct debits under a mandate:

GET /schemes/{CS_ID}/mandates/{MANDATE_ID}/directdebits

List all direct debits under a scheme:

GET /schemes/{CS_ID}/directdebits

List all direct debits under an originator:

GET /directdebits

Arguments

Request param Description
actualcollectiondatefromoptional Format yyyy-mm-dd.
actualcollectiondatetooptional Format yyyy-mm-dd.
scheduleidoptional The Payment Schedule ID of a specific DD. Used to filter direct debits under particular Payment Schedule (See Payment Schedule Object section).
paymentstatusoptional One of, ALL, READY_FOR_EXPORT, EXPORTING, REVOKED, EXPORTED, ACCEPTED, REVERSED, REFUSED, REJECTED, RETURNED, REFUNDED, CANCELLED, PENDING, REPRESENTED. Note number of statuses can be queried within single request by providing multiple occurance of the parameter.

Returns

Returns 200 OK response code and a JSON structure representing a collection of direct debit objects.

In case of failure, an error is returned within the error structure (see Errors section).

List Failed Direct Debits

Example request

$ curl 'https://api.nuapay.com/faileddirectdebits?rejectcreatefrom=2015-07-29&rejectcreateto=2015-07-29&technicalrejects=false' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
ListFailedDirectDebitRequestParameters listFailedDDRequestParameters = 
        new ListFailedDirectDebitRequestParameters()
            .withRejectCreateFrom(DateUtils.toDate("2015-07-29"))
            .withRejectCreateTo(DateUtils.toDate("2015-07-29"))
            .withTechnicalRejects(false);

List<FailedDirectDebitResource> directDebitResourcesList = 
        new DirectDebitServiceDefault(serviceConfig)
            .listFailedDirectDebits(listFailedDDRequestParameters)
            .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "uri": "/faileddirectdebits",
   "data": [   {
      "id": "a2rexqrdmq",
      "uri": "/schemes/abxq93kk2l/mandates/wbv7x6zvb7/directdebits/a2rexqrdmq",
      "creditorScheme":       {
         "schemeType": "CORE",
         "creditorSchemeId": "1234"
      },
      "mandateInfo":       {
         "mandateId": "MAND000050851137B",
         "domesticMandateId": null
      },
      "directDebitInfo":       {
         "endToEndId": "e2eId",
         "scheduleId": null,
         "paymentAmount": 456,
         "requestedCollectionDate": "2017-06-13",
         "actualCollectionDate": "2017-06-13",
         "exportDate": "2017-06-12",
         "remittanceInfo": null,
         "originalEndToEndId": null,
         "representationAttemptNumber": 0,
         "paymentStatus": "REJECTED"
      },
      "rejectDetails":       {
         "rejectReason": "MD07",
         "rejectDescription": "Debtor deceased.",
         "rejectType": "Reject",
         "rejectDate": "2017-09-12"
      }
   }]
}

A GET request used to list failed direct debits.

Definition

GET /faileddirectdebits

Arguments

Request parameter Description
rejectcreatefrom required Create date from in yyyy-mm-dd format.
rejectcreateto required Create date to in yyyy-mm-dd format.
technicalrejects optional Boolean value, where false returns only bank rejections and true returns all rejections including OCX rejections and file import rejections.

Returns

Returns 200 OK response code and a JSON structure representing a collection of failed direct debits.

In case of failure, an error is returned within the error structure (see Errors section).

Revoke Direct Debit

Example request

$ curl 'https://api.nuapay.com/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits/j29p3kpabx/revoke' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X POST -H 'Content-Type: application/json' \
  -d '{"operationReason":"Reason for revoke"}'
RevokeDirectDebitRequest revokeDirectDebitRequest = 
    new RevokeDirectDebitRequest()
        .withOperationReason("Reason for revoke");

DirectDebitResource directDebitResource = 
    new DirectDebitServiceDefault(serviceConfig)
        .revokeDirectDebit(
            "w24y4dro2p", "w24y4dro2p", "w24y4dro2p", 
            revokeDirectDebitRequest).getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "uri": "/schemes/abxq98zk2l/mandates/ybo8zd8j2q/directdebits/w24y4dro2p",
   "data":    {
      "id": "w24y4dro2p",
      "uri": "/schemes/abxq98zk2l/mandates/ybo8zd8j2q/directdebits/w24y4dro2p",
      "scheduleId": "518050",
      "endToEndId": "3D49D84D-AF15-4F09-9",
      "paymentAmount": 9.9,
      "requestedCollectionDate": "2017-09-06",
      "actualCollectionDate": "2017-09-06",
      "exportDate": "2017-08-23",
      "remittanceInformation": "remittanceInformation",
      "originalEndToEndId": null,
      "representationAttemptNumber": 0,
      "paymentStatus": "REVOKED",
      "rejectDetails":       {
         "rejectReason": "CUST",
         "rejectDescription": "Reason for revoke",
         "rejectType": "Revoke",
         "rejectDate": "2017-08-21"
      },
      "links":       [
                  {
            "resourceType": "mandate",
            "id": "ybo8zd8j2q",
            "uri": "/schemes/abxq98zk2l/mandates/ybo8zd8j2q"
         },
                  {
            "resourceType": "scheme",
            "id": "abxq98zk2l",
            "uri": "/schemes/abxq98zk2l"
         },
                  {
            "resourceType": "schedule",
            "id": "j29pv8oabx",
            "uri": "/schemes/abxq98zk2l/mandates/ybo8zd8j2q/paymentschedules/j29pv8oabx"
         }
      ]
   }
}

A POST request used to revoke direct debits. A request must contain the application/json content type. In the request body you must provide a JSON structure describing the revocation reason.

Definition

POST /schemes/{CS_ID}/mandates/{MANDATE_ID}/directdebits/{DD_ID}/revoke

Arguments

JSON Path Type Description
operationReasonoptional Stringmax 140 chars Reason for revoke

Returns

Returns 200 OK response code and a JSON structure representing the altered direct debit resource.

In case of failure, an error is returned within the error structure (see Errors section).

Revoke All Direct Debits

Example request

$ curl 'https://api.nuapay.com/schemes/abxq9kq52l/mandates/w24y3dya2p/revokealldirectdebits' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X POST -H 'Content-Type: application/json' \
  -d '{"operationReason":"Reason for revoke"}'
RevokeAllDirectDebitsRequest revokeDirectDebitRequest = 
        new RevokeAllDirectDebitsRequest()
            .withOperationReason("Reason for revoke all");

RevokeAllDirectDebitsSummary revokeAllDirectDebitsSummary = 
        new DirectDebitServiceDefault(serviceConfig)
            .revokeAllDirectDebits(
                "abxq9kq52l", "abxq9kq52l", revokeDirectDebitRequest)
                .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/revokealldirectdebits",
  "data": {
    "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/revokealldirectdebits",
    "totalTransactionsRevoked": 1,
    "totalAmountRevoked": 5000.01
  }
}

A POST request used to revoke all direct debits. A request must contain the application/json content type. In the request body you must provide a JSON structure with the required parameters.

Definition

POST /schemes/{CS_ID}/mandates/{MANDATE_ID}/revokealldirectdebits

Arguments

JSON Path Type Description
operationReasonoptional String max 140 chars Reason for the revocation
scheduleIdoptional String max 19 chars Payment Schedule Reference

Returns

Returns 200 OK response code and a JSON structure representing the revocation action.

In case of failure, an error is returned within the error structure (see Errors section).

Re-present Failed Direct Debit

Example request

$ curl 'https://api.nuapay.com/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits/w24y3dya2p/represent' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X POST -H 'Content-Type: application/json' -d '{}'
RepresentDirectDebitRequest representDirectDebitRequest = 
        new RepresentDirectDebitRequest();

DirectDebitResource directDebitResource = 
        new DirectDebitServiceDefault(serviceConfig)
            .representDirectDebit(
                "abxq9kq52l", "abxq9kq52l", "abxq9kq52l", 
                representDirectDebitRequest).getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits/j29p3kpabx",
  "data": {
    "id": "j29p3kpabx",
    "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p/directdebits/j29p3kpabx",
    "scheduleId": null,
    "endToEndId": "103EA22B-D737-4886-B",
    "paymentAmount": 5000.01,
    "requestedCollectionDate": "2015-08-04",
    "actualCollectionDate": "2015-02-04",
    "exportDate": "2015-08-01",
    "originalEndToEndId": "1234567890123456789",
    "representationAttemptNumber": 1,
    "paymentStatus": "READY_FOR_EXPORT",
    "rejectDetails" : {
      "rejectReason" : null,
      "rejectDescription" : null,
      "rejectType" : null,
      "rejectDate" : null
    },
    "links":[
                        {
               "resourceType": "mandate",
               "id": "w24y3dya2p",
               "uri": "/schemes/abxq9kq52l/mandates/w24y3dya2p"
            },
                        {
               "resourceType": "scheme",
               "id": "abxq9kq52l",
               "uri": "/schemes/abxq9kq52l"
            }
    ]
  }
}

A POST request used to re-present direct debits. A request must contain the application/json content type. In the request body you must provide a JSON structure with the required parameters. You can re-present the direct debits only if the service is enabled. Please contact support to enable this service.

Definition

POST /schemes/{CS_ID}/mandates/{MANDATE_ID}/directdebits/{DD_ID}/represent

Arguments

JSON Path Type Description
representationDate optional Date yyyy-mm-dd Re-presentation Date
representationFee optional Number max 15 digits Re-presentation Fee
endToEndId optional String max 35 alphanum Payment Reference. Must be a unique value and different to the Payment Reference supplied for the failed direct debit being re-presented

Returns

Returns 200 OK response code and a JSON structure representing the altered direct debit resource. NOTE: The values of id, uri in the response will be different to those supplied in the request. NOTE: The value of endToEndId (if not supplied) in the response will be different to the value of endToEndId that applied to the original failed direct debit

In case of failure, an error is returned within the error structure (see Errors section).

Payment Schedules

Payment Schedules allow you to set up a number of payments against a mandate in one go. Schedules can be Fixed-Length (e.g. collect €10 each month for 12 months) or Open-Ended (e.g. collect €10 every month with no fixed number of payments being defined).

To access payment schedules use the following URL:

https://api.nuapay.com/schemes/{CS_ID}/mandates/{MANDATE_ID}/directdebits/{DD_ID}

where

Schedule Object

Path Type Description
scheduleId optional String max 19 chars This is the customer payment schedule reference that is further used to identify the schedule when filtering direct debits.
paymentFrequency required String enum Possible values: DAILY, WEEKLY, BIWEEKLY, MONTHLY, YEARLY, CUSTOM
paymentType required String enum Possible values: FIXED_LENGTH, OPEN_ENDED
startDate required Dateyyyy-mm-dd Actual Collection Date (ACD) of first payment for the schedule
numberOfPayments optional Number max 3 digits Required for FIXED_LENGTH schedule type. Not allowed for OPEN_ENDED schedule
paymentAmount required Number max 15 chars Amount of regular payment to be sent. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places allowed. Amounts with no decimals can be sent without decimal point.
firstPaymentAmount optional Number max 15 chars Amount of first payment to be sent. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places allowed. Amounts with no decimals can be sent without decimal point.
lastPaymentAmount optional Number max 15 chars Amount of last payment to be sent. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places allowed. Amounts with no decimals can be sent without decimal point.
remittanceInformation optional String max 140 chars Remittance information that will be sent with every payment generated as part of the schedule
paymentDayOfWeek optional String enum Possible values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY
paymentWeekOfMonth optional String enum Possible values: FIRST, SECOND, THIRD, FOURTH, LAST
paymentDateInMonth optional String max 2 digits Between 1 and 31
paymentCustomFrequency optional String enum Determines if a payment schedule is quarterly (payment every 3 months) or bi-annually (payment every 6 months). Must be present for CUSTOM paymentFrequency. Otherwise not present. Possible value: 3, 6.
twoPaymentsSamePeriod optional Boolean true/false Boolean that determines if two direct debits should be generated, in case subsequent payment date (paymentDayOfWeek, paymentWeekOfMonth, paymentDateInMonth) is later than the startDate.
settlementDateShiftoptional Boolean If true, settlement date shift logic is applied and start date can be shifted
paymentScheduleStatus optional String enum Possible values: ACTIVE, INACTIVE, CANCELLED.
links.resourceType String Resource Type. One of mandate, scheme, schedule
links.id String Resource Id
links.uri String Resource URI

Create Schedule

Example request

$ curl 'https://api.nuapay.com/schemes/abxq9kq52l/mandates/w24y3dya2p/paymentschedules' \
  -u 81d8064d88c89947d7b96adb1c54c5328bd4d9cf567281db9d074ffda16d2d63: \
  -X POST -H 'Content-Type: application/json' -d \
  '{
    "paymentFrequency":"DAILY",
    "paymentType":"FIXED_LENGTH",
    "startDate":"2017-09-03",
    "numberOfPayments":2,
    "paymentAmount":9.90,
    "firstPaymentAmount":1.10,
    "lastPaymentAmount":9.90,
    "remittanceInformation":"remittanceInformation",
    "twoPaymentsSamePeriod":true,
    "settlementDateShift": true
}'
CreatePaymentScheduleRequest createPaymentSchedRequest = 
        new CreatePaymentScheduleRequest()
            .withPaymentSchedule(
                    new PaymentSchedule()
                        .withPaymentFrequency(PaymentFrequency.DAILY)
                        .withPaymentType(PaymentType.FIXED_LENGTH)
                        .withStartDate(DateUtils.toDate("2017-09-03"))
                        .withNumberOfPayments(2)
                        .withPaymentAmount(new BigDecimal("9.90"))
                        .withFirstPaymentAmount(new BigDecimal("1.10"))
                        .withLastPaymentAmount(new BigDecimal("9.90"))
                        .withRemittanceInformation("remittanceInformation")
                        .withTwoPaymentsSamePeriod(true));

PaymentScheduleResource paymentScheduleResponse = 
        new PaymentScheduleServiceDefault(serviceConfig)
            .createPaymentSchedule(
                "j29pv8oabx", "j29pv8oabx", createPaymentSchedRequest)
                .getData();

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
   "uri": "/schemes/abxq98zk2l/mandates/ybo8zd8j2q/paymentschedules/j29pv8oabx",
   "data":    {
      "id": "j29pv8oabx",
      "uri": "/schemes/abxq98zk2l/mandates/ybo8zd8j2q/paymentschedules/j29pv8oabx",
      "scheduleId": "518050",
      "paymentFrequency": "DAILY",
      "paymentType": "FIXED_LENGTH",
      "startDate": "2017-09-05",
      "numberOfPayments": 2,
      "paymentAmount": 9.9,
      "firstPaymentAmount": 1.1,
      "lastPaymentAmount": 9.9,
      "remittanceInformation": "remittanceInformation",
      "paymentDayOfWeek": null,
      "paymentWeekOfMonth": null,
      "paymentDateInMonth": null,
      "paymentCustomFrequency": null,
      "twoPaymentsSamePeriod": true,
      "paymentScheduleStatus": "ACTIVE",
      "links":       [
                  {
            "resourceType": "mandate",
            "id": "ybo8zd8j2q",
            "uri": "/schemes/abxq98zk2l/mandates/ybo8zd8j2q"
         },
                  {
            "resourceType": "scheme",
            "id": "abxq98zk2l",
            "uri": "/schemes/abxq98zk2l"
         }
      ]
   }
}

A POST request used to create payment schedules. A request must contain the application/json content type. In the request body you must provide a JSON structure describing the Payment Schedule.

NOTE: Creation of payment schedule results in creation of one (OPEN_ENDED) or more (FIXED_LENGTH) direct debits associated to the schedule. Please use List Direct Debits service, filtering by scheduleId to get the list of created direct debits.

Definition

POST /schemes/{CS_ID}/mandates/{MANDATE_ID}/paymentschedules

Arguments

JSON Path Type Description
scheduleId optional String max 19 chars This is the customer payment schedule reference that is further used to identify the schedule when filtering direct debits.
paymentFrequency required String enum Possible values: DAILY, WEEKLY, BIWEEKLY, MONTHLY, YEARLY, CUSTOM
paymentType required String enum Possible values: FIXED_LENGTH, OPEN_ENDED
startDate required Dateyyyy-mm-dd Actual Collection Date (ACD) of first payment for the schedule
numberOfPayments optional Number max 3 digits Required for FIXED_LENGTH schedule type. Not allowed for OPEN_ENDED schedule
paymentAmount required Number max 15 chars Amount of regular payment to be sent. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places allowed. Amounts with no decimals can be sent without decimal point.
firstPaymentAmount optional Number max 15 chars Amount of first payment to be sent. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places allowed. Amounts with no decimals can be sent without decimal point.
lastPaymentAmount optional Number max 15 chars Amount of last payment to be sent. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places allowed. Amounts with no decimals can be sent without decimal point.
remittanceInformation optional String max 140 chars Remittance information that will be sent with every payment generated as part of the schedule
paymentDayOfWeek optional String enum Possible values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY
paymentWeekOfMonth optional String enum Possible values: FIRST, SECOND, THIRD, FOURTH, LAST
paymentDateInMonth optional String max 2 digits Between 1 and 31
paymentCustomFrequency optional String enum Determines if a payment schedule is quarterly (payment every 3 months) or bi-annually (payment every 6 months). Must be present for CUSTOM paymentFrequency. Otherwise not present. Possible value: 3, 6.
twoPaymentsSamePeriod optional Boolean true/false Boolean that determines if two direct debits should be generated, in case subsequent payment date (paymentDayOfWeek, paymentWeekOfMonth, paymentDateInMonth) is later than the startDate.
settlementDateShiftoptional Boolean If true, settlement date shift logic is applied and start date can be shifted

Returns

Returns 201 Created response code and a JSON structure representing the created resource.

In case of failure, an error is returned within the error structure (see Errors section).

Create Schedule & Mandate

Example request

$ curl 'https://api.nuapay.com/schemes/abxq9kq52l/paymentschedules' \
  -u 81d8064d88c89947d7b96adb1c54c5328bd4d9cf567281db9d074ffda16d2d63: \
  -X POST -H 'Content-Type: application/json' -d \
  '{
  "paymentFrequency": "DAILY",
  "paymentType": "FIXED_LENGTH",
  "startDate": "2017-09-01",
  "numberOfPayments": 2,
  "paymentAmount": 9.9,
  "firstPaymentAmount": 1.1,
  "lastPaymentAmount": 9.9,
  "remittanceInformation": "remittanceInformation",
  "twoPaymentsSamePeriod": true,
  "settlementDateShift":true,
  "mandate": {
    "debtor": {
      "name": "Debtor Name",
      "address": {
        "line1": "Debtor Address Line1",
        "line2": "Debtor Address Line2",
        "town": " Debtor Town",
        "postCode": "123123",
        "state": "Debtor State",
        "country": "IE"
      },
      "language": "sk",
      "email": "debtor@email.com",
      "phoneNumber": "0360123123123",
      "mobileNumber": "0360321312312"
    },
    "mandateInfo": {
      "contractReference": "Contract Reference",
      "signatureLocation": "Signature Location",
      "signatureDate": "2015-07-21",
      "mandateType": "RCUR"
    },
        "debtorAccount": {
      "iban": "GB94SELN00999976543215",
      "bic": "SELNGB21"
    },
    "creditorAccount": {
      "iban": "GB47SELN00999912345678",
      "bic": "SELNGB21"
    }
  }
}'
CreatePaymentScheduleAndMandateRequest createPaymentScheduleAndMandateRequest = 
    new CreatePaymentScheduleAndMandateRequest()
        .withMandate(
            new Mandate()
                .withDebtor(
                    new Debtor()
                        .withName("Debtor Name")
                        .withAddress(
                            new Address()
                                .withLine1("Debtor Address Line1")
                                .withLine2("Debtor Address Line2")
                                .withTown("Debtor Town")
                                .withPostCode("123123")
                                .withState("Debtor State")
                                .withCountry("IE")
                            )
                        .withLanguage(CommunicationLanguage.fr_BE)
                        .withEmail("debtor@email.com")
                        .withPhoneNumber("0360123123123")
                        .withMobileNumber("0360321312312")
                        )
                .withMandateInfo(
                    new MandateInfo()
                        .withMandateId("1234567899")
                        .withContractReference("Contract Reference")
                        .withSignatureLocation("Signature Location")
                        .withSignatureDate(DateUtils.toDate("2017-09-01"))
                        .withMandateType(MandateType.RCUR)
                        )
                .withDebtorAccount(
                    new BasicAccount()
                        .withIban("GB94SELN00999976543215")
                    )
                .withCreditorAccount(
                    new BasicAccount()
                        .withIban("GB47SELN00999912345678")
                    )
            );

createPaymentScheduleAndMandateRequest.withPaymentSchedule(
    new PaymentSchedule()
        .withPaymentFrequency(PaymentFrequency.DAILY)
        .withPaymentType(PaymentType.FIXED_LENGTH)
        .withStartDate(DateUtils.toDate("2017-09-01"))
        .withNumberOfPayments(2)
        .withPaymentAmount(new BigDecimal("9.90"))
        .withFirstPaymentAmount(new BigDecimal("1.10"))
        .withLastPaymentAmount(new BigDecimal("9.90"))
        .withRemittanceInformation("remittanceInformation")
        .withTwoPaymentsSamePeriod(true));

PaymentScheduleAndMandateResource paymentScheduleAndMandateResource = 
    new PaymentScheduleServiceDefault(serviceConfig)
        .createPaymentScheduleAndMandate(
                "8b5g5pv82r", createPaymentScheduleAndMandateRequest)
                .getData();

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
   "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx/paymentschedules/8b5g5pv82r",
   "data":    {
      "id": "8b5g5pv82r",
      "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx/paymentschedules/8b5g5pv82r",
      "scheduleId": "518052",
      "paymentFrequency": "DAILY",
      "paymentType": "FIXED_LENGTH",
      "startDate": "2017-09-05",
      "numberOfPayments": 2,
      "paymentAmount": 9.9,
      "firstPaymentAmount": 1.1,
      "lastPaymentAmount": 9.9,
      "remittanceInformation": "remittanceInformation",
      "paymentDayOfWeek": null,
      "paymentWeekOfMonth": null,
      "paymentDateInMonth": null,
      "paymentCustomFrequency": null,
      "twoPaymentsSamePeriod": true,
      "paymentScheduleStatus": "ACTIVE",
      "links":       [
                  {
            "resourceType": "mandate",
            "id": "j29pj64jbx",
            "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx"
         },
                  {
            "resourceType": "scheme",
            "id": "abxq98zk2l",
            "uri": "/schemes/abxq98zk2l"
         }
      ]
   }
}

A POST request used to create payment schedule and mandate within the same request. A request must contain the application/json content type. In the request body you must provide a JSON structure describing the Payment Schedule and Mandate.

NOTE: Creation of payment schedule results in creation of one (OPEN_ENDED) or more (FIXED_LENGTH) direct debits associated to the schedule. Please use List Direct Debits service, filtering by scheduleId to get the list of created direct debits.

Definition

POST /schemes/{CS_ID}/paymentschedules

Arguments

JSON Path Type Description
root required Payment Schedule JSON structure describing payment schedule (See Payment Schedule Object section)
mandate required Mandate Object JSON structure describing payment schedule (See Mandate Object section)

Returns

Returns 201 Created response code and a JSON structure representing the Payment Schedule Object.

In case of failure, an error is returned within the error structure (see Errors section).

List Schedules

Example request

$ curl 'https://api.nuapay.com/schemes/schemes/abxq98zk2l/paymentschedules?paymentschedulestatus=ACTIVE&paymentschedulestatus=CANCELLED' \
   -u 81d8064d88c89947d7b96adb1c54c5328bd4d9cf567281db9d074ffda16d2d63: \
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("81d8064d88c89947d7b96adb1c54c5328bd4d9cf567281db9d074ffda16d2d63");

ListPaymentScheduleRequestParameters listPaymentScheduleRequestParameters = 
    new ListPaymentScheduleRequestParameters()
        .withPaymentStatus(PaymentScheduleStatus.ACTIVE);

List<PaymentScheduleResource> paymentScheduleResourcesList = 
    new PaymentScheduleServiceDefault(serviceConfiguration)
        .listPaymentSchedules("abxq98zk2l", "abxq98zk2l", listPaymentScheduleRequestParameters)
        .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "uri": "/schemes/abxq98zk2l/paymentschedules",
   "data":    [
            {
         "id": "8b5g5pv82r",
         "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx/paymentschedules/8b5g5pv82r",
         "scheduleId": "518052",
         "paymentFrequency": "DAILY",
         "paymentType": "FIXED_LENGTH",
         "startDate": "2017-09-05",
         "numberOfPayments": 2,
         "paymentAmount": 9.9,
         "firstPaymentAmount": 1.1,
         "lastPaymentAmount": 9.9,
         "remittanceInformation": "remittanceInformation",
         "paymentDayOfWeek": null,
         "paymentWeekOfMonth": null,
         "paymentDateInMonth": null,
         "paymentCustomFrequency": null,
         "twoPaymentsSamePeriod": true,
         "paymentScheduleStatus": "ACTIVE",
         "links":          [
                        {
               "resourceType": "mandate",
               "id": "j29pj64jbx",
               "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx"
            },
                        {
               "resourceType": "scheme",
               "id": "abxq98zk2l",
               "uri": "/schemes/abxq98zk2l"
            }
         ]
      },
            {
         "id": "j29pv8oabx",
         "uri": "/schemes/abxq98zk2l/mandates/ybo8zd8j2q/paymentschedules/j29pv8oabx",
         "scheduleId": "518050",
         "paymentFrequency": "DAILY",
         "paymentType": "FIXED_LENGTH",
         "startDate": "2017-09-05",
         "numberOfPayments": 2,
         "paymentAmount": 9.9,
         "firstPaymentAmount": 1.1,
         "lastPaymentAmount": 9.9,
         "remittanceInformation": "remittanceInformation",
         "paymentDayOfWeek": null,
         "paymentWeekOfMonth": null,
         "paymentDateInMonth": null,
         "paymentCustomFrequency": null,
         "twoPaymentsSamePeriod": true,
         "paymentScheduleStatus": "ACTIVE",
         "links":          [
                        {
               "resourceType": "mandate",
               "id": "ybo8zd8j2q",
               "uri": "/schemes/abxq98zk2l/mandates/ybo8zd8j2q"
            },
                        {
               "resourceType": "scheme",
               "id": "abxq98zk2l",
               "uri": "/schemes/abxq98zk2l"
            }
         ]
      }
   ],
   "page":    {
      "pageNumber": 1,
      "pageSize": 20,
      "totalElements": 2,
      "totalPages": 1
   },
   "sort": []
}

A GET request used to retrieve a collection of payment schedules. Can be used to list all payment schedules associated to a mandate, scheme or originator.

Definition

List all payment schedules under a mandate:

GET /schemes/{CS_ID}/mandates/{MANDATE_ID}/paymentschedules

List all payment schedules under a scheme:

GET /schemes/{CS_ID}/paymentschedules

List all payment schedules under an originator:

GET /paymentschedules

Arguments

Request param Description
paymentschedulestatusoptional One of ACTIVE, INACTIVE, CANCELLED. If the parameters is not provided, all payment schedules are listed. Note that the number of statuses can be queried within a single request by providing multiple occurances of the parameter.

Returns

Returns 200 OK response code and a JSON structure representing a collection of the Payment Schedule Objects.

In case of failure, an error is returned within the error structure (see Errors section).

View Schedule

Example request

$ curl 'https://api.nuapay.com/schemes/abxq98zk2l/mandates/j29pj64jbx/paymentschedules/8b5g5pv82r' \
   -u 81d8064d88c89947d7b96adb1c54c5328bd4d9cf567281db9d074ffda16d2d63: \
To be added

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx/paymentschedules/8b5g5pv82r",
   "data":    {
      "id": "8b5g5pv82r",
      "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx/paymentschedules/8b5g5pv82r",
      "scheduleId": "518052",
      "paymentFrequency": "DAILY",
      "paymentType": "FIXED_LENGTH",
      "startDate": "2017-09-05",
      "numberOfPayments": 2,
      "paymentAmount": 9.9,
      "firstPaymentAmount": 1.1,
      "lastPaymentAmount": 9.9,
      "remittanceInformation": "remittanceInformation",
      "paymentDayOfWeek": null,
      "paymentWeekOfMonth": null,
      "paymentDateInMonth": null,
      "paymentCustomFrequency": null,
      "twoPaymentsSamePeriod": true,
      "paymentScheduleStatus": "CANCELLED",
      "links":       [
                  {
            "resourceType": "mandate",
            "id": "j29pj64jbx",
            "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx"
         },
                  {
            "resourceType": "scheme",
            "id": "abxq98zk2l",
            "uri": "/schemes/abxq98zk2l"
         }
      ]
   }
}

A GET request used to view payment schedules.

Definition

GET /schemes/{CS_ID}/mandates/{MANDATE_ID}/paymentschedules/{SCHEDULE_ID}

Returns

Returns 200 OK response code and a JSON structure representing the Payment Schedule Object.

In case of failure, an error is returned within the error structure (see Errors section).

Cancel Schedule

Example request

$ curl 'https://api.nuapay.com/schemes/abxq98zk2l/mandates/j29pj64jbx/paymentschedules/8b5g5pv82r/cancel' \
  -u 81d8064d88c89947d7b96adb1c54c5328bd4d9cf567281db9d074ffda16d2d63: \
  -X POST -H 'Content-Type: application/json' \
  -d '{"operationReason":"Reason for cancellation"}'
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("81d8064d88c89947d7b96adb1c54c5328bd4d9cf567281db9d074ffda16d2d63");

CancelPaymentScheduleRequest cancelPaymentScheduleRequest = 
    new CancelPaymentScheduleRequest()
        .withOperationReason("Reason for cancellation");

PaymentScheduleResource paymentScheduleResponse = 
    new PaymentScheduleServiceDefault(serviceConfiguration)
        .cancelPaymentSchedule("8b5g5pv82r", "8b5g5pv82r", "8b5g5pv82r", cancelPaymentScheduleRequest).getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx/paymentschedules/8b5g5pv82r",
   "data":    {
      "id": "8b5g5pv82r",
      "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx/paymentschedules/8b5g5pv82r",
      "scheduleId": "518052",
      "paymentFrequency": "DAILY",
      "paymentType": "FIXED_LENGTH",
      "startDate": "2017-09-05",
      "numberOfPayments": 2,
      "paymentAmount": 9.9,
      "firstPaymentAmount": 1.1,
      "lastPaymentAmount": 9.9,
      "remittanceInformation": "remittanceInformation",
      "paymentDayOfWeek": null,
      "paymentWeekOfMonth": null,
      "paymentDateInMonth": null,
      "paymentCustomFrequency": null,
      "twoPaymentsSamePeriod": true,
      "paymentScheduleStatus": "CANCELLED",
      "links":       [
                  {
            "resourceType": "mandate",
            "id": "j29pj64jbx",
            "uri": "/schemes/abxq98zk2l/mandates/j29pj64jbx"
         },
                  {
            "resourceType": "scheme",
            "id": "abxq98zk2l",
            "uri": "/schemes/abxq98zk2l"
         }
      ]
   }
}

A POST request used to cancel payment schedules. A request must contain the application/json content type. In the request body you must provide a JSON structure describing the cancellation reason.

NOTE: Cancellation of payment schedule can result in cancellation of READY_FOR_EXPORT direct debits associated to this schedule. Please use List Direct Debits service, filtering by scheduleId and paymentStatus=CANCELLED to get the list of CANCELLED direct debits under the payment schedule.

Definition

POST /schemes/{CS_ID}/mandates/{MANDATE_ID}/paymentschedules/{SCHEDULE_ID}/cancel

Arguments

JSON Path Type Description
operationReasonoptional Stringmax 255 chars Reason for cancellation

Returns

Returns 200 OK response code and a JSON structure representing the altered Payment Schedule Object.

In case of failure, an error is returned within the error structure (see Errors section).

Credit Transfers APIs

This section contains descriptions of the APIs that allow you to manage Beneficiaries and Credit Transfer payments.

Beneficiaries

Beneficiaries are the Credit Transfer receivers, also known as the payees or creditors. They enable the funds transfer from the debtor’s (Originator/Merchant) account to a creditor’s account via Credit Transfer.

To access a beneficiary use the following URL:

https://api.nuapay.com/beneficiaries/{BENEFICIARY_ID}

where

Beneficiary Object

Example JSON structure describing a beneficiary

{
  "beneficiary": {
    "name": "Beneficiary Name",
    "address": {
      "line1": "Beneficiary Address Line1",
      "line2": "Beneficiary Address Line2",
      "town": "Beneficiary Town",
      "postCode": "123123",
      "state": "Beneficiary State",
      "country": "IE"
    },
    "language": "en",
    "email": "beneficiary@mail.com",
    "phoneNumber": "0360123123123",
    "mobileNumber": "0360321321321",
    "descriptionOfPurpose": "Description of Purpose"
  },
  "beneficiaryAccount": {
    "iban": "GB47SELN00999912345678",
    "domesticAccountNumber": "12345678",
    "domesticBankCode": null,
    "domesticBranchCode": "009999",
    "domesticCheckSum": null,
    "domesticAccountCountry": "GB",
    "bic": "SELNGB21"
  }
}
Path Type Description
beneficiary.namerequired Stringmax 70 chars Beneficiary Name
beneficiary.address.line1optional Stringmax 70 chars Beneficiary Address Line 1
beneficiary.address.line2optional Stringmax 70 chars Beneficiary Address Line 2
beneficiary.address.townoptional Stringmax 35 chars Beneficiary Address City/Town
beneficiary.address.postCodeoptional Stringmax 16 chars Beneficiary Address Post Code
beneficiary.address.stateoptional Stringmax 35 chars Beneficiary Address State/Province/County
beneficiary.address.countryoptional Stringenum ISO 3166-1 alpha-2 code
beneficiary.languageoptional Stringenum Communication language. One of (en, pt, nl, fr, it, es, de, sk, fr_BE, nl_BE)
beneficiary.emailoptional Stringmax 254 chars Beneficiary Email Address
beneficiary.phoneNumberoptional Stringmax 30 chars Beneficiary Phone Number
beneficiary.mobileNumberoptional Stringmax 30 chars Beneficiary Mobile Phone
beneficiary.descriptionOfPurposeoptional Stringmax 140 chars Purpose for the Beneficiary creation
beneficiaryAccount.ibanrequired Stringmax 34 chars Beneficiary Account IBAN
beneficiaryAccount.domesticAccountNumberoptional Stringmax 20 chars Beneficiary Account Domestic Account Number
beneficiaryAccount.domesticBankCodeoptional Stringmax 10 chars Beneficiary Account Bank Code
beneficiaryAccount.domesticBranchCodeoptional Stringmax 10 chars Beneficiary Account Domestic Branch Code
beneficiaryAccount.domesticCheckSumoptional Stringmax 2 chars Beneficiary Account Domestic Check Sum
beneficiaryAccount.domesticAccountCountryoptional StringEnum Beneficiary Account Domestic Account Country. 2 letter ISO country code
beneficiaryAccount.bicoptional Stringmax 11 chars Beneficiary Account BIC

Create Beneficiary

Example request

$ curl 'https://api.nuapay.com/beneficiaries' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X POST -H 'Content-Type: application/json' \
  -H 'JWS-Signature: eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCIsImlhdCIsImlzcyJdLCJraWQiOiIxNzk2NDU1MDI1IiwiaXNzIjoiT1VcdTAwM2ROdWFwYXkgQVBJLExcdTAwM2RMb25kb24sT1x1MDAzZE51YXBheSxDXHUwMDNkR0IsQ05cdTAwM2RvbWdkMzZkcG1rIiwiYWxnIjoiUlMyNTYiLCJpYXQiOjB9..wE6Cal9Hh62YKjjD4BbQpdPc1IwtteZ-ys3aiOWJDVLFdVxnJ0pEvcsK1nfRnfiiqCOB9PbapNrpG1e3jdWA3y-bm0KphLE52PEwhWZkD-x3WeFyxAeZT_Ma7Fem08k31ifMLMPYkXAyUDUfCao4DHJQHmOWQuDawYC4lH4qtiI' -d \
   '{
    "beneficiary": {
    "name": "Beneficiary Name",
    "address": {
      "line1": "Beneficiary Address Line1",
      "line2": "Beneficiary Address Line2",
      "town": "Beneficiary Town",
      "postCode": "123123",
      "state": "Beneficiary State",
      "country": "IE"
    },
    "language": "en",
    "email": "beneficiary@mail.com",
    "phoneNumber": "0360123123123",
    "mobileNumber": "0360321321321",
    "descriptionOfPurpose": "Description of Purpose"
  },
      "beneficiaryAccount": {
        "iban": "GB47SELN00999912345678",
        "bic": "SELNGB21"
      }
}'
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

CreateBeneficiaryRequest createBeneficiaryRequest = 
        new CreateBeneficiaryRequest()
            .withBeneficiary(
                    new Beneficiary()
                        .withBeneficiary(
                                new BeneficiaryDetails()
                                    .withName("Beneficiary Name")
                                    .withAddress(new Address()
                                            .withLine1("Beneficiary Address Line1")
                                            .withLine2("Beneficiary Address Line2")
                                            .withTown("Beneficiary Town")
                                            .withPostCode("123123")
                                            .withState("Beneficiary State")
                                            .withCountry("IE"))
                                    .withLanguage("en")
                                    .withEmail("beneficiary@mail.com")
                                    .withPhoneNumber("0360123123123")
                                    .withMobileNumber("0360321321321")
                                    .withDescriptionOfPurpose("Description of Purpose"))
                        .withBeneficiaryAccount(
                                new BasicAccount()
                                    .withIban("GB47SELN00999912345678")
                                    .withBic("SELNGB21"))
                        );

BeneficiaryResource beneficiaryResource = 
    new BeneficiariesServiceDefault(serviceConfig)
        .createBeneficiary(createBeneficiaryRequest)
        .getData();

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "uri": "/beneficiaries/46pkx7o9n5",
  "data": {
    "id": "46pkx7o9n5",
    "uri": "/beneficiaries/46pkx7o9n5",
    "beneficiary": {
      "name": "Beneficiary Name",
      "address": {
        "line1": "Beneficiary Address Line1",
        "line2": "Beneficiary Address Line2",
        "town": "Beneficiary Town",
        "postCode": "123123",
        "state": "Beneficiary State",
        "country": "IE"
      },
      "language": "en",
      "email": "beneficiary@mail.com",
      "phoneNumber": "0360123123123",
      "mobileNumber": "0360321321321",
      "descriptionOfPurpose": "Description of Purpose"
    },
    "beneficiaryAccount": {
      "iban": "GB47SELN00999912345678",
      "domesticAccountNumber": "12345678",
      "domesticBankCode": null,
      "domesticBranchCode": "009999",
      "domesticCheckSum": null,
      "domesticAccountCountry": "GB",
      "bic": "SELNGB21"
    }
  }
}

A POST request used to create beneficiaries. The request must contain the application/json content type. In the request body you must provide a JSON structure describing the Beneficiary.

Definition

POST /beneficiaries

Arguments

JSON Path Type Description
rootrequired Beneficiary JSON structure describing a beneficiary (See Beneficiary Object section)

Returns

Returns 201 Created response code, a URI to the created resource and a JSON structure representing the created resource.

In case of failure, an error is returned within the error structure (see Errors section).

Retrieve Beneficiary

Example request

$ curl 'https://api.nuapay.com/beneficiaries' 
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686:
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

BeneficiaryResource beneficiaryResource = 
    new BeneficiariesServiceDefault(serviceConfig)
        .retrieveBeneficiary(beneficiaryId).getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/beneficiaries/46pkx7o9n5",
  "data": {
    "id": "46pkx7o9n5",
    "uri": "/beneficiaries/46pkx7o9n5",
    "beneficiary": {
      "name": "Beneficiary Name",
      "address": {
        "line1": "Beneficiary Address Line1",
        "line2": "Beneficiary Address Line2",
        "town": "Beneficiary Town",
        "postCode": "123123",
        "state": "Beneficiary State",
        "country": "IE"
      },
      "language": "en",
      "email": "beneficiary@mail.com",
      "phoneNumber": "0360123123123",
      "mobileNumber": "0360321321321",
      "descriptionOfPurpose": "Description of Purpose"
    },
    "beneficiaryAccount": {
      "iban": "GB47SELN00999912345678",
      "domesticAccountNumber": "12345678",
      "domesticBankCode": null,
      "domesticBranchCode": "009999",
      "domesticCheckSum": null,
      "domesticAccountCountry": "GB",
      "bic": "SELNGB21"
    }
  }
}

A GET request used to retrieve a beneficiary.

Definition

GET /beneficiaries/{BENEFICIARY_ID}

Returns

Returns 200 OK response code and a JSON structure representing the queried beneficiary resource.

In case of failure, an error is returned within the error structure (see Errors section).

List Beneficiaries

Example request

$ curl 'https://api.nuapay.com/beneficiaries/?beneficiaryiban=GB47SELN00999912345678&beneficiaryname=Beneficiary' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

List<BeneficiarySummaryResource> beneficiaryList = 
    new BeneficiariesServiceDefault(serviceConfig)
        .listBeneficiaries().getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/beneficiaries",
  "data": [
    {
      "id": "w24y3olz2p",
      "uri": "/beneficiaries/w24y3olz2p",
      "beneficiary": {
        "name": "Beneficiary Name",
        "address": {
          "line1": "Beneficiary Address Line1",
          "line2": "Beneficiary Address Line2",
          "town": "Beneficiary Town",
          "postCode": "123123",
          "state": "Beneficiary State",
          "country": "IE"
        },
        "language": "en",
        "email": "beneficiary@mail.com",
        "mobileNumber": "0360321321321",
        "phoneNumber": "0360123123123",
        "descriptionOfPurpose": "Description of Purpose"
      },
      "beneficiaryAccount": {
        "iban": "GB47SELN00999912345678",
        "domesticAccountNumber": "12345678",
        "domesticBankCode": null,
        "domesticBranchCode": "009999",
        "domesticCheckSum": null,
        "domesticAccountCountry": "GB",
        "bic": "SELNGB21"
      }
    },
    {
      "id": "abxq9jak2l",
      "uri": "/beneficiaries/abxq9jak2l",
      "beneficiary": {
        "name": "Beneficiary Name",
        "address": {
          "line1": "Beneficiary Address Line1",
          "line2": "Beneficiary Address Line2",
          "town": "Beneficiary Town",
          "postCode": "123123",
          "state": "Beneficiary State",
          "country": "IE"
        },
        "language": "en",
        "email": "beneficiary@mail.com",
        "mobileNumber": "0360321321321",
        "phoneNumber": "0360123123123",
        "descriptionOfPurpose": "Description of Purpose"
      },
      "beneficiaryAccount": {
        "iban": "GB47SELN00999912345678",
        "domesticAccountNumber": "12345678",
        "domesticBankCode": null,
        "domesticBranchCode": "009999",
        "domesticCheckSum": null,
        "domesticAccountCountry": "GB",
        "bic": "SELNGB21"
      }
    }
  ],
  "page": {
    "pageNumber": 1,
    "pageSize": 20,
    "totalElements": 2,
    "totalPages": 1
  },
  "sort": []
}

A GET request used to retrieve a collection of beneficiaries. It can return beneficiaries associated to an organization.

Definition

To return all beneficiaries for an organization, use

GET /beneficiaries

Arguments

Request parameter Description
beneficiaryiban optional Beneficiary IBAN
beneficiaryname optional Beneficiary Name

Returns

Returns 200 OK response code and a JSON structure representing a collection of Beneficiary Objects.

In case of failure, an error is returned within the error structure (see Errors section).

Credit Transfers

Credit tranfers are the financial transactions associated to the beneficiary.

To access credit transfers use the following URL:

https://api.nuapay.com/beneficiaries/{BENEFICIARY_ID}/credittransfers/{CT_ID}

where

Credit Transfer Object

Example JSON structure describing credit transfer


{
  "originatorIban": "GB94SELN00999976543215",
  "requestedExecutionDate": "2016-10-14",
  "paymentAmount": 5000.01,
  "paymentCurrency": "EUR",
  "endToEndId": "12345678901330w4",
  "remittanceInformation": "Remittance info",
  "paymentStatus": "READY_FOR_EXPORT",
  "paymentScheme": "SCT",
  "type": "STANDARD",
  "beneficiaryName": "Beneficiary Name",
  "beneficiaryAccount": {
    "iban": "GB47SELN00999912345678",
    "domesticAccountNumber": "12345678",
    "domesticBankCode": null,
    "domesticBranchCode": "009999",
    "domesticCheckSum": null,
    "domesticAccountCountry": "GB",
    "bic": "SELNGB21"
  },
  "ultimateCreditor": {
    "name": "ultimate Creditor",
    "organisationId": {
      "bicOrBei": "SELNGB21",
      "other": {
        "id": "id",
        "schemeName": {
          "code": "BANK",
          "proprietary": "proprietary"          
        },
        "issuer": "issuer"
      }
    },
    "privateId": {
      "dateAndPlaceOfBirth": {
        "birthDate": null,
        "cityOfBirth": null,
        "countryOfBirth": null
      },
      "other": {
        "id": null,
        "schemeName": {
          "code": "BANK",
          "proprietary": "proprietary"
        },
        "issuer": null
      }
    }
  },
  "ultimateDebtor": {
    "name": "ultimate Debtor",
    "organisationId": {
      "bicOrBei": null,
      "other": {
        "id": null,
        "schemeName": {
          "code": "BANK",
          "proprietary": "proprietary"
        },
        "issuer": null
      }
    },
    "privateId": {
      "dateAndPlaceOfBirth": {
        "birthDate": "2000-05-09",
        "cityOfBirth": "city",
        "countryOfBirth": "IE"
      },
      "other": {
        "id": "id",
        "schemeName": {
          "code": "BANK",
          "proprietary": "proprietary"
        },
        "issuer": "issuer"
      }
    }
  }
}

Path Type Description
originatorIbanoptional Stringmax 34 chars Originator IBAN from which the credit transfer originated. To provide domestic format of account instead of originatorIban populate originatorAccount.
originatorAccount.domesticAccountNumberoptional Stringmax 20 chars Originator Domestic Account Number
originatorAccount.domesticBankCodeoptional Stringmax 10 chars Originator Account Bank Code
originatorAccount.domesticBranchCodeoptional Stringmax 10 chars Originator Account Domestic Branch Code
originatorAccount.domesticCheckSumoptional Stringmax 2 chars Originator Account Domestic Check Sum
originatorAccount.domesticAccountCountryoptional StringEnum Originator Account Domestic Account Country. 2 letter ISO country code
originatorAccount.bicoptional Stringmax 11 chars Originator Account BIC
requestedExecutionDateoptional Dateyyyy-mm-dd Requested Execution Date for the credit transfer. If not provided it will be set to the current processing date.
paymentAmountrequired Numbermax 12 chars Payment Amount. Max length without decimals is 9 digits. Decimal separator is .. Max two decimal places allowed.
paymentCurrencyrequired Stringenum Credit Transfer Currency. Currently supported: GBP and EUR
endToEndIdoptional Stringmax 35 chars Payment Reference
remittanceInformationoptional Stringmax 140 chars Remittance Information
paymentStatusoptional Stringenum Return parameter only. One of, READY_FOR_EXPORT, REJECTED, RECALLED, EXPORTED, ACCEPTED.
paymentScheme
typeoptional stringenum Type of Credit Transfer. Determine which of available execution options (payment schemes) will be used to process the transfer. Note that standard payment scheme is always available. Other schemes will be used only when available. Response payment scheme determine which scheme was actually used to process the payment. One of, STANDARD and EXPRESS
beneficiaryNameoptional stringmax 70 chars Response parameter only. Name of Beneficiary. Used to filter credit transfers with provided beneficiary name. Full name and partial name is supported.
beneficiaryAccount.ibanrequired Stringmax 34 chars Response parameter only. Beneficiary Account IBAN
beneficiaryAccount.domesticAccountNumberoptional Stringmax 20 chars Response parameter only. Beneficiary Account Domestic Account Number
beneficiaryAccount.domesticBankCodeoptional Stringmax 10 chars Response parameter only. Beneficiary Account Bank Code
beneficiaryAccount.domesticBranchCodeoptional Stringmax 10 chars Response parameter only. Beneficiary Account Domestic Branch Code
beneficiaryAccount.domesticCheckSumoptional Stringmax 2 chars Response parameter only. Beneficiary Account Domestic Check Sum
beneficiaryAccount.domesticAccountCountryoptional StringEnum Response parameter only. Beneficiary Account Domestic Account Country. 2 letter ISO country code
beneficiaryAccount.bicoptional Stringmax 11 chars Response parameter only. Beneficiary Account BIC
ultimateCreditor.nameoptional stringmax 70 chars The ultimate creditor name.
ultimateCreditor.organisationId.bicOrBeioptional stringmax 11 chars The ultimate creditor bic.
ultimateCreditor.organisationId.other.idoptional stringmax 35 chars Organization ID Other ID.
ultimateCreditor.organisationId.schemeName.codeoptional stringenum Organization ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalOrganisationIdentification1Code'. Cannot be used at the same time as organisationIdOtherSchemeNameProprietary.
ultimateCreditor.organisationId.schemeName.proprietaryoptional stringmax 35 chars Organization ID Other Scheme Name Proprietary. Cannot be used at the same time as organisationIdOtherSchemeNameCode.
ultimateCreditor.organisationId.other.issueroptional stringmax 35 chars Organization ID Other Issuer
ultimateCreditor.privateId.dateAndPlaceOfBirth.birthDateoptional Dateyyyy-mm-dd Ultimate Creditor Birth Date
ultimateCreditor.privateId.dateAndPlaceOfBirth.cityOfBirthoptional stringmax 35 chars City of Birth
ultimateCreditor.privateId.dateAndPlaceOfBirth.countryOfBirthoptional stringenum ISO3166-1 alpha-2 country code.
ultimateCreditor.privateId.other.idoptional stringmax 35 chars Private ID Other ID
ultimateCreditor.privateId.other.schemeName.codeoptional stringenum Private ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalPersonIdentification1Code'.
ultimateCreditor.privateId.other.schemeName.proprietaryoptional stringmax 35 chars Private ID Other Scheme Name Proprietary
ultimateCreditor.privateId.other.issueroptional stringmax 35 chars Private ID Other Issuer
ultimateDebtor.nameoptional stringmax 70 chars The ultimate debtor name.
ultimateDebtor.organisationId.bicOrBeioptional stringmax 11 chars The ultimate debtor bic.
ultimateDebtor.organisationId.other.idoptional stringmax 35 chars Organization ID Other ID.
ultimateDebtor.organisationId.schemeName.codeoptional stringenum Organization ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalOrganisationIdentification1Code'. Cannot be used at the same time as organisationIdOtherSchemeNameProprietary.
ultimateDebtor.organisationId.schemeName.proprietaryoptional stringmax 35 chars Organization ID Other Scheme Name Proprietary. Cannot be used at the same time as organisationIdOtherSchemeNameCode.
ultimateDebtor.organisationId.other.issueroptional stringmax 35 chars Organization ID Other Issuer
ultimateDebtor.privateId.dateAndPlaceOfBirth.birthDateoptional Dateyyyy-mm-dd Ultimate Creditor Birth Date
ultimateDebtor.privateId.dateAndPlaceOfBirth.cityOfBirthoptional stringmax 35 chars City of Birth
ultimateDebtor.privateId.dateAndPlaceOfBirth.countryOfBirthoptional stringenum ISO3166-1 alpha-2 country code.
ultimateDebtor.privateId.other.idoptional stringmax 35 chars Private ID Other ID
ultimateDebtor.privateId.other.schemeName.codeoptional stringenum Private ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalPersonIdentification1Code'.
ultimateDebtor.privateId.other.schemeName.proprietaryoptional stringmax 35 chars Private ID Other Scheme Name Proprietary
ultimateDebtor.privateId.other.issueroptional stringmax 35 chars Private ID Other Issuer

Create Credit Transfer

Example request

$ curl 'https://api.nuapay.com/beneficiaries/abxq9ox92l/credittransfers' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X POST -H 'Content-Type: application/json' \
  -H 'JWS-Signature: eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCIsImlhdCIsImlzcyJdLCJraWQiOiIxNzk2NDU1MDI1IiwiaXNzIjoiT1VcdTAwM2ROdWFwYXkgQVBJLExcdTAwM2RMb25kb24sT1x1MDAzZE51YXBheSxDXHUwMDNkR0IsQ05cdTAwM2RvbWdkMzZkcG1rIiwiYWxnIjoiUlMyNTYiLCJpYXQiOjB9..wE6Cal9Hh62YKjjD4BbQpdPc1IwtteZ-ys3aiOWJDVLFdVxnJ0pEvcsK1nfRnfiiqCOB9PbapNrpG1e3jdWA3y-bm0KphLE52PEwhWZkD-x3WeFyxAeZT_Ma7Fem08k31ifMLMPYkXAyUDUfCao4DHJQHmOWQuDawYC4lH4qtiI' -d \
   '{
   "originatorIban":"GB94SELN00999976543215",
   "requestedExecutionDate":"2016-10-14",
   "paymentAmount":5000.01,
   "paymentCurrency":"EUR",
   "endToEndId":"12345678901330w4",
   "remittanceInformation":"Remittance info"
}'
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

CreateCreditTransferRequest createCreditTransferRequest = 
    new CreateCreditTransferRequest()
        .withOriginatorIban("GB94SELN00999976543215")
        .withRequestedExecutionDate(DateUtils.toDate("2016-10-14"))
        .withPaymentAmount(new BigDecimal("5000.01"))
        .withPaymentCurrency("EUR")
        .withEndToEndId("12345678901330w4")
        .withRemittanceInformation("Remittance info");

CreditTransferResource creditTransferResource = 
    new CreditTransferServiceDefault(serviceConfiguration)
        .createCreditTransfer("abxq9ox92l", createCreditTransferRequest).getData();

Example response

{
  "uri": "/beneficiaries/abxq9ox92l/credittransfers/a2av38kz2w",
  "data": {
    "id": "a2av38kz2w",
    "uri": "/beneficiaries/abxq9ox92l/credittransfers/a2av38kz2w",
    "originatorIban": "GB94SELN00999976543215",
    "requestedExecutionDate": "2016-10-14",
    "paymentAmount": 5000.01,
    "paymentCurrency": "EUR",
    "endToEndId": "12345678901330w4",
    "remittanceInformation": "Remittance info",
    "paymentStatus": "READY_FOR_EXPORT",
    "beneficiaryName": "Beneficiary Name",
    "beneficiaryAccount": {
      "iban": "GB47SELN00999912345678",
      "domesticAccountNumber": "12345678",
      "domesticBankCode": null,
      "domesticBranchCode": "009999",
      "domesticCheckSum": null,
      "domesticAccountCountry": "GB",
      "bic": "SELNGB21"
    }
  }
}

A POST request used to create credit transfers. A request must contain the application/json content type. In the request body you must provide a JSON structure describing the Credit Transfer.

Definition

POST /beneficiaries/{BENEFICIARY_ID}/credittransfers

Arguments

Body param Type Description
originatorIbanoptional Stringmax 34 chars Originator IBAN from which the credit transfer originated. To provide domestic format of account instead of originatorIban populate originatorAccount.
originatorAccount.domesticAccountNumberoptional Stringmax 20 chars Originator Domestic Account Number
originatorAccount.domesticBankCodeoptional Stringmax 10 chars Originator Account Bank Code
originatorAccount.domesticBranchCodeoptional Stringmax 10 chars Originator Account Domestic Branch Code
originatorAccount.domesticCheckSumoptional Stringmax 2 chars Originator Account Domestic Check Sum
originatorAccount.domesticAccountCountryoptional StringEnum Originator Account Domestic Account Country. 2 letter ISO country code
originatorAccount.bicoptional Stringmax 11 chars Originator Account BIC
requestedExecutionDateoptional Dateyyyy-mm-dd Requested Execution Date for the credit transfer. If not provided it will be set to the current processing date.
paymentAmountrequired Numbermax 12 chars Payment Amount. Max length without decimals is 9 digits. Decimal separator is .. Max two decimal places allowed.
paymentCurrencyrequired Stringenum Credit Transfer Currency. Currently supported: GBP and EUR
endToEndIdoptional Stringmax 35 chars Payment Reference
remittanceInformationoptional Stringmax 140 chars Remittance Information
typeoptional stringenum Type of Credit Transfer. Determine which of available execution options (payment schemes) will be used to process the transfer. Note that standard payment scheme is always available. Other schemes will be used only when available. Response payment scheme determine which scheme was actually used to process the payment. One of, STANDARD or EXPRESS
ultimateCreditor.nameoptional stringmax 70 chars The ultimate creditor name.
ultimateCreditor.organisationId.bicOrBeioptional stringmax 11 chars The ultimate creditor bic.
ultimateCreditor.organisationId.other.idoptional stringmax 35 chars Organization ID Other ID.
ultimateCreditor.organisationId.schemeName.codeoptional stringenum Organization ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalOrganisationIdentification1Code'. Cannot be used at the same time as organisationIdOtherSchemeNameProprietary.
ultimateCreditor.organisationId.schemeName.proprietaryoptional stringmax 35 chars Organization ID Other Scheme Name Proprietary. Cannot be used at the same time as organisationIdOtherSchemeNameCode.
ultimateCreditor.organisationId.other.issueroptional stringmax 35 chars Organization ID Other Issuer
ultimateCreditor.privateId.dateAndPlaceOfBirth.birthDateoptional Dateyyyy-mm-dd Ultimate Creditor Birth Date
ultimateCreditor.privateId.dateAndPlaceOfBirth.cityOfBirthoptional stringmax 35 chars City of Birth
ultimateCreditor.privateId.dateAndPlaceOfBirth.countryOfBirthoptional stringenum ISO3166-1 alpha-2 country code.
ultimateCreditor.privateId.other.idoptional stringmax 35 chars Private ID Other ID
ultimateCreditor.privateId.other.schemeName.codeoptional stringenum Private ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalPersonIdentification1Code'.
ultimateCreditor.privateId.other.schemeName.proprietaryoptional stringmax 35 chars Private ID Other Scheme Name Proprietary
ultimateCreditor.privateId.other.issueroptional stringmax 35 chars Private ID Other Issuer
ultimateDebtor.nameoptional stringmax 70 chars The ultimate debtor name.
ultimateDebtor.organisationId.bicOrBeioptional stringmax 11 chars The ultimate debtor bic.
ultimateDebtor.organisationId.other.idoptional stringmax 35 chars Organization ID Other ID.
ultimateDebtor.organisationId.schemeName.codeoptional stringenum Organization ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalOrganisationIdentification1Code'. Cannot be used at the same time as organisationIdOtherSchemeNameProprietary.
ultimateDebtor.organisationId.schemeName.proprietaryoptional stringmax 35 chars Organization ID Other Scheme Name Proprietary. Cannot be used at the same time as organisationIdOtherSchemeNameCode.
ultimateDebtor.organisationId.other.issueroptional stringmax 35 chars Organization ID Other Issuer
ultimateDebtor.privateId.dateAndPlaceOfBirth.birthDateoptional Dateyyyy-mm-dd Ultimate Creditor Birth Date
ultimateDebtor.privateId.dateAndPlaceOfBirth.cityOfBirthoptional stringmax 35 chars City of Birth
ultimateDebtor.privateId.dateAndPlaceOfBirth.countryOfBirthoptional stringenum ISO3166-1 alpha-2 country code.
ultimateDebtor.privateId.other.idoptional stringmax 35 chars Private ID Other ID
ultimateDebtor.privateId.other.schemeName.codeoptional stringenum Private ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalPersonIdentification1Code'.
ultimateDebtor.privateId.other.schemeName.proprietaryoptional stringmax 35 chars Private ID Other Scheme Name Proprietary
ultimateDebtor.privateId.other.issueroptional stringmax 35 chars Private ID Other Issuer

Returns

Returns 201 Created response code and a JSON structure representing the created resource.

In case of failure, an error is returned within the error structure (see Errors section).

Retrieve Credit Transfer

Example request

$ curl 'https://api.nuapay.com/beneficiaries/abxq9ox92l/credittransfers/a2av38kz2w' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: 
ServiceConfiguration serviceConfig = new ServiceConfiguration();
serviceConfig.setApiKey("bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686");

CreditTransferResource creditTransferResource = 
    new CreditTransferServiceDefault(serviceConfiguration)
        .retrieveCreditTransfer("abxq9ox92l", "a2av38kz2w").getData();    

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/beneficiaries/abxq9ox92l/credittransfers/a2av38kz2w",
  "data": {
    "id": "j29p3kxabx",
    "uri": "/beneficiaries/abxq9ox92l/credittransfers/a2av38kz2w",
    "originatorIban": "GB94SELN00999976543215",
    "requestedExecutionDate": "2016-12-14",
    "paymentAmount": 5000.01,
    "paymentCurrency": "EUR",
    "endToEndId": "12345678901330w4",
    "remittanceInformation": "Remittance info",
    "paymentStatus": "READY_FOR_EXPORT",
    "beneficiaryName": "Beneficiary Name",
    "beneficiaryAccount": {
      "iban": "GB47SELN00999912345678",
      "domesticAccountNumber": "12345678",
      "domesticBankCode": null,
      "domesticBranchCode": "009999",
      "domesticCheckSum": null,
      "domesticAccountCountry": "GB",
      "bic": "SELNGB21"
    }
  }
}

A GET request used to retrieve credit transfers.

Definition

GET /beneficiaries/{BENEFICIARY_ID}/credittransfers/{CT_ID}

Returns

Returns 200 OK response code and a JSON structure representing the queried credit transfer resource.

In case of failure, an error is returned within the error structure (see Errors section).

List Credit Transfers GET

Example request

$ curl 'https://api.nuapay.com/beneficiaries/abxq9ox92l/credittransfers/a2av38kz2w?executiondatefrom=2015-07-29&executiondateto=2015-08-28' \
   -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \

To be updated

Example response

{
  "uri": "/beneficiaries/abxq9ox92l/credittransfers",
  "data": [
    {
      "id": "a2av38kz2w",
      "uri": "/beneficiaries/abxq9ox92l/credittransfers/a2av38kz2w",
      "originatorIban": "GB51RCWB00999901159383",
      "requestedExecutionDate": "2016-10-14",
      "paymentAmount": 5000.01,
      "paymentCurrency": "EUR",
      "endToEndId": "12345678901330w4",
      "remittanceInformation": "Remittance info",
      "paymentStatus": "READY_FOR_EXPORT",
      "beneficiaryName": "Beneficiary Name",
      "beneficiaryAccount": {
        "iban": "GB47SELN00999912345678",
        "domesticAccountNumber": "12345678",
        "domesticBankCode": null,
        "domesticBranchCode": "009999",
        "domesticCheckSum": null,
        "domesticAccountCountry": "GB",
        "bic": "SELNGB21"
      }
    },
    {
      "id": "a2av38kz2w",
      "uri": "/beneficiaries/abxq9ox92l/credittransfers/a2av38kz2w",
      "originatorIban": "GB51RCWB00999901159383",
      "requestedExecutionDate": "2016-10-14",
      "paymentAmount": 5000.01,
      "paymentCurrency": "EUR",
      "endToEndId": "12345678901330w4",
      "remittanceInformation": "Remittance info",
      "paymentStatus": "READY_FOR_EXPORT",
      "beneficiaryName": "Beneficiary Name",
      "beneficiaryAccount": {
        "iban": "GB47SELN00999912345678",
        "domesticAccountNumber": "12345678",
        "domesticBankCode": null,
        "domesticBranchCode": "009999",
        "domesticCheckSum": null,
        "domesticAccountCountry": "GB",
        "bic": "SELNGB21"
      }
    }
  ],
  "page": {
    "pageNumber": 1,
    "totalPages": 3,
    "pageSize": 20,
    "totalElements": 10
  },
  "sort": []
}

A GET request used to retrieve a collection of credit transfers. This request can be used to list all credit transfers associated to a beneficiary or originator.

Definition

List all credit transfers under a beneficiary:

GET /beneficiaries/{BENEFICIARY_ID}/credittransfers

List all credit transfers under an originator:

GET /credittransfers

Arguments

Request param Description
executiondatefromoptional Format yyyy-mm-dd
executiondatetooptional Format yyyy-mm-dd
beneficiarynameoptional Name of Beneficiary. Used to filter credit transfers with provided beneficiary name. Full name and partial name is supported.
beneficiaryibanoptional Beneficiary IBAN. Used to filter credit transfers with provided beneficiary IBAN
paymentstatusoptional One of, ALL, READY_FOR_EXPORT, REJECTED, RECALLED, EXPORTED, ACCEPTED. Note number of statuses can be queried within single request by providing multiple occurence of the parameter.
originatoribanoptional Originator IBAN. Used to filter credit transfers with provided originator IBAN.

Returns

Returns 200 OK response code and a JSON structure representing a collection of credit transfer objects.

In case of failure, an error is returned within the error structure (see Errors section).

List Credit Transfers POST

Example request

$ curl 'https://api.nuapay.com/accounts/w24y3dya2p/credittransfers/list' -i -X POST  \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -H 'Content-Type: application/json' \
  -d '{
  "page": {
    "pageNumber": 1,
    "pageSize": 1
  },
  "filter": {
    "executionDateFrom": "2017-09-21",
    "executionDateTo": "2017-10-28",
    "paymentStatus": "ACCEPTED",
    "beneficiaryName": "Beneficiary Name",
    "beneficiaryAccount": "GB47SELN00999912345678"
  }
}'

To be updated

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/accounts/w24y3dya2p/credittransfers/list",
  "data": [
    {
      "id": "j29pjrvdbx",
      "uri": "/beneficiaries/j29pjqknbx/credittransfers/j29pjrvdbx",
      "originatorIban": "GB25SELN00999988796624",
      "requestedExecutionDate": "2017-10-27",
      "paymentAmount": 5000.01,
      "paymentCurrency": "EUR",
      "endToEndId": "563456456",
      "remittanceInformation": "Remittance info",
      "paymentStatus": "ACCEPTED",
      "beneficiaryName": "Beneficiary Name",
      "beneficiaryAccount": {
        "iban": "GB47SELN00999912345678",
        "domesticAccountNumber": "12345678",
        "domesticBankCode": null,
        "domesticBranchCode": "009999",
        "domesticCheckSum": null,
        "domesticAccountCountry": "GB",
        "bic": "SELNGB21"
      }
    }
  ],
  "page": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalElements": 1,
    "totalPages": 1
  },
  "sort": []
}

A POST request is used to retrieve collection of credit transfers under given account in secured way. Allows to pass query parameters in JSON body object. A request must contain the application/json content type.

Definition

POST accounts/{ACCOUNT_ID}/credittransfers/list

Arguments

Body param Description
filter.executionDateFromoptional Format yyyy-mm-dd
filter.executionDateTooptional Format yyyy-mm-dd
filter.beneficiaryNameoptional Name of Beneficiary. Used to filter credit transfers with provided beneficiary name. Full name and partial name is supported.
filter.beneficiaryAccountoptional At least 3 characters of Beneficiary IBAN or Account Number. Used to filter credit transfers with provided beneficiary IBAN
filter.paymentStatusoptional One of, ALL, READY_FOR_EXPORT, REJECTED, RECALLED, EXPORTED, ACCEPTED. Note number of statuses can be queried within single request by providing multiple occurence of the parameter.

Returns

Returns 200 OK response code and a JSON structure representing the queried resource.

In case of failure, an error is returned within the error structure (see Errors section).

Create Credit Transfer and Beneficiary

Example request

$ curl 'https://api.nuapay.com/credittransfers' -i -X POST  \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -H 'Content-Type: application/json' \
  -H 'JWS-Signature: eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCIsImlhdCIsImlzcyJdLCJraWQiOiIxNzk2NDU1MDI1IiwiaXNzIjoiT1VcdTAwM2ROdWFwYXkgQVBJLExcdTAwM2RMb25kb24sT1x1MDAzZE51YXBheSxDXHUwMDNkR0IsQ05cdTAwM2RvbWdkMzZkcG1rIiwiYWxnIjoiUlMyNTYiLCJpYXQiOjB9..wE6Cal9Hh62YKjjD4BbQpdPc1IwtteZ-ys3aiOWJDVLFdVxnJ0pEvcsK1nfRnfiiqCOB9PbapNrpG1e3jdWA3y-bm0KphLE52PEwhWZkD-x3WeFyxAeZT_Ma7Fem08k31ifMLMPYkXAyUDUfCao4DHJQHmOWQuDawYC4lH4qtiI' -d '{
    "originatorIban": "GB94SELN00999976543215",
    "requestedExecutionDate": "2016-10-14",
    "paymentAmount": 5000.01,
    "paymentCurrency": "EUR",
    "endToEndId": "12345678901330w4",
    "remittanceInformation": "Remittance info",
    "type": "STANDARD",
    "beneficiary": {
      "name": "Beneficiary Name",
      "address": {
        "line1": "Beneficiary Address Line1",
        "line2": "Beneficiary Address Line2",
        "town": "Beneficiary Town",
        "postCode": "123123",
        "state": "Beneficiary State",
        "country": "IE"
      },
      "language": "en",
      "email": "beneficiary@mail.com",
      "phoneNumber": "0360123123123",
      "mobileNumber": "0360321321321",
      "descriptionOfPurpose": "Description of Purpose"
    },
    "beneficiaryAccount": {
      "iban": "GB47SELN00999912345678",
      "bic": "SELNGB21"
    },
    "ultimateCreditor": {
      "name": "ultimate Creditor",
      "organisationId": {
        "bicOrBei": "SELNGB21"
      }
    },
    "ultimateDebtor": {
      "name": "ultimate Debtor",
      "privateId": {
        "dateAndPlaceOfBirth": {
          "birthDate": "2000-05-09",
          "cityOfBirth": "city",
          "countryOfBirth": "IE"
        }
      }
    }
  }'

To be updated

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/beneficiaries/abxq9ox92l/credittransfers/a2av38kz2w",
  "data": {
    "id": "a2av38kz2w",
    "uri": "/beneficiaries/abxq9ox92l/credittransfers/a2av38kz2w",
    "originatorIban": "GB94SELN00999976543215",
    "requestedExecutionDate": "2016-10-14",
    "paymentAmount": 5000.01,
    "paymentCurrency": "EUR",
    "endToEndId": "12345678901330w4",
    "remittanceInformation": "Remittance info",
    "paymentStatus": "READY_FOR_EXPORT",
    "paymentScheme": "SCT",
    "type": "STANDARD",
    "beneficiaryName": "Beneficiary Name",
    "beneficiaryAccount": {
      "iban": "GB47SELN00999912345678",
      "domesticAccountNumber": "12345678",
      "domesticBankCode": null,
      "domesticBranchCode": "009999",
      "domesticCheckSum": null,
      "domesticAccountCountry": "GB",
      "bic": "SELNGB21"
    },
    "ultimateCreditor": {
      "name": "ultimate Creditor",
      "organisationId": {
        "bicOrBei": "SELNGB21",
      },
    },
    "ultimateDebtor": {
      "name": "ultimate Debtor",
      "privateId": {
        "dateAndPlaceOfBirth": {
          "birthDate": "2000-05-09",
          "cityOfBirth": "city",
          "countryOfBirth": "IE"
        },
      }
    }
  },
  "links": [
    {
      "resourceType": "beneficiary",
      "id": "abxqg83n2l",
      "uri": "/beneficiaries/abxqg83n2l"
    }
  ]
}

A POST request used to create credit transfers and beneficiary if none exists. A request must contain the application/json content type. In the request body you must provide a JSON structure describing both the Credit Transfer and Beneficiary.

Definition

POST /credittransfers

Arguments

Body param Type Description
beneficiary required Object JSON structure describing the Beneficiary (See beneficiary in Beneficiary Object section)
beneficiaryAccount required Object JSON structure describing the Beneficiary Account (See beneficiaryAccount in Beneficiary Object section)
originatorIbanoptional Stringmax 34 chars Originator IBAN from which the credit transfer originated. To provide domestic format of account instead of originatorIban populate originatorAccount.
originatorAccount.domesticAccountNumberoptional Stringmax 20 chars Originator Domestic Account Number
originatorAccount.domesticBankCodeoptional Stringmax 10 chars Originator Account Bank Code
originatorAccount.domesticBranchCodeoptional Stringmax 10 chars Originator Account Domestic Branch Code
originatorAccount.domesticCheckSumoptional Stringmax 2 chars Originator Account Domestic Check Sum
originatorAccount.domesticAccountCountryoptional StringEnum Originator Account Domestic Account Country. 2 letter ISO country code
originatorAccount.bicoptional Stringmax 11 chars Originator Account BIC
requestedExecutionDateoptional Dateyyyy-mm-dd Requested Execution Date for the credit transfer. If not provided it will be set to the current processing date.
paymentAmountrequired Numbermax 12 chars Payment Amount. Max length without decimals is 9 digits. Decimal separator is .. Max two decimal places allowed.
paymentCurrencyrequired Stringenum Credit Transfer Currency. Currently supported: GBP and EUR
endToEndIdoptional Stringmax 35 chars Payment Reference
remittanceInformationoptional Stringmax 140 chars Remittance Information
typeoptional stringenum Type of Credit Transfer. Determine which of available execution options (payment schemes) will be used to process the transfer. Note that standard payment scheme is always available. Other schemes will be used only when available. Response payment scheme determine which scheme was actually used to process the payment. One of, STANDARD or EXPRESS
ultimateCreditor.nameoptional stringmax 70 chars The ultimate creditor name.
ultimateCreditor.organisationId.bicOrBeioptional stringmax 11 chars The ultimate creditor bic.
ultimateCreditor.organisationId.other.idoptional stringmax 35 chars Organization ID Other ID.
ultimateCreditor.organisationId.schemeName.codeoptional stringenum Organization ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalOrganisationIdentification1Code'. Cannot be used at the same time as organisationIdOtherSchemeNameProprietary.
ultimateCreditor.organisationId.schemeName.proprietaryoptional stringmax 35 chars Organization ID Other Scheme Name Proprietary. Cannot be used at the same time as organisationIdOtherSchemeNameCode.
ultimateCreditor.organisationId.other.issueroptional stringmax 35 chars Organization ID Other Issuer
ultimateCreditor.privateId.dateAndPlaceOfBirth.birthDateoptional Dateyyyy-mm-dd Ultimate Creditor Birth Date
ultimateCreditor.privateId.dateAndPlaceOfBirth.cityOfBirthoptional stringmax 35 chars City of Birth
ultimateCreditor.privateId.dateAndPlaceOfBirth.countryOfBirthoptional stringenum ISO3166-1 alpha-2 country code.
ultimateCreditor.privateId.other.idoptional stringmax 35 chars Private ID Other ID
ultimateCreditor.privateId.other.schemeName.codeoptional stringenum Private ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalPersonIdentification1Code'.
ultimateCreditor.privateId.other.schemeName.proprietaryoptional stringmax 35 chars Private ID Other Scheme Name Proprietary
ultimateCreditor.privateId.other.issueroptional stringmax 35 chars Private ID Other Issuer
ultimateDebtor.nameoptional stringmax 70 chars The ultimate debtor name.
ultimateDebtor.organisationId.bicOrBeioptional stringmax 11 chars The ultimate debtor bic.
ultimateDebtor.organisationId.other.idoptional stringmax 35 chars Organization ID Other ID.
ultimateDebtor.organisationId.schemeName.codeoptional stringenum Organization ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalOrganisationIdentification1Code'. Cannot be used at the same time as organisationIdOtherSchemeNameProprietary.
ultimateDebtor.organisationId.schemeName.proprietaryoptional stringmax 35 chars Organization ID Other Scheme Name Proprietary. Cannot be used at the same time as organisationIdOtherSchemeNameCode.
ultimateDebtor.organisationId.other.issueroptional stringmax 35 chars Organization ID Other Issuer
ultimateDebtor.privateId.dateAndPlaceOfBirth.birthDateoptional Dateyyyy-mm-dd Ultimate Creditor Birth Date
ultimateDebtor.privateId.dateAndPlaceOfBirth.cityOfBirthoptional stringmax 35 chars City of Birth
ultimateDebtor.privateId.dateAndPlaceOfBirth.countryOfBirthoptional stringenum ISO3166-1 alpha-2 country code.
ultimateDebtor.privateId.other.idoptional stringmax 35 chars Private ID Other ID
ultimateDebtor.privateId.other.schemeName.codeoptional stringenum Private ID Other Scheme Name Code, ENUM based on ISO external code set 'ExternalPersonIdentification1Code'.
ultimateDebtor.privateId.other.schemeName.proprietaryoptional stringmax 35 chars Private ID Other Scheme Name Proprietary
ultimateDebtor.privateId.other.issueroptional stringmax 35 chars Private ID Other Issuer

Returns

Returns 201 OK response code and a JSON structure representing the created resource.

In case of failure, an error is returned within the error structure (see Errors section).

Nuapay Accounts APIs

This section contains descriptions of the APIs that allow you to manage Nyapay Accounts.

Accounts

Account Object

Example JSON structure describing an account

{
  "name" : "Test Account",
  "currency": "EUR",
  "type": "SUB_ACCOUNT",
  "masterAccountIban": "GB14SELN00999950563593",
  "identification": {
    "domesticAccountNumber": "76543215",
    "domesticBankCode": null,
    "domesticBranchCode": "009999",
    "domesticAccountChecksum": "94",
    "domesticAccountCountry": "GB",
    "iban": "GB94SELN00999976543215",
    "bic": "SELNGB21"
  },
  "secondaryIdentification": null,
  "links": [
    {
      "resourceType": "balances",
      "id": null,
      "uri": "/accounts/cdxt17zj1l/balances"
    },
    {
      "resourceType": "beneficiary",
      "id": "j29pkqiaby",
      "uri": "/beneficiaries/j29pkqiaby"
    }      
  ]
}
Path Type Description
currency String enum Account currency, one of EUR or GBP
type String enum Account type allows either CURRENT_ACCOUNT, for general use, or SUB_ACCOUNT, for interactions with sub-accounts
masterAccountIban String max 34 chars Master account to link sub-account to. Must be the same currency as sub-account being created, has to exist under the same Originator and must be of type 'CURRENT_ACCOUNT'
identification.domesticAccountNumber String max 20 chars Domestic account number to be provided if BBAN is to be used
identification.domesticBankCode String max 10 chars Domestic bank code to be provided if BBAN is to be used
identification.domesticBranchCode String max 10 chars Domestic branch code to be provided if BBAN is to be used
identification.domesticAccountChecksum String max 2 chars Domestic account checksum to be provided if BBAN is to be used
identification.domesticAccountCountry String enum ISO country code, it is requried if BBAN is provided and IBAN is not
identification.iban String max 35 chars Account IBAN
identification.bic String max 11 chars BIC of the financial institution the account is held in
secondaryIdentification String max 12 chars Account secondary identification
links.resourceType String enum Type of linked resource, one of BALANCES or BENEFICIARY
links.id String Encoded Id of linked resource
links.uri String URI to the linked resource

Create Account

Example request

$ curl 'https://api.nuapay.com/accounts' -i \
  -u 442a42e412074e5c805fd3ca8e38767d14505e065fd61e33b1a50f86a3143b1e: \
  -X POST -H 'Content-Type: application/json' \
  -d '{ 
        "name" : "Test Account", 
        "currency" : "EUR", 
        "type" : "SUB_ACCOUNT", 
        "masterAccountIban": "GB14SELN00999950563593", 
        "settlementIban" : "GB57TURU00999921499476" 
    }'

To be updated

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "uri":"/accounts/62wnl9352y",
  "data":{
    "id":"62wnl9352y",
    "uri":"/accounts/62wnl9352y",
    "name":"Test Account",
    "currency":"EUR",
    "type":"SUB_ACCOUNT",
    "identification":{
      "iban":"GB31SELN00999919884612",
      "domesticAccountNumber":"19884612",
      "domesticBankCode":null,
      "domesticBranchCode":"009999",
      "domesticCheckSum":"31",
      "domesticAccountCountry":"GB",
      "bic":"SELNGB21"
    },
    "secondaryIdentification":null,
    "links":[
      {
        "resourceType":"balances",
        "id":null,
        "uri":"/accounts/62wnl9352y/balances"
      },
      {
        "resourceType":"beneficiary",
        "id":"ym3n37oyb3",
        "uri":"/beneficiaries/ym3n37oyb3"
      },
      {
        "resourceType":"account",
        "id":"dmq8a4laml",
        "uri":"/accounts/dmq8a4laml"
      }
    ]
  }
}

A POST request is used to register or create account depending on the Originator configuration. A request must contain the application/json content type.

Definition

POST /accounts

Arguments

JSON Path Type Description
name required String max 50 chars Account name given by customer
currency required String enum Account currency, one of EUR or GBP
type String enum Account type allows either CURRENT_ACCOUNT, for general use, or SUB_ACCOUNT, for interactions with sub-accounts
masterAccountIban String max 34 chars Master account to link sub-account to. Must be the same currency as sub-account being created, has to exist under the same Originator and must be of type 'CURRENT_ACCOUNT'
identification.domesticAccountNumber optional String max 20 chars Domestic account number, to be provided if BBAN is to be used
identification.domesticBankCode optional String max 10 chars Domestic bank code, to be provided if BBAN is to be used
identification.domesticBranchCode optional String max 10 chars Domestic branch code, to be provided if BBAN is to be used
identification.domesticAccountChecksum optional String max 2 chars Domestic account checksum, to be provided if BBAN is to be used
identification.domesticAccountCountry optional String enum ISO country code, account secondary identification, requried if BBAN is provided
identification.iban optional String max 35 chars Account IBAN
identification.bic optional String max 11 chars Financial institution BIC
secondaryIdentification String max 12 chars Allows the definition of an internal account name for identification of the Account
settlementIban String max 35 chars Settlement IBAN to be linked to account created as part of this request, should only be used when creating a Nuapay Virtual Account

Returns

Returns 201 Created response code and a JSON structure with URI and 'account' object.

In case of failure, an error is returned within the error structure (see Errors section).

List Accounts

Example request

$ curl 'https://api.nuapay.com/accounts/list' -i -X POST  \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -X POST -H 'Content-Type: application/json' \
  -d '{
    "page": {
        "pageNumber": 1,
        "pageSize": 10
    },
    "filter": {
        "queryString": "GB94"
    }
    }'

To be updated

Example response

HTTP/1.1 200 Ok
Content-Type: application/json

{  
  "uri":"/accounts/list",
  "data":[  
    {  
    "id":"dmq8a4laml",
    "uri":"/accounts/dmq8a4laml",
    "name":"Case 3 ",
    "currency":"EUR",
    "type":"CURRENT_ACCOUNT",
    "identification":{  
      "iban":"GB14SELN00999950563593",
      "domesticAccountNumber":"50563593",
      "domesticBankCode":null,
      "domesticBranchCode":"009999",
      "domesticCheckSum":"14",
      "domesticAccountCountry":"GB",
      "bic":"SELNGB21"
    },
    "secondaryIdentification":null,
    "links":[  
      {  
        "resourceType":"balances",
        "id":null,
        "uri":"/accounts/dmq8a4laml/balances"
      },
      {  
        "resourceType":"beneficiary",
        "id":"ym3n37oyb3",
        "uri":"/beneficiaries/ym3n37oyb3"
      }
    ]
    }
  ],
  "page":{  
    "pageNumber":1,
    "pageSize":10,
    "totalElements":1,
    "totalPages":1
  },
  "sort":[ ]
}

A POST request is used to retrieve collection of accounts in secured way. Allows to pass query parameters in JSON body object. A request must contain the application/json content type.

Definition

POST /accounts/list

Arguments

JSON Path Type Description
page.pageNumber optional Number Page number to be returned. Default to '1'.
page.pageSize optional Number Number of elements to be returned on single page. Default to '20' elements.
filter.queryString optional String max 50 chars Free text query string that searches in 'name' and 'identification.iban' fields. Requries 3 characters minimum

Returns

Returns 200 OK response code and a JSON structure with URI and 'account' object.

In case of failure, an error is returned within the error structure (see Errors section).

View Account

Example request

$ curl 'https://api.nuapay.com/accounts/dmq8a4laml' -i  \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: 

To be updated

Example response

HTTP/1.1 200 Ok
Content-Type: application/json

{  
  "uri":"/accounts/dmq8a4laml",
  "data":{  
    "id":"dmq8a4laml",
    "uri":"/accounts/dmq8a4laml",
    "name":"Case 3 ",
    "currency":"EUR",
    "type":"CURRENT_ACCOUNT",
    "identification":{  
      "iban":"GB14SELN00999950563593",
      "domesticAccountNumber":"50563593",
      "domesticBankCode":null,
      "domesticBranchCode":"009999",
      "domesticCheckSum":"14",
      "domesticAccountCountry":"GB",
      "bic":"SELNGB21"
    },
    "secondaryIdentification":null,
    "links":[  
      {  
        "resourceType":"balances",
        "id":null,
        "uri":"/accounts/dmq8a4laml/balances"
      },
      {  
        "resourceType":"beneficiary",
        "id":"ym3n37oyb3",
        "uri":"/beneficiaries/ym3n37oyb3"
      }
    ]
  }
}

A GET request is used to retrieve patricular account object identified by resource ID returned by Create or List Accounts services.

Definition

GET /accounts/{ACCOUNT_ID}

Returns

Returns 200 OK response code and a JSON structure with URI and 'account' object.

In case of failure, an error is returned within the error structure (see Errors section).

Balances

Balances Object

Example JSON structure describing an account

{
  "balance": {
    "amount": 100.00,
    "currency": "EUR",
    "creditDebitIndicator": "CREDIT",
    "type": "BOOKED_BALANCE"
  },
  "timestamp": "1502717756000"
}
Path Type Description
balance.amount Number Max 15 digits Absolute balance amount
balance.currency String enum Balance currency, one of 'EUR' or 'GBP'
balance.creditDebitIndicator String enum Indicates whether balance amount is a positive - CREDIT or negative - DEBIT value
balance.type String enum Balance type one of, BOOKED_BALANCE or AVAILABLE_BALANCE
timestamp Number The date the balance was queried for. Note: This is not the request date and may be past or future date

List Account Balances

Example request

$ curl 'https://api.nuapay.com/accounts/rmpa5ve4m6/balances?dateuntil=1513083481996' -i  \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: 

To be updated

Path Type Description
dateuntil Number Epoch timestamp format date until which the balance should be returned. Default: current date.

Example response

HTTP/1.1 200 Ok
Content-Type: application/json

{
   "uri": "/accounts/rmpa5ve4m6/balances",
   "data":    [
            {
         "uri": "/accounts/rmpa5ve4m6/balances",
         "balance":          {
            "amount": 1000,
            "currency": "EUR",
            "creditDebitIndicator": "CREDIT",
            "type": "BOOKED_BALANCE"
         },
         "timestamp": "1513083481996"
      },
            {
         "uri": "/accounts/rmpa5ve4m6/balances",
         "balance":          {
            "amount": 1000,
            "currency": "EUR",
            "creditDebitIndicator": "CREDIT",
            "type": "AVAILABLE_BALANCE"
         },
         "timestamp": "1513083481996"
      }
   ]
}

A GET request is used to retrieve patricular account balances

Definition

GET /accounts/{ACCOUNT_ID}/balances

Returns

Returns 200 OK response code and a JSON structure with URI and 'balance' object.

In case of failure, an error is returned within the error structure (see Errors section).

Transactions

Transaction is a resource that describes a posting to an account that results in an increase or decrease to a balance of the account.

To access transaction use following URL: https://api.nuapay.com/accounts/{accountId}/transactions/{transactionId}

where

Transaction Object

Example JSON structure describing transaction

{
  "id": "bzja3ye692",
  "uri": "/accounts/w24y3dzo2p/transactions/bzja3ye692",
  "postingDate": "2018-02-07",
  "transactionType": "OUTGOING_CREDIT_TRANSFER",
  "valueDate": "2018-02-07",
  "amount": 1,
  "currency": "EUR",
  "creditDebitIndicator": "DEBIT",
  "purposeCode": null,
  "endToEndId": "endToEndId1",
  "mandateReference": null,
  "ultimateCreditorId": null,
  "ultimateCreditorName": null,
  "ultimateDebtorId": null,
  "ultimateDebtorName": null,
  "reasonCode": null,
  "reasonProprietary": null,
  "bulkMessageId": null,
  "batchReference": null,
  "unstructuredRemittanceInformation": "unstructuredRemittanceInformation",
  "remittanceInfo": "remittanceInfo",
  "schemeType": null,
  "numberOfTransactions": null,
  "totalAmount": null,
  "balanceAfterTransaction": {
    "amount": 23781.16,
    "currency": "EUR",
    "creditDebitIndicator": "CREDIT",
    "type": "BOOKED_BALANCE"
  },
  "counterparty": {
    "name": "Originator Name",
         "address":          {
            "line1": "Originator Address Line1",
            "line2": "Originator Address Line2",
            "postalCode": "123123",
            "town": "Originator Town",
            "country": "PL"
         },
    "account": {
      "iban": "GB89SELN00999940483361",
      "bic": "SELNGB21"
    }
  }
}
Path Type Description
postingDate Dateyyyy-mm-dd Date when booking happened on the account
transactionType Stringenum Returns one of Transaction Types
valueDate Dateyyyy-mm-dd Transaction value date.
amount Numbermax 15 digits Transaction Amount. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places.
currency Stringenum ISO Currency Code: EUR, GBP
creditDebitIndicator Stringenum CREDIT or DEBIT
counterparty.name String max 70 chars Counterparty Name
counterparty.address.line1 String max 70 chars Counterparty address line 1.
counterparty.address.line2 String max 70 chars Counterparty address line 2.
counterparty.address.postalCode String max 16 chars Counterparty address postcode.
counterparty.address.town String max 70 chars Counterparty address town.
counterparty.address.country Stringenum ISO 3166-1 alpha-2 code
counterparty.account.iban Stringmax 34 chars Counterparty account in IBAN format.
counterparty.account.bic Stringmax 11 chars Counterparty bank BIC code.
purposeCode Stringenum Returns a Purpose Code, for example SALA for a Salary payment.
endToEndId Stringmax 35 chars Transaction End To End ID.
mandateReference Stringmax 35 chars Related Mandate Reference. Direct Debits only.
ultimateCreditorId Stringmax 35 chars Ultimate Creditor ID.
ultimateCreditorName String max 70 chars Ultimate Creditor name.
utimateDebtorId Stringmax 35 chars Ultimate Debtor ID.
ultimateDebtorName String max 70 chars Ultimate Debtor name
reasonCode Stringenum Returned only for R-Transactions. One of SEPA Reason Codes.
reasonProprietary Stringmax 35 chars Returned only for R-Transactions.
bulkMessageId Stringmax 35 chars Bulk reference the transaction was exported in.
batchReference Stringmax 35 chars Batch reference the transaction was exported in.
unstructuredRemittanceInformation Stringmax 140 chars Related Transaction remittance information
remittanceInfo Stringmax 140 chars This is posting related remittance information
schemeType Stringenum Returned only for Direct Debits. One of: CORE,B2B,BACS
numberOfTransactions Number Number of Transactions in the batch. Used only for Batch Postings
totalAmount Numbermax 15 digits Total amount of transactions in the Batch. Used only for Batch Postings
balanceAfterTransaction.amount Numbermax 15 digits Balance After Transaction. Max length without decimals is 12 digits. Decimal separator is .. Max two decimal places.
balanceAfterTransaction.currency Numbermax 15 digits Balance currency, one of EUR or GBP
balanceAfterTransaction.creditDebitIndicator Numbermax 15 digits Indicates whether balance amount is a positive - CREDIT or negative - DEBIT value
balanceAfterTransaction.type Stringenum Balance type, in transaction object always BOOKED_BALANCE

Transaction Types

Following are the transcation types in Transaction Object

Transaction Transaction Type Debit Credit Indicator Counterparty
Credit Transfer Bank Reject CREDIT_TRANSFER_BANK_REJECT CREDIT Debtor
Direct Debit Batch DIRECT_DEBIT_BATCH CREDIT Creditor
Direct Debit Bank Cancellation DIRECT_DEBIT_BANK_CANCELLATION DEBIT Creditor
Direct Debit Reject DIRECT_DEBIT_REJECT DEBIT Creditor
Direct Debit Reversal DIRECT_DEBIT_REVERSAL DEBIT Creditor
Direct Debit Return DIRECT_DEBIT_RETURN DEBIT Creditor
Direct Debit Refusal DIRECT_DEBIT_REFUSAL DEBIT Creditor
Direct Debit Authorized Refund DIRECT_DEBIT_AUTHORIZED_REFUND DEBIT Creditor
Direct Debit Unauthorized Refund DIRECT_DEBIT_AUTHORIZED_REFUND DEBIT Creditor
Outgoing Credit Transfer OUTGOING_CREDIT_TRANSFER DEBIT Creditor
Availability Fee AVAILABILITY_FEE DEBIT N/A for Fees
Direct Debit Batch Transactions Fee DIRECT_DEBIT_BATCH_TRANSACTIONS_FEE DEBIT N/A for Fees
Direct Debit R-Transaction Fee DIRECT_DEBIT_RTRANSACTIONS_FEE DEBIT N/A for Fees
Credit Transfer Reject Fee CREDIT_TRANSFER_RTRANSACTION_FEE DEBIT N/A for Fees
Incoming Credit Transfer INCOMING_CREDIT_TRANSFER CREDIT Debtor
Credit Transfer Recall CREDIT_TRANSFER_RECALL CREDIT Debtor
E-Mandate Setup Fee - CORE Scheme CORE_EMANDATE_SETUP_FEE DEBIT N/A for Fees
E-Mandate Setup Fee - BACS Scheme BACS_EMANDATE_SETUP_FEE DEBIT N/A for Fees
E-Mandate Setup Fee - B2B Scheme B2B_EMANDATE_SETUP_FEE DEBIT N/A for Fees
E-Mandate Fee - CORE Scheme CORE_EMANDATE_FEE DEBIT N/A for Fees
E-Mandate Fee - BACS Scheme BACS_EMANDATE_FEE DEBIT N/A for Fees
E-Mandate Fee - B2B Scheme B2B_EMANDATE_FEE DEBIT N/A for Fees
Outgoing Credit Transfer Fee OUTGOING_CREDIT_TRANSFER_FEE DEBIT N/A for Fees
Incoming Credit Transfer Fee INCOMING_CREDIT_TRANSFER_FEE DEBIT N/A for Fees
Credit Transfer Recall Fee CREDIT_TRANSFER_RECALL_FEE DEBIT N/A for Fees
Overdraft Fee OVERDRAFT_FEE DEBIT N/A for Fees

View Transaction

Example request

$ curl 'https://api.nuapay.com/accounts/qj29pkgnbx/transactions/ym37ygrg23' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: 
To be updated

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "uri": "/accounts/qj29pkgnbx/transactions/ym37ygrg23",
   "data":    {
      "id": "ym37ygrg23",
      "uri": "/accounts/qj29pkgnbx/transactions/ym37ygrg23",
      "postingDate": "2017-07-21",
      "transactionType": "INCOMING_CREDIT_TRANSFER",
      "valueDate": "2017-07-21",
      "amount": 5000,
      "currency": "EUR",
      "creditDebitIndicator": "CREDIT",
      "purposeCode": "SALA",
      "endToEndId": "endToEndId",
      "mandateReference": null,
      "ultimateCreditorId": null,
      "ultimateCreditorName": null,
      "ultimateDebtorId": null,
      "ultimateDebtorName": null,
      "reasonCode": null,
      "reasonProprietary": null,
      "bulkMessageId": "pacs008-msg-id",
      "batchReference": null,
      "unstructuredRemittanceInformation": "unstructuredRemittanceInformation",
      "remittanceInfo": "Incoming CT",
      "schemeType": null,
      "numberOfTransactions": null,
      "totalAmount": null,
      "counterparty":       {
         "name": "Debtor Name",
         "address":          {
            "line1": "Debtor Address Line1",
            "line2": "Debtor Address Line2",
            "postalCode": "123123",
            "town": "Debtor Town",
            "country": "PL"
         },
         "account":          {
            "iban": "GB94SELN00999976543215",
            "bic": "SELNGB21"
         }
      }
   }
}

A GET request is used to retrieve Transaction under Account.

Definition

GET /accounts/{accountId}/transactions/{transactionId}

Returns

Returns 200 OK response code and a JSON structure representing the queried transaction resource.

In case of failure, an error is returned within the error structure (see Errors section).

List Transactions

Example request

$ curl 'https://api.nuapay.com/accounts/qj29pkgnbx/transactions/list'  -i -X POST \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -H 'Content-Type: application/json' \
  -d '{
      "page": {
        "pageNumber": 1,
        "pageSize": 1
      },
      "filter": {
        "valuedateFrom": 1500542067000,
        "valuedateTo": 1518517758000,
        "amountFrom": 10,
        "amountTo": 50000
      }
    }'
To be updated

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/accounts/w24y3dzo2p/transactions",
  "data": [
    {
      "id": "bzja3ye692",
      "uri": "/accounts/w24y3dzo2p/transactions/bzja3ye692",
      "postingDate": "2018-02-07",
      "transactionType": "OUTGOING_CREDIT_TRANSFER",
      "valueDate": "2018-02-07",
      "amount": 1,
      "currency": "EUR",
      "creditDebitIndicator": "DEBIT",
      "purposeCode": null,
      "endToEndId": "endToEndId1",
      "mandateReference": null,
      "ultimateCreditorId": null,
      "ultimateCreditorName": null,
      "ultimateDebtorId": null,
      "ultimateDebtorName": null,
      "reasonCode": null,
      "reasonProprietary": null,
      "bulkMessageId": null,
      "batchReference": null,
      "unstructuredRemittanceInformation": "unstructuredRemittanceInformation",
      "remittanceInfo": "remittanceInfo",
      "schemeType": null,
      "numberOfTransactions": null,
      "totalAmount": null,
      "balanceAfterTransaction": {
        "amount": 23781.16,
        "currency": "EUR",
        "creditDebitIndicator": "CREDIT",
        "type": "BOOKED_BALANCE"
      },
      "counterparty": {
        "name": "Originator Name",
        "address": {
          "line1": "Originator Address Line1",
          "line2": "Originator Address Line2",
          "postalCode": "123123",
          "town": "Originator Town",
          "country": "PL"
        },
        "account": {
          "iban": "GB89SELN00999940483361",
          "bic": "SELNGB21"
        }
      }
    }
  ],
  "page": {
    "pageNumber": 1,
    "pageSize": 20,
    "totalElements": 1,
    "totalPages": 1
  },
  "sort": []
}

A POST request is used to retrieve List of Transactions under Account.

Definition

POST /accounts/{accountId}/transactions/list

Arguments

JSON Path Type Description
filter.valuedateFrom optional String timestamp Epoch timestamp format date from which the transactions should be returned.
filter.valuedateTo optional String timestamp Epoch timestamp format date until which the balance should be returned.
filter.amountFrom optional String max 10 digits and 2 decimals Minimal amount of transaction included in the response. Max amount 9,999,999,999.99
filter.amountTo optional String max 10 digits and 2 decimals Maximum amount of transaction included in the response. Max amount 9,999,999,999.99

Returns

Returns 200 OK response code and a JSON structure representing the queried transactions list resource.

In case of failure, an error is returned within the error structure (see Errors section).

Transfers

The 'transfers' endpoint allows the user to transfer funds between thier own Nuapay accounts.

To access 'transfers' use the following URL:

https://api.nuapay.com/transfers

Transfers Object

Example JSON structure describing the transfers object

{
  "requestedExecutionDate": "2018-03-22",
  "remittanceInfo": "Meeting Example",
  "amount": 20.01,
  "currency": "EUR",
  "accountFrom": {
    "domesticAccountNumber": "88796624",
    "domesticAccountCountry": "GB",
    "domesticBankCode": null,
    "domesticBranchCode": "009999",
    "domesticAccountChecksum": "25",
    "iban": "GB25SELN00999988796624",
    "bic": "SELNGB21"
  },
  "accountTo": {
    "domesticAccountNumber": "76543215",
    "domesticAccountCountry": "GB",
    "domesticBankCode": null,
    "domesticBranchCode": "009999",
    "domesticAccountChecksum": "94",
    "iban": "GB94SELN00999976543215",
    "bic": "SELNGB21"
  }
}
Path Type Description
requestedExecutionDaterequired Dateyyyy-mm-dd Requested Execution Date for the credit transfer, should always be the current processing date. If not provided it will be set to the current processing date.
remittanceInfooptional Stringmax 140 chars Remittance Information
amountrequired Numbermax 12 chars Transfer amount. Max length without decimals is 9 digits. Decimal separator is .. Max two decimal places allowed.
currencyrequired Stringenum Transfer currency. Currently supported: GBP and EUR
accountFrom.domesticAccountNumberconditional Stringmax 20 chars Domestic account number of account to transfer funds from, user either IBAN or domestic account number
accountFrom.domesticAccountCountryoptional StringEnum Domestic account country. 2 letter ISO country code, use with domestic account number
accountFrom.domesticBankCodeoptional Stringmax 10 chars Domestic account bank code of account to transfer funds from, use with domestic account number
accountFrom.domesticBranchCodeoptional Stringmax 10 chars Domestic account branch code of account to transfer funds from, use with domestic account number
accountFrom.domesticChecksumoptional Stringmax 2 chars Domestic account check sum of account to transfer funds from, use with domestic account number
accountFrom.ibanconditional Stringmax 34 chars IBAN of account to transfer funds from, user either IBAN or domestic account number
accountFrom.bicoptional Stringmax 11 chars BIC of account to transfer funds from
accountTo.domesticAccountNumberconditional Stringmax 20 chars Domestic account number of account to transfer funds to, user either IBAN or domestic account number
accountTo.domesticAccountCountryoptional StringEnum Domestic account country. 2 letter ISO country code, use with domestic account number
accountTo.domesticBankCodeoptional Stringmax 10 chars Domestic account bank code of account to transfer funds to, use with domestic account number
accountTo.domesticBranchCodeoptional Stringmax 10 chars Domestic account branch code of account to transfer funds to, use with domestic account number
accountTo.domesticChecksumoptional Stringmax 2 chars Domestic account check sum of account to transfer funds to, use with domestic account number
accountTo.ibanconditional Stringmax 34 chars IBAN of account to transfer funds to, user either IBAN or domestic account number
accountTo.bicoptional Stringmax 11 chars BIC of account to transfer funds to

Transfers

Example request

$ curl 'https://api.nuapay.com/transfers' \
  -i \
  -u bdf120b4a3cc0c52c0d40f7c291adac3ae95bb4371ba0c0d7fc5a8afe2c27b52: \
  -X POST -H 'Content-Type: application/json' \
  -d \
  '{ 
    "requestedExecutionDate": "2018-05-30", 
    "remittanceInfo": "Meeting Example", 
    "amount": 0.01, 
    "currency": "EUR", 
    "accountFrom": { 
      "iban": "GB45TURU00999990882628" 
    },
    "accountTo": {
      "iban": "GB73TURU00999928450014" 
    } 
  }'
To be updated

Example response

{  
   "uri":"/transfers/j29p3dpdbx",
   "data":{  
      "id":"j29p3dpdbx",
      "uri":"/transfers/j29p3dpdbx",
      "requestedExecutionDate":"2018-05-30",
      "remittanceInfo":"Meeting Example",
      "amount":0.01,
      "currency":"EUR",
      "accountFrom":{  
         "domesticAccountNumber":"90882628",
         "domesticAccountCountry":"GB",
         "domesticBankCode":null,
         "domesticBranchCode":"009999",
         "domesticCheckSum":"45",
         "iban":"GB45TURU00999990882628",
         "bic":"TURUIE21"
      },
      "accountTo":{  
         "domesticAccountNumber":"28450014",
         "domesticAccountCountry":"GB",
         "domesticBankCode":null,
         "domesticBranchCode":"009999",
         "domesticCheckSum":"73",
         "iban":"GB73TURU00999928450014",
         "bic":"TURUIE21"
      },
      "links":[]
   }
}

A POST request used to transfer funds between thier own Nuapay accounts. A request must contain the application/json content type. In the request body you must provide a JSON structure describing the transfer.

Definition

POST /transfers

Arguments

JSON Path Type Description
requestedExecutionDaterequired Dateyyyy-mm-dd Requested Execution Date for the credit transfer, should always be the current processing date. If not provided it will be set to the current processing date.
remittanceInfooptional Stringmax 140 chars Remittance Information
amountrequired Numbermax 12 chars Transfer amount. Max length without decimals is 9 digits. Decimal separator is .. Max two decimal places allowed.
currencyrequired Stringenum Transfer currency. Currently supported: GBP and EUR
accountFrom.domesticAccountNumberconditional Stringmax 20 chars Domestic account number of account to transfer funds from, user either IBAN or domestic account number
accountFrom.domesticAccountCountryoptional StringEnum Domestic account country. 2 letter ISO country code, use with domestic account number
accountFrom.domesticBankCodeoptional Stringmax 10 chars Domestic account bank code of account to transfer funds from, use with domestic account number
accountFrom.domesticBranchCodeoptional Stringmax 10 chars Domestic account branch code of account to transfer funds from, use with domestic account number
accountFrom.domesticChecksumoptional Stringmax 2 chars Domestic account check sum of account to transfer funds from, use with domestic account number
accountFrom.ibanconditional Stringmax 34 chars IBAN of account to transfer funds from, user either IBAN or domestic account number
accountTo.domesticAccountNumberconditional Stringmax 20 chars Domestic account number of account to transfer funds from, user either IBAN or domestic account number
accountTo.domesticAccountCountryoptional StringEnum Domestic account country. 2 letter ISO country code, use with domestic account number
accountTo.domesticBankCodeoptional Stringmax 10 chars Domestic account bank code of account to transfer funds from, use with domestic account number
accountTo.domesticBranchCodeoptional Stringmax 10 chars Domestic account branch code of account to transfer funds from, use with domestic account number
accountTo.domesticChecksumoptional Stringmax 2 chars Domestic account check sum of account to transfer funds from, use with domestic account number
accountTo.ibanconditional Stringmax 34 chars IBAN of account to transfer funds from, user either IBAN or domestic account number

Returns

Returns 201 Created response code and a JSON structure representing the created resource.

In case of failure, an error is returned within the error structure (see Errors section).

Other APIs

This section contains descriptions of additional APIs, which can be used in conjunction with the Direct Debit APIs.

Validate Account Number

Validate Account object

Example JSON structure describing an account

{
    "iban" : "GB94SELN00999976543215",
    "domesticAccountNumber" : "76543215",
    "accountCountry" : "GB",
    "domesticBankCode" : "009999",
    "domesticBranchCode" : null,
    "domesticCheckSum" : "94",
    "bic" : "SELNGB21"
  }
Path Type Description
ibanoptional Stringmax 34 chars Valid IBAN structure
domesticAccountNumber required String max 70 chars Domestic account number
accountCountry required String enum 2 letter ISO country code
domesticBankCode optional String max 35 chars Domestic bank code
domesticBranchCode optional String max 35 chars Domestic branch code
domesticCheckSum optional String max 35 chars Domestic checksum
bicoptional String max 11 chars BIC Code

Validate Domestic Account

Example request

$ curl 'https://api.nuapay.com/iban/validate' -i -X POST  \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -H 'Content-Type: application/json' \
  -d '{"domesticAccountNumber":"76543215", 
       "accountCountry":"GB", 
       "domesticBranchCode":"009999", 
       "domesticCheckSum":"94" 
      }'

ValidateAccountRequest validateAccountRequest = 
        new ValidateAccountRequest()
            .withAccount(
                    new Account()
                        .withDomesticAccountNumber("76543215")
                        .withAccountCountry("GB")
                        .withDomesticBranchCode("009999")
                        .withDomesticCheckSum("94"));

AccountResource accountResource = 
        accountsService.validateAccount(validateAccountRequest)
        .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/iban/validate",
  "data": {
    "uri": "/iban/validate",
    "iban": "GB94SELN00999976543215",
    "domesticAccountNumber": "76543215",
    "accountCountry": "GB",
    "domesticBankCode": null,
    "domesticBranchCode": "009999",
    "domesticCheckSum": null,
    "bic": "SELNGB21XXX"
  }
}

A POST request used to validate accounts. A request must contain the application/json content type. In the request body you must provide a JSON structure containing domestic account information.

Definition

POST /iban/validate

Arguments

JSON Path Type Description
domesticAccountNumber required String max 70 chars Domestic account number
accountCountry required String enum 2 letter ISO country code
domesticBankCode optional String max 35 chars Domestic bank code
domesticBranchCode optional String max 35 chars Domestic branch code
domesticCheckSum optional String max 35 chars Domestic checksum

Must not be mixed with iban property of Validate Account object.

Returns

Returns 200 OK response code and a JSON structure with URI and Validate Account object.

In case of failure, an error is returned within the error structure (see Errors section).

Validate IBAN

Example request

$ curl 'https://api.nuapay.com/iban/validate' -i -X POST  \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -H 'Content-Type: application/json' \
  -d '{"iban":"GB94SELN00999976543215"
      }'

ValidateAccountRequest validateAccountRequest = 
        new ValidateAccountRequest()
            .withAccount(new Account().withIban("GB94SELN00999976543215"));

AccountResource accountResource = 
        accountsService.validateAccount(validateAccountRequest)
        .getData();

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri": "/iban/validate",
  "data": {
    "uri": "/iban/validate",
    "iban": "GB94SELN00999976543215",
    "domesticAccountNumber": "76543215",
    "accountCountry": "GB",
    "domesticBankCode": null,
    "domesticBranchCode": "009999",
    "domesticCheckSum": null,
    "bic": "SELNGB21XXX"
  }
}

A POST request used to validate accounts. A request must contain the application/json content type. In the request body you must provide a JSON structure containing an iban.

Definition

POST /iban/validate

Arguments

JSON Path Type Description
iban required String max 34 chars Valid IBAN structure

Must not be mixed with Domestic Account properties of Validate Account object.

Returns

Returns 200 OK response code and a JSON structure with URI and Validate Account object.

In case of failure, an error is returned within the error structure (see Errors section).

Files

Upload file

Example request

$ curl 'https://api.nuapay.com/files' -i -X POST \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@12345.xml' -F \
  'json={
    "fileType":"DD",
    "fileName":"12345.xml",
    "fileFormat":"BE_SCHEME",
    "schemeType":"CORE",
    "creditorSchemeId":"CreditorSchemeName"
   };type=application/json'
byte[] fileContent = ...

UploadFileRequest uploadFileRequest = 
        new UploadFileRequest()
            .withFileType(FileType.DD)
            .withFileName("12345.xml")
            .withFileFormat("BE_SCHEME")
            .withSchemeType(SchemeType.CORE)
            .withCreditorSchemeId("CreditorSchemeName");

FileResource fileResource = 
    new FilesServiceDefault(serviceConfig)
        .uploadFile(uploadFileRequest, fileContent)
        .getData();

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "uri" : "/files/23qzxn1f7m",
  "data" : {
    "id" : "23qzxn1f7m",
    "uri" : "/files/23qzxn1f7m",
    "originalFileName": "originalFileName.xml",
    "newFileName": "newFileName.xml.QUEUED"
  }
}

A POST request used to upload a file. A request must contain the multipart/form-data content type with a json part containing input parameters in a JSON structure and a file part with file content.

Definition

POST /files

Arguments for json part

JSON Path Type Description
fileType required String enum Uploaded file type: currently only DD (Direct Debit) supported
fileFormat required String enum Import format type matching file type provided. For full list of allowed format types contact Customer Support. NOTE: The list is limited to allowed file formats agreed with Nuapay during the on-boarding process.
schemeType required String enum Possible values: CORE, B2B, DSH, HYB
creditorSchemeId required String Returned by List Creditor Schemes. Mandatory for DD files
fileName required String max 250 chars Uploaded file name. No white spaces allowed, Allowed characters: letters, digits, special chars: underscore ( _ ), dash ( - ), dot ( . )

Returns

Returns 200 OK response code with a JSON structure representing the uploaded file.

In case of failure, an error is returned within the error structure (see Errors section).

Allowed File Formats

DD File Type File Format
Austrian AcePropACEPROP
Belgian Dom80 BE_SCHEME
Cyprus Cyprus-DD
Dutch CLIEOP03 CT_CLIEOP03
EDIFACT EDIFACT
French CFONB160 FR_SCHEME
French CFONB160 UMR CFONB160UMR
French CFONB214 CFONB214
Generic BAFF_BAML BAFF
Generic CSV GC_SCHEME
Generic GFF_JPM DD_GFF
Generic IDOC IDOC
Generic TSYS_Barclaycard TSYS
Generic XML Format GX_SCHEME
German DTA DE_SCHEME
German DTUS DTA_ZEN
Greece Greece-DD
idoc-SAP-JPM idoc-SAP-JPM
idoc-SAP-XML idoc-SAP-XML
Irish STD18 STD18_Ireland
Irish STD18-ACC STD18_Ireland_ACC
Irish STD18 (Multi day) STD18_Ireland_Multi
Irish STD18-UniqueMsgId STD18_UniqueMsgId
Italian CBI CBI_RID
Norm19_Marsh Norm19M
PAIN.008.001.02 P812
PAIN.008.001.02.ISO P812ISO
Portuguese EDR EDR
Portuguese PS2 PS2
SAP IDOC idoc-SAP
Spanish Norm19 Norm19
Spanish Norm58 Norm58

Responses

Every API Request will generate a HTTP Response. This will contain a HTTP Response Code to indicate the status of the Request. In addition certain HTTP Responses (400, 422) may generate an Error Response with an Error Code.

HTTP Response Codes

You may encounter the following response codes. Selected response codes will contain more information to help identify problems.

Status Code Usage
200 OK -- The request completed successfully.
201 Created -- A new resource has been created successfully. The resource is appended to the response.
400 Bad Request -- The request was malformed. The response body will include an error providing further information.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The client has provided a valid Authentication header, but it does not have permission to access this resource.
404 Not Found -- The requested resource did not exist.
405 Method Not Allowed -- When a HTTP method is being requested that isn’t allowed.
410 Gone -- The API requested has been removed from our servers.
412 Precondition Failed -- Certain unmet conditions must be fulfilled before the request to be processed e.g. timestamp is too old.
415 Unsupported Media Type -- If incorrect content type was provided as part of the request (e.g. other than "application/json").
422 Unprocessable Entity -- Used for validation errors. More details will be provided in response body.
500 Internal Server Error -- We had a problem with our server. Try again later and if the problem persists contact the Nuapay application support team.
501 Not Implemented -- When the endpoint is not implemented yet.
503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

Errors

For example, a request that attempts to create a payment schedule with invalid start date will produce a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "returnCode" : "7043",
  "returnDescription" : "Start date is invalid"
}

Whenever an error response with status 400 or 422 is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description
returnCode String Error Code
returnDescription String Error description
details Array The object holds collection of validation errors. It is returned only for returnCode equal to 8888,9999.
details[].code String Error Code
details[].field String JSON path to request object property the error is related to
details[].description Error description
details[].resourceUri String This property holds existing resource URI in case the validation error states the resource already exist and can't be created. It is returned only for returnCode equal to 9999.

See Error Codes section for details.

Error Codes

Following is the list of error codes with description as a possible return when request failed:

Code Description
2005 Debtor Account Validation Error Create mandate, Update mandate
2006 The Creditor Account referenced within the file does not exist within the system Create mandate, Update mandate
3001 The debtor language must be provided Create mandate, Update mandate
3002 The language parameter is incorrect Create mandate, Update mandate
3003 The debtor address line 1 must be provided Create mandate, Update mandate
3004 The debtor country must be provided Create mandate, Update mandate
3006 The address parameter is mandatory when paper handling is set to true Create mandate, Update mandate
3007 The country is invalid Create mandate, Update mandate
3008 The debtor town must be provided Create mandate Update mandate
3009 The Mandate cannot be edited from its current state Update mandate
3010 Mandate cannot be cancelled from its current state Cancel Mandate
3021 A Payment already exists against a ONCE_OFF mandate Create direct debit
3022 The Mandate cannot be Activated from its current state Activate mandate
3023 Mandate could not be added due to missing PDF template Create mandate
3024 The debtor e-mail must be provided Create mandate
3025 The debtor mobile number must be provided Create mandate
3026 Mandate Type not supported in current configuration Update mandate
3027 A Mandate exists in the system with the specified SEPA mandate ID. This ID must be unique for an Originator Create mandate, Update mandate
3028 In Respect of Contract ID not provided Create mandate, Update mandate
3029 No SEPA Mandate ID Provided Create mandate
3030 Language is not supported by originator Create mandate
4003 Payment Date is not a working day Create direct debit, Create payment schedule
4004 Date format invalid Create direct debit
4005 Payment Date is not far enough in the future Create direct debit, Create payment schedule
4006 Invalid Number of Payments Create payment schedule
4007 Invalid Schedule Reference Create payment schedule
4008 Payment Date is too far in the future Create direct debit, Create payment schedule
4009 Payment Amount is invalid Create direct debit, Create payment schedule
4011 First Payment Amount Invalid Create payment schedule
4013 Last Payment Amount Invalid Create payment schedule
4016 Representation is not enabled for the creditor scheme Represent failed direct debit
4019 End To End Id is invalid Create direct debit
4021 Direct Debit cannot be revoked as it is not in a valid status Revoke direct debit
4022 No Direct Debit exists matching information provided Revoke all direct debits
4023 Direct Debit is not in a valid condition for Representation Represent failed direct debit
4024 Invalid Representation Fee amount Represent failed direct debit
4025 Invalid Representation Date Represent failed direct debit
4029 Number of Payments not provided Create payment schedule
4031 Final Payment amount should not be provided for an Open Ended Schedule Create payment schedule
4032 Number of Payments should not be provided for an Open Ended Schedule Create payment schedule
4033 Only a Start date should be provided for a Daily/Yearly Schedule Create payment schedule
4034 Only Day of Week should be provided for a Weekly/Bi-Weekly Schedule Create payment schedule
4035 Only Date in Month or Week in Month and Day of week should be provided for a Monthly schedule Create payment schedule
4036 An Active schedule already exists on this mandate Create payment schedule
4039 Payment Type must be Fixed Length on a Once off Mandate Create payment schedule
4040 Number of Payments on a Once Off Mandate must be set to 1 Create payment schedule
4041 End To End Id is not unique Create direct debit
4042 Mandate is not in a Valid Status Create direct debit, Create payment schedule, Represent DD
4043 No Direct Debit exists in a valid status Revoke all direct debits
4048 Payment Custom Frequency must be provided if Payment Schedule Frequency is set to CUSTOM Create payment schedule and mandate
5001 Invalid Beneficiary Account Details Create beneficiary, Create credit transfer
5002 Duplicate Beneficiary Account Details Provided Create beneficiary
5004 Beneficiary Country Required if any other Address element is provided Create beneficiary
5005 Invalid Beneficiary e-mail address provided Create beneficiary
5006 Payment Amount Invalid Create credit transfer
5007 Originator Account provided does not exist Create credit transfer
5008 Invalid Payment Reference Create credit transfer
5009 Invalid Date for Payment Create credit transfer
5014 Transfer Failed. Please try again later Create credit transfer
5015 Transfer Failed. Please contact support Create credit transfer
5016 Insufficient Funds Create credit transfer
5017 Originator account currency does not match payment currency Create credit transfer
7001 Date format invalid List mandates, List direct debits,List failed direct debits, List credit transfers
7002 ‘From Date ’ must be earlier or equal to 'To Date’ List mandates, List direct debits, List failed direct debits, List credit transfers
7003 Max date range is exceeded List mandates, List direct debits, List failed direct debits
7004 Boolean parameter value must be either 'true’ or 'false’ List failed direct debits, Create direct debit, Create payment schedule, Create direct debit and mandate, Create payment schedule and mandate
7005 Max file size exceeded Upload file
7006 Invalid file supplied. File extension does not match file format Upload file
7007 Not allowed file format Upload file
7008 Invalid file name Upload file
7009 The Creditor Scheme ID/Type referenced does not exist within the system Upload file
7010 Debtor Name is invalid or max length is exceeded Create mandate, Update mandate, List mandates
7011 Address Line1 is invalid or max length is exceeded Create mandate, Update mandate, Create beneficiary
7012 Address Line2 is invalid or max length is exceeded Create mandate, Update mandate, Create beneficiary
7013 Address Town is invalid or max length is exceeded Create mandate, Update mandate, Create beneficiary
7014 Address Postal Code is invalid or max length is exceeded Create mandate, Update mandate, Create beneficiary
7015 Address State is invalid or max length is exceeded Create mandate, Update mandate, Create beneficiary
7016 Address ISO Country Code is invalid Create mandate, Update mandate, Create beneficiary
7017 Debtor Language is invalid Create mandate, Update mandate
7018 Debtor Email is invalid or max length is exceeded Create mandate, Update mandate
7019 Phone Number is invalid or max length is exceeded Create mandate, Update mandate, Create beneficiary
7020 Mobile Number is invalid or max length is exceeded Create mandate, Update mandate, Create beneficiary
7021 Mandate Id is invalid or max length is exceeded Create mandate, Update mandate, List mandates
7022 Contract Reference is invalid or max length is exceeded Create mandate, Update mandate
7023 Signature Location is invalid or max length is exceeded Create mandate, Update mandate, Activate mandate
7024 Signature Date is invalid or max length is exceeded Create mandate, Update mandate, Activate mandate
7025 Mandate Type is invalid Create mandate, Update mandate
7026 Debtor IBAN is invalid Create mandate, Update mandate, List mandates
7027 Debtor Bank BIC is invalid Create mandate, Update mandate
7028 Creditor IBAN is invalid Create mandate, Update mandate
7029 Creditor Bank BIC is invalid Create mandate, Update mandate
7030 Mandate Source is invalid Update mandate
7031 Debtor Account IBAN is required Create mandate, Update mandate
7032 Debtor object is required Create mandate, Update mandate
7033 Debtor Account object is required Create mandate, Update mandate
7034 Debtor name is required Create mandate, Update mandate
7035 Remittance Information is invalid or max length is exceeded Create direct debit, Create payment schedule
7036 Requested Collection Date is required Create direct debit
7037 Payment Amount is required Create direct debit, Create payment schedule
7038 Payment Frequency is required Create payment schedule
7039 Payment Type is required Create payment schedule
7040 Start Date is required Create payment schedule
7041 Payment Frequency is invalid Create payment schedule
7042 Payment Type is invalid Create payment schedule
7043 Start date is invalid Create payment schedule
7044 Schedule Id is invalid or max length is exceeded Create payment schedule, List direct debits, Revoke all direct debits
7045 Number of Payments is invalid Create payment schedule
7046 Payment Day of Week is invalid Create payment schedule
7047 Payment Week of Month is invalid Create payment schedule
7048 Payment Day in Month is invalid Create payment schedule
7049 ResendMandateForSignature is invalid Update mandate
7050 Page Number is invalid List mandates, List direct debits, List beneficiaries, List credit transfers, List Transactions
7051 Max page size is exceeded List mandates, List direct debits, List beneficiaries, List credit transfers, List Transactions
7052 Page size is invalid List mandates, List direct debits, List beneficiaries, List credit transfers, List Transactions
7053 Authorization Method is invalid Activate mandate, Create mandate
7054 Authorization Token is invalid or max length is exceeded Activate mandate, Create mandate
7055 Authorization email is invalid or max length is exceeded Activate mandate, Create mandate
7056 Authorization Mobile Number is invalid or max length is exceeded Activate mandate, Create mandate
7057 Ip Address is invalid or max length is exceeded Activate mandate, Create mandate
7058 Geographic Location is invalid or max length is exceeded Activate mandate, Create mandate
7059 Mandate Status is invalid List mandates
7060 End To End Id is invalid Create direct debit, Create direct debit and mandate
7063 Payment Status is invalid List direct debits, List credit transfers
7064 Operation Reason exceeds maximum length Cancel Mandate, Revoke all direct debits, Revoke direct debit
7065 Invalid Domestic Bank Code Validate Domestic Account
7066 Invalid Domestic Branch Code Validate Domestic Account
7067 Invalid Account Country Validate Domestic Account
7068 Invalid Domestic Checksum Validate Domestic Account
7070 The SEPA Creditor Scheme ID does not exist for the selected scheme Validate IBAN
7071 No account associated to the creditor scheme Create direct debit and mandate, Create payment schedule and mandate
7072 PDF could not be generated / retrieved Retrieve mandate document
7074 Mandate Operation Reason not provided Cancel Mandate,
7075 Domestic Account Number is required if IBAN is not provided Validate Domestic Account
7076 Invalid Domestic Account Number Validate Domestic Account
7077 Account Country is required if IBAN is not provided Validate Domestic Account
7078 ‘Reject From Date’ is required List failed direct debits
7079 ‘Reject To Date’ is required List failed direct debits
7080 Payment Custom Frequency is invalid Create payment schedule
7081 Beneficiary IBAN is invalid List beneficiaries, Create beneficiary
7082 Beneficiary Bank BIC is invalid Create beneficiary
7083 Beneficiary Account IBAN is required Create beneficiary
7084 Beneficiary object is required Create beneficiary
7085 Beneficiary Account object is required Create beneficiary
7086 Beneficiary Name is required Create beneficiary
7087 Beneficiary Bank BIC is required if External Account Validation is OFF Create beneficiary
7088 Beneficiary Language is invalid Create beneficiary
7089 Beneficiary Email is invalid or max length is exceeded Create beneficiary
7090 Requested Execution Date is required Create credit transfer
7091 Originator IBAN is required Create credit transfer
7092 Payment Currency is required Create credit transfer
7093 Payment Currency is invalid Create credit transfer
7094 Beneficiary account is not reachable for GBP currency Create credit transfer
7096 Description of Purpose is invalid or max length is exceeded Create beneficiary
7098 Invalid IBAN Validate IBAN
7099 Domestic Account details are not allowed if IBAN is provided Validate Domestic Account, Validate IBAN
7100 Beneficiary Name is invalid or max length is exceeded List beneficiaries, Create beneficiary, List credit transfers
7101 Provided schedule details would create two payments for first collecting period. Please change schedule details or twoPaymentsSamePeriod flag Create payment schedule
7104 Debtor Account Country does not match Scheme Country Create mandate
7105 Creditor Account Country does not match Scheme Country Create mandate
7106 Exported Mandates cannot be amnded when Edit Doc Handling / Regulatory Screening is enabled Update mandate
7107 Mandate Id and Debtor Account details cannot be amended when Debtor Mandate Flow is used Update mandate
7108 The file extension does not match that of the content-type header Upload Mandate Document
7109 The file size exceeds 2MB Upload Mandate Document
7110 The file name is invalid or exceeds the max length Upload Mandate Document
7111 Originator IBAN is invalid Create credit transfer
7112 Insufficient Funds Create credit transfer
7113 Transfer Failed. Please try again later Create credit transfer
7114 Transfer Failed. Please contact support Create credit transfer
7116 A Once Off Mandate cannot have Migrating Mandate value true Update mandate
7117 BBAN specific fields not allowed Create mandate, Update mandate
7118 Payment schedule status is invalid List payment schedules
7120 Payment schedule cannot be cancelled as it is not in ACTIVE status Cancel Payment Schedule
7123 Mandate object is required Create direct debit and mandate,Create payment schedule and mandate
7124 Current Creditor Scheme configuration does not allow to create mandate on the fly Create direct debit and mandate,Create payment schedule and mandate
7125 Requested execution date is in the past Create credit transfer
7126 Requested execution date is not a working day Create credit transfer
7127 Requested execution date is today and Cut-off time has passed Create credit transfer
7128 Required request part 'file' is not present Upload Mandate Document
7129 Debtor Bank BIC is required as Debtor Bank is located in a NON-EEA Country Create mandate,Create direct debit and mandate,Create payment schedule and mandate
7130 Beneficiary Bank BIC is required as Beneficiary Bank is located in a NON-EEA Country Create beneficiary
7131 Field is invalid or max length is exceeded Create account, List accounts, List credit transfers
7132 Field is required Create account
7133 IBAN is requried if External Account Validation is off Create account
7134 Object is required Create account
7135 Object is not allowed for current Originator configuration Create account
7136 Account Validation Error Create account
7137 Account already exist Create account
7138 Currency is not supported Create account
7139 Field is required for provided Account Country Create account
7140 Field is not allowed for provided Account Country Create account
7141 Field is not allowed for current Originator configuration Create account
7142 Cannot generate account for current Originator configuration. Billing Mandate Reference is not set. Create direct debit and mandate, Create payment schedule and mandate
7143 Electronic Signature Details object is required.
7144 Account currency does not match payment currency.Transfers
7145 Account From is the same as Account To.Transfers
7146 Transfer not allowed for current Originator configuration.Transfers
7147 Transfer not allowed for Originator type.Transfers
7148 The Execution Date must be set to today's date.Transfers,Create credit transfer, Create Credit Transfer and Beneficiary
7149 Account From and Account To needs to be of the same type.Transfers
7150 Transfer between sub-accounts of different master account is not allowed.Transfers
7152 Payment amount exceeds max allowed scheme limit Create Credit Transfer and Beneficiary
7153 Requested payment type is not supported by OriginatorCreate Credit Transfer and Beneficiary
7154 Originator Bank BIC is required for EXPRESS paymentsCreate Credit Transfer and Beneficiary
7155 Beneficiary Bank BIC is required for EXPRESS paymentsCreate Credit Transfer and Beneficiary
7156 Beneficiary account is not reachable for requested payment typeCreate Credit Transfer and Beneficiary
7157 Original transaction has not been found
7158 Either originatorIban or originatorAccount object is allowed.Create credit transfer
7159 Either Iban or Domestic Account is allowed. Create credit transfer, Create Credit Transfer and Beneficiary,Create beneficiary
7160 Domestic Bank Code is required for provided Account CountryCreate credit transfer, Create Credit Transfer and Beneficiary,Create beneficiary
7161 Domestic Bank Code is not allowed for provided Account CountryCreate credit transfer, Create Credit Transfer and Beneficiary)
7162 Domestic Branch Code is required for provided Account CountryCreate credit transfer, Create Credit Transfer and Beneficiary,Create beneficiary
7163 Domestic Branch Code is not allowed for provided Account CountryCreate credit transfer, Create Credit Transfer and Beneficiary,Create beneficiary
7164 Domestic Checksum is required for provided Account CountryCreate credit transfer, Create Credit Transfer and Beneficiary,Create beneficiary
7165 Domestic Checksum is not allowed for provided Account CountryCreate credit transfer, Create Credit Transfer and Beneficiary,Create beneficiary
7200 JWS-Signature header is required. Create beneficiary, Create credit transfer
7201 JWS-Signature is invalid. Create beneficiary, Create credit transfer
7202 Invalid file MIME Type for file extention. Please check the file content. Upload file
7204 Value Date To is invalid. List Transactions
7205 Value Date From is invalid. List Transactions
7206 Amount From is invalid. List Transactions
7207 Amount To is invalid. List Transactions
7208 'Value Date From' is not earlier or equal to 'Value Date To'. List Transactions
7209 'Amount From' is greater then 'Amount To'. List Transactions
7203 Field is invalid or max length is exeeded List account balances
7300 UltimateParty Name' is invalid or max length is exceeded. Create credit transfer, Create Credit Transfer and Beneficiary
7301 UltimateParty Other SchemeName Code' is Invalid. Create credit transfer, Create Credit Transfer and Beneficiary
7302 UltimateParty Other SchemeName Proprietary' is Invalid. Create credit transfer, Create Credit Transfer and Beneficiary
7303 UltimateParty Other ID' is Invalid. Create credit transfer, Create Credit Transfer and Beneficiary
7304 UltimateParty Other Issuer' is Invalid. Create credit transfer, Create Credit Transfer and Beneficiary
7305 UltimateParty OrganisationId BicorBei' is Invalid. Create credit transfer, Create Credit Transfer and Beneficiary
7306 UltimateParty PrivateId BirthDate' is Invalid. Create credit transfer, Create Credit Transfer and Beneficiary
7307 UltimateParty PrivateId BirthDate' is required. Create credit transfer, Create Credit Transfer and Beneficiary
7308 UltimateParty PrivateId CityOfBirth' is Invalid. Create credit transfer, Create Credit Transfer and Beneficiary
7309 UltimateParty PrivateId CountryOfBirth' is Invalid. Create credit transfer, Create Credit Transfer and Beneficiary
7310 UltimateParty PrivateId CountryOfBirth' is required. Create credit transfer, Create Credit Transfer and Beneficiary
7330 UltimateCreditor either 'organisationId' or 'privateId' is allowed. Create credit transfer, Create Credit Transfer and Beneficiary
7331 UltimateCreditor OrganisationId either 'bicOrBei' or 'other' is allowed. Create credit transfer, Create Credit Transfer and Beneficiary
7332 UltimateCreditor OrganisationId Other SchemeName either 'code' or 'proprietary' is allowed. Create credit transfer, Create Credit Transfer and Beneficiary
7333 UltimateCreditor PrivateId either 'dateAndPlaceOfBirth' or 'other' is allowed. Create credit transfer, Create Credit Transfer and Beneficiary
7334 UltimateCreditor PrivateId Other SchemeName either 'code' or 'proprietary' is allowed. Create credit transfer, Create Credit Transfer and Beneficiary
7335 UltimateDebtor either 'organisationId' or 'privateId' is allowed. Create credit transfer, Create Credit Transfer and Beneficiary
7336 UltimateDebtor OrganisationId either 'bicOrBei' or 'other' is allowed. Create credit transfer, Create Credit Transfer and Beneficiary
7337 UltimateDebtor OrganisationId Other SchemeName either 'code' or 'proprietary' is allowed. Create credit transfer, Create Credit Transfer and Beneficiary
7338 UltimateDebtor PrivateId either 'dateAndPlaceOfBirth' or 'other' is allowed. Create credit transfer, Create Credit Transfer and Beneficiary
7339 UltimateDebtor PrivateId Other SchemeName either 'code' or 'proprietary' is allowed. Create credit transfer, Create Credit Transfer and Beneficiary
7340 'UltimateParty Other ID' is required. Create credit transfer, Create Credit Transfer and Beneficiary
7341 'UltimateParty PrivateId CityOfBirth' is required. Create credit transfer, Create Credit Transfer and Beneficiary
7148 The Execution Date must be set to today's date. Create credit transfer, Create Credit Transfer and Beneficiary
7152 Payment amount exceeds max allowed scheme limit. Create credit transfer, Create Credit Transfer and Beneficiary
7153 Requested payment type is not supported by Originator. Create credit transfer, Create Credit Transfer and Beneficiary
7154 Originator Bank BIC is required for EXPRESS payments. Create credit transfer, Create Credit Transfer and Beneficiary
8888 Input validation errors occurred. Please check details Create direct debit and mandate,Create payment schedule and mandate
9001 Invalid Domestic Account Number Validate Domestic Account
9002 None-SEPA country IBAN has been provided Create mandate, Update mandate
9999 Resource validation error Create direct debit and mandate,Create payment schedule and mandate
10002 Request parameters not valid Upload file

Pagination

e.g. show the 1st page with a maximum of 10 entries per page from all of the available mandates:

$ curl 'https://api.nuapay.com/schemes/46pkx7o9n5/mandates/?pagesize=10&pagenumber=1' \
  -u bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: \
ListMandatesRequestParameters listMandatesRequestParameters = 
    new ListMandatesRequestParameters();
listMandatesRequestParameters.setPageSize(10);
listMandatesRequestParameters.setPageNumber(1);

ListMandatesResponse listMandatesResponse = 
    mandateService.listMandates("46pkx7o9n5", listMandatesRequestParameters);

the response will be:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri" : "/schemes/46pkx7o9n5/mandates",
  "data" : [ {
    "id" : "46pkxn8e9n",
    "uri" : "/schemes/8g3o2yyk2w/mandates/46pkxn8e9n",
    "mandateId" : "b8b7ee91-b403-4ecb-9d98-059746dd8149",
    "debtorName" : "Debtor Name",
    "debtorIBAN" : "GB94SELN00999976543215",
    "debtorMobileNumber" : "0360321312312",
    "mandateStatus" : "ACTIVE",
    "creationDate" : "2015-07-21"
  }, {
    "id" : "nx9kndaejm",
    "uri" : "/schemes/8g3o2yyk2w/mandates/nx9kndaejm",
    "mandateId" : "a04ee152-505d-4125-b671-5c5318b53842",
    "debtorName" : "Debtor Name",
    "debtorIBAN" : "GB94SELN00999976543215",
    "debtorMobileNumber" : "0360321312312",
    "mandateStatus" : "ACTIVE",
    "creationDate" : "2015-07-21"
  }, {
    "id" : "vw7kj9gey5",
    "uri" : "/schemes/8g3o2yyk2w/mandates/vw7kj9gey5",
    "mandateId" : "79839287-54d8-4fab-99cc-cf1808b7a766",
    "debtorName" : "Debtor Name",
    "debtorIBAN" : "GB94SELN00999976543215",
    "debtorMobileNumber" : "0360321312312",
    "mandateStatus" : "ACTIVE",
    "creationDate" : "2015-07-21"
  } ],
  "page" : {
    "pageNumber" : 1,
    "pageSize" : 3,
    "totalElements" : 3,
    "totalPages" : 1
  },
  "sort" : [ ]
}

Nuapay API utilizes offset-based pagination for endpoints returning a collection of resources.

Pagination parameters can be passed in URI for GET requests and in Body in POST requests.

To control pagination, simply include either of 'Page Number' and 'Page Size' parameters in a request. In the supported responses there will always be a page section added, describing the pagination settings used.

In URI

There are two parameters that control pagination: pagenumber, which specifies the page number to retrieve, and pagesize, which indicates how many records each page should contain.

In Body

Path Type Description
page.pageNumberrequired Number Holds page number to be returned. Default: 1
page.pageSizerequired Number Holds page size to be returned. Default: 20

Versioning

The current version of the Nuapay API is version 1.0. Changes may occur to this version of the API without a change in version number if such a change follows our backwards compatibility guidelines. Different versions will be managed via a HTTP header indicating the version of the API which the client is using.

Requests with no version number or an unmatched version number will be treated as version 1.0 requests.

Backwards Compatibility

The following changes are considered backwards compatible:

Useful Links

Below you can find some useful links for further reading and help around RESTful integration and E-Mandates.

Changelog

2018-10-08

2018-07-27

2018-06-18

2018-05-30

2018-04-05

2018-01-22

2017-09-14

2017-10-20

2017-09-15

2017-09-14

2017-08-21

2017-08-15

2017-08-14

2017-07-12

2017-07-05

2017-05-29

2017-05-24

2017-04-11

2017-03-01

2017-01-10

2016-07-20

2016-06-29

2016-05-06

2016-04-12

2016-04-11

2016-04-03

2016-01-21

2015-11-19

2015-09-30

2015-09-01