📘

Prerequisites

You have completed the registration in the Merchant Portal and have made your first one-time payment. If you have not done these two steps, go back and create your Merchant Portal account by clicking here.

This documentation contains information on how to integrate an external system with Neonomics in order to receive Checkout payments status updates in real time.

Neonomics delivers the payments status updates through a Webhook (a URL with API key protection) that the customer needs to register on the Merchant portal.

Registration of the Webhook information

To receive the payments status updates that are initiated on Checkout, you first need to register the webhook information. The webhook information is specific to the organization.

1. Log in to the merchant portal.
2. Go to 'Company settings' section and select the Webhook tab
3. Input the URL (without https:// part) and the API key (mandatory) that the customer will use to authenticate requests coming from Neonomics. The API key can be of any format, it is customer’s responsibility to make this key secure enough.

This completes the registration of the Webhook information. Now you are ready to start listening for payments status updates on your Webhook.

Payment status update request and payload

Every time an update is detected by our Checkout system, the update event is delivered on the Webhook configured in the merchant portal. Checkout notification system performs the following call:

POST https://configured_webhook_on_merchant_portal

The request will contain an header called api-key with the value you set in the merchant portal when setting up the Webhook. Use this to verify that the request comes from Neonomics.

Request header:

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

Customers can expect the following body JSON in this request:

{  
    referenceId: String,  
    payment:  {  
        amount: Decimal,  
        currency: Enum(Currency),  
        remittanceInfo: String,  
    },  
    creditor:  {  
        name: String,  
        iban: String  
    },  
    debtor:  {  
        name: String,  
        iban: String  
    },  
    status: Enum(CheckoutStatus),  
    createdDate: String,  
    lastModifiedDate: String,
    abortReason: Enum(CheckoutAbortReason)
}

Fields definitions

Checkout statuses

The statuses below PAYMENT_INITIATED can only be reached after PAYMENT_INITIATED.

Retry mechanism

The Webhook expects a response with status code 200 on every request. In case any other response status code is received, the Webhook will reattempt to deliver the same event.

The retry strategy follows the exponential backoff, with a minimum delay of 10 seconds. The maximum time that an event can stay in our system without being delivered is 7 days. In other words, if the customer system does not process the event in 7 days, it will be lost.

Checkout notification service guaranties that every event will be delivered at least once. The customer should assume that it may receive duplicates.

The checkout notification service awaits for a response from the request for a total of 5 seconds. If the response is not received within that timeframe, the event will be considered not delivered and will reattempt the delivery at the next backoff.

Ordering of delivery of events

The events of a single payment are delivered in order. The second event will not be delivered if the first one has not been acknowledged, the third one will not be delivered if the second has not been acknowledged, etc.

The events of different payments are delivered in parallel. In other words, the customer should expect parallel requests incoming at the specified webhook.

📘

Want to follow along on the status of the connectivity?

Subscribe to our status page.