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.
- Log in to the merchant portal: https://merchant.neonomics.io/login
- Go to 'Company settings' section and select the Webhook tab
- 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
Customers can expect the following body JSON in this request:
referenceId
The customer reference identifier provided in the checkout request
payment.amount
The actual payment amount of the current checkout. Set to be same as original amount. It is updated if user manually edited the amount of payment and this value is provided by bank. In some cases bank does not provide this data.
payment.originalAmount
The original payment amount of the current checkout
payment.scheduledDate
The scheduled date for payment in YYYY-MM-DD format. Applicable for scheduled payments only.Add new Status
payment.currency
The currency of the payment amount that follows ISO 4217
payment.remittanceInfo
The remittance information associated to the current checkout
creditor.name
The name of the creditor
creditor.iban
The IBAN of the creditor
debtor.name
The name of the debtor
debtor.iban
The IBAN of the debtor
Status
Checkout status, can be:
STARTED: User was redirected to the checkout // Non-Definitive.
CANCELLED: User cancelled the payment within the Checkout application // Definitive // cancelURL
FAILED: The payment failed within the checkout application // Definitive // failURL
TIMED_OUT: The checkout session reached the time limit and was terminated // Definitive // failURL
PAYMENT_CREATED: The user started the payment but has not yet authorized it // Non-Definitive.
PAYMENT_INITIATED: The user authorized the payment // Non-Definitive. // successURL
PAYMENT_COMPLETED: Our payment poller has detected that the funds have been settled // Definitive.
PAYMENT_FAILED: Our payment poller has detected that the payment failed // Definitive
PAYMENT_CANCELLED: Our payment poller has detected that the user manually canceled the payment // Definitive
PAYMENT_NONTRACKABLE: Our payment poller has detected that the user manually made some changes to the payment and their bank will not provide us with an updated status. // Definitive
The highlighted statuses are statuses that can only be received after
PAYMENT_INITIATED. This is what happens in the banking system after a payment has been initiated through Neonomics.
The statuses that have a URL mentioned are statuses that will coincide with a redirect
CreatedDate
The date when the checkout was created
lastModifiedDate
The last update of the checkout (payment status update)
Retry mechanism
The checkout notification service expects a response with status code 200 on every request. In case any other response status code is received, the checkout notification service 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.
