APIs typically operate in a synchronous manner. This is where a client makes a request to a server and then waits for the server to process the request. Once the server has finished processing, it returns the desired output to the client in a response messge. In this model the client always initiates the communication and the server responds. The response serves as both an acknowledgement that the request has been received, and the result of the processing that was requested.
It has become increasingly common, however, for applications to make use of asynchronous API behaviour. In the asynchronous — or event-driven — model there is no notion of a client and a server. Rather there are simply two parties that either send or receive messages using the protocol and format specified by the API. When a message is received from Party A, it can be immediately acknowledged by Party B, but the result of the processing will be delivered to Party A as a separate notification sent by Party B. Note that even if a request is positively acknowledged, the result of the processing may be a negative outcome.
The Electrum Regulated Payments API makes use of asynchronous calls for its core functions, but does contain some synchronous auxilliary operations.
Electrum can communicate to a partner's system either as API calls to an HTTP endpoint hosted by the partner, or as notifications to a webhook endpoint. You may choose to receive these notifications by either method. There is no inherent benefit of one approach over the other, so the choice will likely depend on which is more convenient given your system's architecture.
Before implementation, you will need to communicate your choice to Electrum and specify the endpoints on which you will receive incoming messages.
The basic asynchronous workflow for sending requests:
- Send a request to the Electrum API. This could be to initiate a new transaction, or to convey the result of a processing step.
- Electrum will immediately acknowledge receipt of the request, or reject it with a technical error .
- If the request was not rejected, then Electrum processes it against the relevant payment scheme.
The basic asynchronous workflow for receiving notifications on API endpoints is:
- Receive a request from Electrum on your API endpoint.
- Immediately acknowledge receipt of the request, or reject it with a technical error .
- If the request was not rejected, then process it accordingly.
The basic asynchronous workflow for receiving notifications via webhooks is:
- Receive an event notification from Electrum on your webhook endpoint.
- Immediately acknowledge receipt of the notification.
- Process the message accordingly.
Regardless of your method of implementation, make sure your processing and response times are in line with the time limits mandated by each scheme.