The simplified webhooks workflow allows you to retrieve real-time information about payment, payout, spendback, and application events.

Preparation flow

The preparation stage consists of three tasks.

Set up one or more URLs on the merchant server to listen for POST requests from Nexio.

You can use a service like webhook.site to get a unique, random URL that you can use to test and debug webhooks and HTTP requests.
Set up actions to take for potential webhooks. For example, ignoring transaction events from alternative payment methods (APMs) or routing transactions from an authorize-only workflow to a queue for transactions to be captured or identifying payouts that have expired and updating account information accordingly.
Register the URL or URLs with the Nexio API. For the steps to take, see Registering webhooks.

The following flow diagram corresponds to the preparation flow detailed above.

Preparation flow diagram

Event flow

The general flow for an event is the same regardless of the event type.

An event happens (the run card or run echeck transaction, the payout request, the spendback request, or the application request) for a specific merchant ID (MID) and the request goes to the Nexio server.
Nexio sends the request to the appropriate connection or payment method, based on the settings for the MID.
Nexio receives an initial response from the connection.
Nexio sends that response to the event and to all configured webhooks for that event.
Nexio pings the connection server for status changes to the transaction, payout, spendback, or application.
Nexio sends the information about the status change to all configured webhooks for that event.

For the steps to complete the event flow, see Receiving webhooks.

The following event flow diagram corresponds to the flow detailed above.

Event flow diagram

Receive webhook flow

The merchant server receives webhooks from Nexio at the registered URLs.

When a transaction, payout, or spendback event happens, it automatically triggers a webhook, whether it was successful or failed. However, this webhook has no additional information or meaning than the initial response to the request.

For example, an initial transactionStatus may be 10 (or 12 for echecks), indicating that the transaction has been successfully authorized and is pending settlement. Usually, the status changes almost immediately to 20, indicating that the transaction settled successfully.

So, look for the next webhook about that transaction to know when the status changes. For example, when the status changes to 20. In the case of a status change from 10 or 12 to 20, you may want to ignore the webhook. However, if the status is not 20, then you may want to initiate an action. For example, if there is an error or the status changes to voided. Or, for the case where you do an authorize-only transaction and then capture later, the status changes as those events happen (from authOnlyPending to authOnly).

For payouts, the transferStatus or payoutStatus may change. Typically, you will only be looking for a payoutStatus change, however. You may not need to do anything for a status change to 12 (pending recipient action) or 20 (completed). But may want to do something if the status changes to 11 (pending merchant action). Or, if the payout expires and returns a status of 30, you want want to update your own records and account balance.

For spendbacks, the spendbackStatus may change and has similar changes as for payout events, including spendbacks that need to be reviewed, that were canceled, or that have expired.

For onboarding applications, the credsReady status may change, pending items may be updated or notes made about the application, application information may change, or the application status may change. Use the repCode to identify the account to use and the onboardingId to use the View application by onboarding ID endpoint to get more information about the application.

The following receive webhook flow diagram corresponds to the information detailed above.

Receive webhook flow diagram

Overall flow

The following diagram indicates the combined flow for simplified webhooks. The numbered actions correspond to the event flow:

Webhooks