Webhook: payment status updates

๐Ÿ“˜

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 Nello Pay 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 Nello Pay, 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 Nello Pay system, the update event is delivered on the Webhook configured in the merchant portal. Nello Pay 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

ParametersDescriptions
idThe id that is returned when creating an checkout using the checkout-request endpoint. This is unique for each checkout it should be used to track the updates from the webhook for each checkout payment.
referenceIdThe customer reference identifier provided in the checkout request
payment.amountThe 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.originalAmountThe original payment amount of the current checkout
payment.scheduledDateThe scheduled date for payment in YYYY-MM-DD format. Applicable for scheduled payments only.
payment.currencyThe currency of the payment amount that follows ISO 4217
payment.remittanceInfoThe remittance information associated to the current checkout
creditor.nameThe name of the creditor
creditor.ibanThe IBAN of the creditor
debtor.nameThe name of the debtor
debtor.ibanThe IBAN of the debtor
CreatedDateThe date when the checkout was created
lastModifiedDateThe last update of the checkout
abortReasonThis field can be populated when the status is TIMED_OUT or CANCELLED and the user has attempted a payment but failed and didn't finish the checkout. Possible values: INSUFFICIENT_FUNDS, LIMIT_EXCEEDED, PAYMENT_NOTAUTH, BANK_ERROR

Checkout statuses

ParametersDescriptionsNote
STARTEDUser was redirected to Nello PayWill always be sent
CANCELLEDUser cancelled the payment within Nello PayFinal update
FAILEDThe payment failed within Nello PayFinal update
TIMED_OUTThe Nello Pay session reached the time limit and was terminatedFinal update
PAYMENT_CREATEDThe user started the payment but has not yet authorized itWill be sent if SCA is needed
PAYMENT_INITIATEDThe user authorized the paymentFinal end user step
PAYMENT_COMPLETEDOur payment poller has detected that the funds have been settledFinal update
PAYMENT_FAILEDOur payment poller has detected that the payment failedFinal update
PAYMENT_CANCELLEDOur payment poller has detected that the user manually canceled the paymentFinal update
PAYMENT_NONTRACKABLEThe payment was successfully initiated by the end user but the bank has stopped providing updates about the paymentFinal update

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.