Not implementing Checkout?
Head our to our UAPI documentation
UAPI documentation

Neonomics Checkout Technical Client Documentation

Version January 13th 2023

1. Client requirements

Integration with Checkout Solution is a lightweight procedure that requires two code snippets. The snippets are integrated to Client’s System User Interface and Client’s System Back-End. Client’s Back-End is involved to achieve high security of transferred data between Client and Checkout Solution.

1.1 Client Integration Steps

In general client integration steps are depicted below:

Flowchart showing the steps of client integration with checkout

Detailed description of integration steps

  1. Register with Neonomics Checkout by providing your profile data (IBAN, owner, contact details)
  2. Put HTML code snippet into your webpage
  3. Receive API key from Neonomics Checkout Solution that is required to call Checkout back-end from client back-end. See 2.3.1 Integration Context View.
  4. Implement handler on you back-end side that handles click on pay button from a user (HTML snippet). Use Checkout back-end snippet to simplify this action.
  5. Use API key in Back-end code snippet to call "Create Checkout request" REST endpoint. (It is just REST call to Checkout back-end). This call will provide information about amount and currency of money that has to be paid by a user. See 2.3.2 REST API specification.
  6. Redirect a user to a redirect url that is provided in response of previous step (Create Checkout request endpoint). After that user will perform payment of Checkout Solution side and funds will be settled on Client's account.

2 Architecture overview

This section describes high level architecture of Checkout Solution and explains integration approach.

2.1 Business context view

Business context provides overview of business use cases that are implemented by Checkout Solution. Use Case diagram is depicted below:

Illustration of the clients responsibilities: Handle success and fail, let users to checkout and receibe TX history

‍

Diagram showing the responsibilities and tasks for the Neonomics admin in the Checkout flow: Create client, update client and deactivate client.

‍

Diagram showing the user flow of Checkout from the end-user perspective

There are three user roles in Neonomics Checkout:

  • Client: A customer that uses the Checkout solution. It could be an investment platform, a merchant or any other customer
  • Admin: Internal Neonomics employee
  • User: Directly a user that exectures checkout (payment) process

2.2 System context view

System context diagram depicts involved systems and their relationships.

System context diagram

As can be seen a User redirected from Client’s Web site to Checkout Solution Web Site in order to execute checkout (payment) process. The Checkout Solution abstracts the Neonomics API from the Client.

2.3 Integration specification

This section provides information about the communication between the Client's system and Neonomics Checkout

2.3.1 Integration Context View

Integration between Client’s System and Neonomics Checkout is done via REST API:

Diagram showing integration between Client's system and Neonomics API

As can be seen Client’s System Back-End calls Neonomics Checkout via REST API in order to create CheckoutRequest. The CheckoutRequest caries parameters: apiKey, amount, currency, referenceId, remittance information, etc. These parameters are transferred in a protected way between the Client’s Back-End and Neonomics Checkout, so they can’t be changed by a user. Parameters description is provided below.

2.3.2 Rest API Specification

The specification is intended to provide information about integration endpoint and fields.

Endpoint: Create CheckoutRequest
Method: POST
HTTP Path: /api/v1/checkout-requests

Sandbox Environment: https://checkout.sandbox.neonomics.io/

Sandbox Sample App: https://checkout.sandbox.neonomics.io/sample-shop/
- represents a simple app which integrates with the checkout

Live Environment: https://checkout.neonomics.io/

Description

Endpoint is called by Client's back-end.

Authentication:

Endpoint checks client's api-key in Postgres DB.

Request header

Parameters
Description
api-key
Secret API key that is used to identify a client. It is provided to a client after onboarding

Request body

JSON object with the next fields:

Parameters
Description
referenceID
type: string
required: TRUE
May be order id in client's system
endToEndId
type: string
required: FALSE
If not provided it will be generated. Max length is 35 characters.
amount
type: BigDecimal
required: TRUE
Amount that has to be paid by debtor
currency
type: STRING
required: TRUE
Currency enum - currency of transferring money. Currency codes (ISO 4217). For payments in Norway use NOK and EUR for Finland.
country
type: STRING
required: FALSE
Country enum - the country of the creditor and debtor account. Country codes (ISO 3166-1 alpha-2). For payments in Norway use NO and FI for Finland. If it is not provided the default country is Norway.
language
type: STRING
required: FALSE
Language code for the language in which the UI should be rendered.
paymentScheduledDate
‍type: STRING
required: FALSE
Date for scheduled Payment in YYYY-MM-DD format. Should not contain dates older than current date.
scheduledDateEditable
‍type: STRING
required: FALSE
Value "TO_SET_DATE" to enable date-picker (if user should be able to edit the payment scheduled date) and "FIXED" to disable it. If it is not provided, feature is enabled by default.

URL redirections back to Client:

Parameters
Description
successURL
type: string
required: TRUE
URL for user redirection in case of success.
failUrl
type: string
required: FALSE
URL for user redirection in case of failed payment.
cancelUrl
type: String
required: TRUE
URL redirection for user checkout cancellation.
Parameters
Description
Note: only one of the two below can be populated, not both.
remittanceInfo
type: string
required: TRUE
Message that is put to remittanve information of the payment (max size: 140 characters). This is unstructured information.
remittanceInfoStructured
type: JSON object
required: TRUE
Containing data to execute structured payment. It is an unique identification for the payment, issued by the creditor in accordance with a national standard (e.g. "KID" in Norway, "INVOICE" in Finland, "OCR" in Sweden.

Example of the JSON object:

remittanceInfoStructured: {
reference: '1234',
referenceIssuer: 'John Dou',
referenceType:'KID'
},

The fields reference and referenceType are mandatory, while referenceIssuer is optional. If the referenceType is "KID", the length should be minimum 4, maximum 25 digits and digits only.

Parameters
Description
CreditorAccount
type: JSON object
required: FALSE
Should be used when the creditor (payee) should be a different account than the one registered for the merchant.

Example of the JSON object:

creditorAccount: {
creditorName: 'John Doe',
iban: 'NO2390412263056',
bban: '86011117947'
}

All of the fields of the object are String type. Note that creditorName is mandatory, while at least one of iban or bban is needed. Note that in case both the iban and bban are present the payment will be completed using the iban. In case only the bban is present, it will be converted to iban and used for the transaction.

Response:

The response is a JSON object. It contains a redirectUrl field and a checkout id number.

Example

Request Headers:

api-key: 31mkl-hfy23-312kj-f8qw…

Request body:

{
referenceId: "41212",
remittanceInfo: "Ord #41212",
amount: 20,
currency: "EUR",
successUrl: "https://merchant.neonomics.io/order/41212/success",
failUrl: "https://merchant.neonomics.io/order/41212/fail",
cancelUrl: https://merchant.neonomics.io/order/41212/cancel,
language: "EN",
country: "NO"
}

Response body:

{
redirectUrl: https://checkout.neonomics.io/api/v1/checkoutrequests/JkuOIJHLSjhasodLJGHD.../app,
id: "0a15025d-824a-19c6-8182-7d5ab472002f"
}

In case structured payment data needs to be provided, the Request body should look like:

{
referenceId: "41212",
remittanceInfoStructured: {
reference: '1234',
referenceIssuer: 'John Dou',
referenceType:'KID' },
amount: 20,
currency: "EUR",
successUrl: "https://merchant.neonomics.io/order/41212/success",
failUrl: "https://merchant.neonomics.io/order/41212/fail",
cancelUrl: https://merchant.neonomics.io/order/41212/cancel,
language: "EN",
country: "NO"
}

3. Integration Examples to redirect users to Neonomics Checkout

Integrating with Neonomics Checkout follows two easy steps where you have to:

  1. Add a link/button to Neonomics Checkout in your Frontend
  2. Adjust the Back-End to call the endpoint mentioned above to submit the payment information and retrieve a unique URL which is then used to hand the user over to Neonomics Checkout.

After going through the checkout process, the user will be redirected back to the URL you specified in the redirect parameters depending on the result of the checkout (success, failure or cancellation). The following examples illustrates a setup using HTML and PHP, and HTML and Java. If you need help for other languages, please feel free to get in touch with us.

3.1 HTML and PHP integration

HTML Frontend: Place a "Pay Now" button or link on a page you wish your customers to complete the payments.

This HTML code adds to your website product information and a button which will initiate the whole process. The Pay Now button simply does a call towards the server-side plugin.

pay-now-button.html

<!DOCTYPE html>
<html>
<head>
<title>Merchant inc.</title>
</head>
<body>
<section>
<div class="product">
<div class="description">
<h3>Sweatshirt</h3>
<h5>20.00 NOK</h5>
</div>
</div>
<form action="pay-with-neonomics.php" method="POST">
<button type="submit" id="checkout-button">Pay Now</button>
</form>
</section>
</body>
</html>

PHP Server-Side: Plugin which triggers the call towards the Neonomics Checkout endpoint  

A click on the Front-End component would trigger the execution of the PHP code below. This is an example of how the server-side can initiate the process for creating a checkout request.

pay-with-neonomics.php

<?php
$curl = curl_init();  

$YOUR_DOMAIN = "http://localhost";  

$postData = [
  "referenceId" => "46cc77a44f0f40f8b7877c78d8bbd8e0", //Your Reference
  "amount" => 20.00,
  "currency" => "NOK",
  "successUrl" => "$YOUR_DOMAIN/success",
  "failUrl" => "$YOUR_DOMAIN/fail",
  "cancelUrl" => "$YOUR_DOMAIN/cancel",
  "remittanceInfo" => "Sweatshirt Order #85" // Remittance Information
  "language" => "EN"
  "country" => "NO"
];  

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://checkout.sandbox.neonomics.io/api/v1/checkout-requests',   CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode($postData),
  CURLOPT_HTTPHEADER => array(
    'api-key: 09e4201c-9ddb-4b65-bc95-975b7373qwer', // Your Api Key
    'Content-Type: application/json',
    'Accept: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);

$redirectUrl = json_decode($response, true)['redirectUrl']
; header("Location: $redirectUrl");
?>

Some fields explained:

YOUR_DOMAIN - here goes the domain in which the HTML snippet is being hosted.
For example https://-yourDomain-.com/cart

postData - the body of the request which will arrive on the checkout.sandbox.neonomics.io/api/v1/checkout-request endpoint. Note that all the fields are hardcoded in this example to illustrate the purpose. You might use dynamic data for these fields.

CURLOPT_URL - this is the Checkout Project Endpoint which will receive the request

api-key – API key generated when the Merchant was registered to have access to the Checkout Project.
Note that this key will identify the merchant to the endpoint and allow access afterward.

redirectUrl - received as a response from the Checkout Endpoint (example : https://checkout.sandbox.neonomics.io/app/checkouts/0a0a048f-7e4d-1955-817e-5281e0ec0026). Once this is received the page will automatically redirect to this URL (the end-user is forwarded to the Neonomics Checkout to perform the payment).

successUrl/failUrl/cancelUrl - represent your pages where the Neonomics Checkout will redirect to afterwards according to the outcome. For example, in case of success, the end-user could be redirected to: https://-yourDomain-.com/cart/successPage

3.2 Html and Java integration

HTML Frontend: Similar to the HTML example above, this code will make a POST request towards a Java endpoint.

pay-now-button.html

<!DOCTYPE html>
<html>
<head>
<title>Merchant inc.</title>
</head>
<body>
<section>
<div class="product">
<div class="description">
<h3>Sweatshirt</h3>
<h5>20.00 NOK</h5>
</div>
</div>
<form action="/pay-with-neonomics" method="POST">
<button type="submit" id="checkout-button">Pay Now</button>
</form>
</section>
</body>
</html>

Java Server-Side: Plugin which triggers the call towards the Neonomics Checkout endpoint  

Corresponding to the above outlined PHP code snippet, here an example in Java which could be referenced from the Frontend HTML code accordingly:

pay-with-neonomics.java

import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;
import org.json.JSONObject;  

import static spark.Spark.*;  

public class PayWithNeonomics {
       public static void main(String[] args) {
        PayWithNeonomicsSevice payWithNeonomicsSevice = new PayWithNeonomicsSevice();
        port(80);
        post("/pay-with-neonomics", (request, response) -> {
            String redirectUrl = payWithNeonomicsSevice.createCheckoutRequest();
            response.redirect(redirectUrl);
            return "";
          });
    }
    static class PayWithNeonomicsSevice {
        public String createCheckoutRequest() throws UnirestException {
            JSONObject requestBody = new JSONObject();
            requestBody.put("referenceId", "a6128c9f-8155-4e2e"); // Your Reference
            requestBody.put("amount", 12.24);
            requestBody.put("currency", "NOK");
            requestBody.put("country", "NO");
            requestBody.put("successUrl", "https://-yourDomain-.com/order/a6128c9f-81554e2e-b24f-7a65555b93c6/success");
            requestBody.put("failUrl", "https://-yourDomain-.com/order/a6128c9f-8155-4e2eb24f-7a65555b93c6/fail");
            requestBody.put("cancelUrl", "https://-yourDomain-.com/order/a6128c9f-8155-4e2eb24f-7a65555b93c6/cancel");
            requestBody.put("language", "EN");
               String redirectUrl = Unirest.post("https://checkout.sandbox.neonomics.io/api/v1/checkout-requests")
              .header("api-key", "4d3aacdb-54c1-4348-b09f-ed439590ae0f") // Your API Key
              .header("Content-Type", "application/json")
              .header("Accept", "application/json")
              .body(requestBody)
              .asJson().getBody().getObject()
              .getString("redirectUrl").toString();
              return redirectUrl;
        }
    }
  }

Final note:

If you need any further help with code implementations, please do not hesitate to get in touch with us!

‍

Checkout documentation
1. Client requirements1.1 Client integration steps2. Architecture overview2.1 Business context view2.2 System context view2.3 Integration specification2.3.1 Integration context view2.3.2 Rest API specification3. Integration examples to redirect user to Neonomics Checkout3.1 HTML and PHP integration3.2 HTML and Java integration
Webhook