Asynchronous API Operations through AMQP
Overview
Several API operations cannot be completed within the scope of a normal HTTP request. For example, a settlement request might take more than 24 hours to reach a settled state or to provide risk assessment reply, and sending an HTTP response within a realistic read timeout interval is not possible.
Operations that can potentially take a long time to complete need a way to send an asynchronous reply/event message to the original caller.
Advanced Message Queuing Protocol (AMQP)
Asynchronous reply/event messages that take a long time to complete are sent to queues on an externally-exposed RabbitMQ server. RabbitMQ is an open-source message broker that implements the AMQP standard. API clients using these asynchronous operations must run AMQP consumers to process reply/event messages as they become available in these queues.
Using AMQP for asynchronous reply/event messages rather than alternative approaches such as http polling or callbacks has the following advantages:
- AMQP can reliably deliver messages through message acknowledgments. If an unrecoverable error occurs when processing a message and an acknowledgment is not sent, the broker redelivers the message in the future, guaranteeing at-least-once delivery.
- All communication with the broker can take place over a single, client-initiated connection. No firewall configuration changes are needed at the client site, as would be the case with callbacks.
- Clients connect to port 443 (the default HTTPS port), which most likely is already an open port if using a firewall. This AMQP connection is significantly less "chatty" than a polling API operation.
Payment Service Asynchronous API Operations
The Payment Service uses the following asynchronous API operations:
Risk Service Asynchronous API Operations
The Risk Service uses the following asynchronous API operations:
Processing Flow
The asynchronous API operations follow the same basic processing flow:
- The order management system requests an asynchronous API operation.
- The operation completes the necessary processing.
- The operation sends a reply/event message to the order management system over AMQP.
- The order management system processes and/or persists the message.
- The order management system sends an acknowledgment message to the message broker.
Queued Messages
A message stays in the queue until the consumer process (the order management system) acknowledges the message. If your order management system does not consume messages for a period of time, the number of messages in your queue will grow. When that number exceeds 5000 messages, the system will alert Radial's operations team, and Radial will consult with you about the queued messages. If you remain unable to consume the messages within an agreed time frame, Radial will purge the messages to free up the queue for further processing.
Asynchronous API Operations through Webhooks
If client/partner chooses Webhooks for asynchronous operations, see Asynchronous API Operations through Webhooks.