Gateway Emulator
The emulated RTGS.global Gateway APIs are provided as endpoints exposed within Docker containers but do not interact with the RTGS.global Network
Gateway Emulator allows you to try out and get experience of our API and responses, before the Integration phase of onboarding
"You do you"
This quick start guide can be used to get up and running with RTGS.global APIs in a few steps without having to deploy any Azure components.
Keep in mind that new features and functionality are deployed in the Emulator first, providing early access and allowing for integration planning, meaning the Emulator is consistently ahead of the Sandbox and Production platform capabilities.
RTGS.global Emulator APIs
The RTGS.global emulator APIs are provided in a Docker image which can be run on your preferred host environment. This provides a view of the APIs for invoking the RTGS.global workflows.
Contracts and behaviours mirror RTGS.global APIs, but are simulated and do not interact with any external systems. Endpoints are asynchronous in nature and results are posted back to a webhook with a CloudEvent message schema.
Production systems use EventGrid to provide result messages. If you choose to integrate using your own webhooks then resulting payloads are representative.
Deploying the Gateway Emulator
The gateway emulator is provided as container image that runs on Docker® Engine. The gateway-emulator is intended to be run on a local desktop development environment and not as a centralized server-side application. The gateway emulator can be found on Docker Hub here:
Getting started
If Docker is not installed on your local development environment please refer to the Docker website and follow their guide to prepare your machine to host and run Docker containers.
You will need to have endpoints available that mimic two participants on the RTGS.global Network to receive the full suite of notifications. This can be done on your local environment by creating webhooks that can accept POST requests. Using a service such as request catcher will make things easier to begin with.
This guide focuses on the use of request catcher to provide the webhook endpoints. If this does not reflect your development environment, you can disregard details related to request catcher use. The operation of the emulator and the API endpoint specifications are the same regardless.
Note: If you do intend to create your own webhooks you cannot use a self-signed certificate so either use HTTP, or HTTPS with a trusted SSL certificate.
When Docker is successfully installed, retrieve the latest gateway-emulator image from a command shell using:
Next, on the request catcher portal create two sub domains. To aid understanding of the operations and configuration, it is recommended that two request catcher browser tabs are opened where one is used to create a domain to reflect your own organization, and the other to create a partner organization you are communicating with.
Figures 1 and 2 below depict an example of two distinct sub domains created using request catcher.
Next, in a command shell, start the gateway-emulator container by issuing the command below, passing the webhook URLs as environment variables ParticipantWebhookUrl and CounterpartyWebhookUrl:
Now open the gateway-emulator Swagger documentation, invoking the API endpoints by navigating to http://localhost:3001/swagger/index.html
General behaviours
A valid HTTP POST request to an endpoint will cause a 202 ACCEPTED HTTP response to be returned. Result messages will be re-issued by the emulator as POST requests to the respectively configured ParticipantWebhookUrl and CounterpartyWebhookUrl.
The webhook handling the result message should respond with a 2xx status code. Non-2xx responses will be retried a further 4 times with exponential back-off, starting at 1 second.
OpenAPI/Swagger documentation including the detailed request/response contracts of all endpoints is available at: /localhost:3001/swagger/v1/swagger.json
Error scenarios
To test out different gateway-emulator error scenarios you can pass specific values as inputs in the request to trigger the error response. The webhooks will be then called with appropriate payloads which will contain the details of the "error" that occurred.
Details on how to generate error scenarios for different product services use case can be found on the Emulator docker hub page
Testing: Using the gateway-emulator APIs will enable you to identify and design the changes that will need to be made to the systems that will be leveraging the RTGS.global settlement fabric. It is acknowledged that using the emulator in isolation will only provide the actual interface contracts and messages exchanged. It is also envisaged however that enhancements needed to your internal systems can be fully unit tested whilst running against the emulator and greatly expedite your route to live.
Support
A high-level set of instructions are provided in the following sections to configure a local development environment. These instructions are complete but provide little detail in how the local environment is configured and no support information is provided in respect to troubleshooting environment issues. However, if you are experiencing problems when following the instructions provided, please do contact support@rtgs.com.
The gateway emulator is provided as-is and though considered effort is made to ensure it functions properly please understand that it is not guaranteed to be always completely error free and as such therefore comes with no warranties. It is also updated frequently so it is recommended that regular pulls of the latest image from Docker Hub are performed. We do however take great care to ensure that the swaggers are accurate, so if you encounter a mismatch in an API definition and its operation inside the emulator please do raise it with us and we will prioritize its resolution with you.
License and Copyright
The gateway emulator is free to everyone who wishes to use it. It can only be used in standalone development environments and therefore cannot be used to replace the RTGS.global gateway or to prove the operation of the gateway. It cannot be offered for resale as a product or service and cannot be bundled with any other product or service even if any such product or service is provided for free to users.
Last updated
