The APEXX API notifies of transaction outcomes through API responses and through webhooks.
1. API Responses
API responses are synchronous messages, which means that they will always be sent as a result of a prior, outgoing transaction request.
Responses for declined and failed transactions will contain both an error or reason code, and an associated reason message. These can be used by the merchant application to display the transaction result to the web user.
In case a transaction fails for a technical reason, the API response will contain an error code. Please refer to the APEXX API documentation for a full list of error codes.
If the transaction is declined by the card issuer, the API response includes a reason code. ISO 8583 offers a standardised format for reason codes, but is not used by all banks. Where an issuing bank is using its own list of reason codes, APEXX will map the code internally and send the ISO code in the API response instead. A list of the ISO reason codes used by APEXX can be found here.
2. Webhooks
Webhooks are asynchronous, which means that these messages are not sent as direct responses to a prior transaction request. The communication to the merchant application is initiated by APEXX and is triggered by some kind of external event, for example a reconciliation file import that updates captured transactions to settled status.
The URL for the webhook endpoint can either be configured against a specific account by your APEXX Implementation Consultant, or sent dynamically in the payment request. Webhook URLs included in a transaction request will override any URL set on the account. Note that the top level domain of any URL received in a transaction request must match the top level domain configured on the corresponding account in APEXX.
The merchant will need to provide an application that processes the incoming webhook events and returns a response message to APEXX. If APEXX does not receive a message indicating that the event update was successfully received, it will attempt to resend the update at a later point in time.