Types of payments supported by Neonomics

Neonomics supports four types of payments: Domestic Payment, Domestic Scheduled Payment, SEPA Payment, and SEPA Scheduled Payment.

Domestic Payment is a transfer of money between two bank accounts in the same country using the domestic currency. An example of a domestic payment would be £50 from one British bank account to another British bank account.
Domestic Scheduled Payment is a transfer of money between two bank accounts in the same country using the domestic currency, set to be executed on a specific date. For example, initiating a payment of £10 from one British bank account to another British bank account to be executed on the 11th of March 2021.
SEPA Payment (Single Euro Payments Area) is a transfer of money from one bank account to another within the 36 SEPA countries. The currency used for these payments is the euro. An example of a SEPA payment would be €10 from a Finnish bank account to a French bank account.
SEPA Scheduled Payment is a SEPA payment set to be executed on a specific date.

📘
Info
You need to complete the development quickstart and the customer consent guide before starting this guide. A valid access_token and sessionId are needed to follow the payments.

How to make a payment using the Neonomics API

To make a payment, complete these four steps in sequence:

Initiate the payment to create a payment object in Neonomics so that the end-user can authorize the payment. This step will require consent from the end-user if no valid consent exists for the account.
Handle the response from payment initiation to determine how to proceed. If the payment is exempt from SCA, the initiation will already be complete in step 1. Otherwise, you need to execute the following two steps.
Authorize the payment by obtaining a URL from the end-user's bank to complete a payment authorization. This step is omitted if the payment is exempt from SCA.
Complete the payment initiation to queue the payment for execution in the bank. This step is omitted if the payment is exempt from SCA.

When the payment initiation is complete, the debtor bank will execute the payment in accordance with its procedures for cut-off time and settlement.

Step 1: Initiate a payment

To initiate a payment, make a curl POST request below and follow these instructions:

Replace <PAYMENT_TYPE> with the payment type you want to initiate. The possible payment types are /payments/domestic-transfer/, /payments/domestic-scheduled-transfer/, /payments/sepa-credit/, or /payments/sepa-scheduled-credit/
The request body must contain all required parameters in the <PAYMENT_BODY>.
In cases where you need to apply a Redirect URL, include the x-redirect-url parameter in the request header.
Remember to include the x-psu-id header if it is required by the bank.
Replace <ACCESS_TOKEN> and <SESSION_ID> with the access_token and sessionId generated in the Development quickstart.
Please note that the bank details used in this document are test details, only used in the sandbox.


curl -X POST https://sandbox.neonomics.io/ics/v3/payments/<PAYMENT_TYPE> \
-H "Authorization:Bearer <ACCESS_TOKEN>" \
-H "x-device-id:example_id_for_quickstart" \
-H "Content-Type:application/json" \
-H "Accept:application/json" \
-H "x-session-id:<SESSION_ID>" \
-H "x-psu-ip-address: 109.74.179.3" \
-d '{<PAYMENT_BODY>
}'

Account numbers

When initiating a payment, creditor and debtor account info is required. This info consists of two parts:

The actual account number, which is also called the account identifier, e.g., 'DE89370400440532013000'.
The account scheme is also called account number type. The table below shows what account schemes can be used in what markets.

Account scheme	Name	Where used
IBAN	International Bank Account Number	All markets
BBAN	Base Bank Account Number	All markets
PGNR	PlusGironummer	Sweden
BGNR	Bankgironummer	Sweden

The rules for what account schemes are valid in a payment initiation request body depend on the payment type. Those rules are described for each payment type in the payment guides here as well as in API References for the respective payment types.

Step 2: Handle the response

You can usually expect one of the three responses described below when you initiate a payment. Handle any other response as an error situation.

Status code 201 with message "Payment created", which means that the bank accepted the payment straight away. The response contains the payment's status and paymentId, which you can use later in a Get Payment by ID call to follow up on the payment's status. After a 201 response, omit calling Authorize payment and Complete Payment, because the payment initiation is already complete.
Status code 510 together with error code 1426, which means that end-user consent is required. The next step is to call Get Consent API to initiate Strong Customer Authentication. When that is successfully completed, initiate the payment again.
Status code 510 together with error code 1428, which means that payment authorization is required. The next step is to call Authorize Payment API to initiate Strong Customer Authentication. When that is successfully completed, call Complete Payment. Below is an example of a response with the error code 1428.

Response

{
  "id": "366c893e-4649-4692-8ade-a30d190e5c15",
  "errorCode": "1428",
  "message": "This payment requires strong customer authorisation. Please use the authorisation URL provided to continue, then call the payment complete endpoint after authorising.",
  "source": "C",
  "type": "CONSENT",
  "timestamp": 1575379181868,
  "links": [
    {
      "type": "GET",
      "rel": "payment",
      "href": "https://sandbox.neonomics.io/ics/v3/payments/<PAYMENT_TYPE>/05a072c7-9a6f-4170-ac61-9bd70512a440/authorize",
       "meta": 
       {
            "id": "05a072c7-9a6f-4170-ac61-9bd70512a440"
        }
    }
  ]
}

Link object

Neonomics API errors can contain an array of link objects. The error shown above contains a link object with the following attributes:

href - This can contain two types of links. The first type is the URL for a Neonomics API request, as in the example above. The second type is a link to the bank's website so the end-user can complete a consent request or a customer payment authorization.
rel - The Neonomics API operation related to the link.
type - If the href is a link to a request to the Neonomics API, then this is the type of HTTP RESTful request method required: POST, GET, DELETE, PUT, or PATCH.
meta - This object contains an id which is the current paymentId.

Save the href you received from the request above, as you will need it in step 2.

Step 3: Authorize the payment

Now that you have initiated a payment, the end-user usually has to authorize the payment API. However, some payment types are exempt from authorization. In those cases, there will be no error.

To authorize a payment, you will need to obtain the bank's authorization URL by using the curl GET request below.

You will need the URL you obtained in the error object in step one. Replace <AUTHORIZATION_URL> with the href obtained in step one. Replace <ACCESS_TOKEN> and <SESSION_ID> with your access_token and sessionId. Remember to include the x-psu-id header if it is required by the bank.

Request:

curl -X GET \<AUTHORIZATION_URL>  
-H "Authorization:Bearer \<ACCESS_TOKEN>"  
-H "Accept:application/json"  
-H "x-device-id:example_id_for_quickstart"  
-H "x-psu-ip-address:109.74.179.3"  
-H "x-session-id:\<SESSION_TOKEN>"

Below is the response returned from the request above.

Response:

{
  "paymentId": "<PAYMENT_ID>",
  "message": "Please use the Authorization Url to continue.",
  "links": [
    {
      "type": "GET",
      "rel": "Authorization URL",
      "href": "https://openbanking.sbanken.no/tap-sandbox/9710/?route_secesb_id=2&flow=psd2&state=8cda5e87-1fbc-4d82-8f5b-c13351d8c911&context=PRIVATE"
    }
  ]
}

This response contains an array of links with one object. The href in this object is a link that will take you to the decoupled authorization page.

In this example, you can simulate the end-user authorization of the payment. Save the paymentId, as this is required in step three.

Copy the href URL and open it in your internet browser. Below is the bank's payment authorization webpage. You will be asked to enter a ‘Personnummer’. Use this number: 01078900497

You will then be taken to the Neonomics webpage shown below. However, if a custom Redirect URL was applied in the authorization request, the page specified in x-redirect-url will appear instead.

Step 4: Complete the payment initiation

After the end-user has authorized the payment, it's required to complete the payment initiation API. This needs to be done without delay since payment tokens issued by banks are only valid for a limited time.

Use the curl POST request below. Replace \<PAYMENT_ID> with the paymentId that was returned in the authorization response in step two. Replace \<ACCESS_TOKEN> and \<SESSION_ID> with your access_token and sessionId. Remember to include the x-psu-id header if it is required by the bank.

Request:

curl -X POST <https://sandbox.neonomics.io/ics/v3/payments/><PAYMENT_TYPE/>\<PAYMENT_ID>/complete  
-H "Authorization:Bearer \<ACCESS_TOKEN>"  
-H "accept: application/json"  
-H "content-type: application/json"  
-H "x-device-id:example_id_for_quickstart"  
-H "x-psu-ip-address:109.74.179.3"  
-H "x-session-id:\<SESSION_ID>"  
-H "content-length: 0"

This is the returned object.

Response:

{  
  "paymentId": "\<PAYMENT_ID>",  
  "status": "ACTC",  
  "creationDateTime": "2019-12-03T14:19:41.855+01:00"  
}

Step 5: Get the final payment status

Regardless if the final payment status (successful or failed) was returned in a previous step, we strongly recommend calling the Get Payment by ID endpoint for all payments. Only if the response of the Get Payment by ID call is final should the end-user be informed about the outcome of the payment.

If the payment is scheduled, a final payment status may only be returned on the due date. note that in some cases, banks will retry the payments for some days if the user does not have sufficient funds in their account on the due date. It is therefore recommended to continue polling the Get Payment by ID until a final payment status is returned.

Use the curl GET request below. Replace \<PAYMENT_ID> with the paymentId that was returned in the authorization response in step two.

curl -X GET <https://sandbox.neonomics.io/ics/v3/payments/><PAYMENT_TYPE/>\<PAYMENT_ID>
-H 'accept: application/json'`

This is the returned object. If the payment is successful then the attribute status will be ACSC, this is an ISO 20022 standard code. The ISO Codes page explains the codes used by the Neonomics API.

Response:

{
  "paymentId": "string",
  "status": "ACPT",
  "creationDateTime": "2024-03-07T11:01:20.820Z",
  "debtorAccount": {
    "iban": "string",
    "bban": "string",
    "sortCodeAccountNumber": "string"
  },
  "creditorAccount": {
    "iban": "string",
    "bban": "string",
    "sortCodeAccountNumber": "string"
  },
  "remittanceInformationUnstructured": "string",
  "instrumentedAmount": "string",
  "currency": "NOK",
  "type": "string",
  "remittanceInformationStructured": {
    "reference": "string",
    "referenceType": "string",
    "referenceIssuer": "string"
  }
}

Fantastic! You have now completed your first payment 🌟

Types of payments supported by Neonomics

📘Info

How to make a payment using the Neonomics API

Step 1: Initiate a payment

Account numbers

Step 2: Handle the response

Link object

Step 3: Authorize the payment

Step 4: Complete the payment initiation

Step 5: Get the final payment status

📘
Info