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.
The basic asynchronous workflow for sending requests to the API is as follows:
- 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 requests on API endpoints is as follows:
- 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.
- Once processing is complete, communicate the outcome with Electrum as a new API request.
Make sure your processing and response times are in line with the time limits mandated by each scheme.