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.
- Log in to the merchant portal.
- 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 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
Parameters | Descriptions |
---|---|
id | The 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. |
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. |
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 |
CreatedDate | The date when the checkout was created |
lastModifiedDate | The last update of the checkout |
abortReason | This 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
Parameters | Descriptions | Note |
---|---|---|
STARTED | User was redirected to Nello Pay | Will always be sent |
CANCELLED | User cancelled the payment within Nello Pay | Final update |
FAILED | The payment failed within Nello Pay | Final update |
TIMED_OUT | The Nello Pay session reached the time limit and was terminated | Final update |
PAYMENT_CREATED | The user started the payment but has not yet authorized it | Will be sent if SCA is needed |
PAYMENT_INITIATED | The user authorized the payment | Final end user step |
PAYMENT_COMPLETED | Our payment poller has detected that the funds have been settled | Final update |
PAYMENT_FAILED | Our payment poller has detected that the payment failed | Final update |
PAYMENT_CANCELLED | Our payment poller has detected that the user manually canceled the payment | Final update |
PAYMENT_NONTRACKABLE | The payment was successfully initiated by the end user but the bank has stopped providing updates about the payment | Final 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.
Updated 27 days ago