rtgsglobal/gateway-emulator repository overview

⁠RTGS.global Gateway Emulator

⁠Introduction

An API emulator for trying out the RTGS.global payment workflows.

Contracts and behaviours match the real RTGS.global API, but are entirely 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 webhooks then result payloads are representative.

⁠Getting started

You'll need an API endpoint (webhook) that the emulator can invoke.

Either:

1. create an API that can accept a POST request, or
2. use a service such as request catcher⁠

Note: you cannot use a self-signed certificate so either use HTTP or HTTPS with a trusted SSL certificate.

Retrieve the latest image using the command:

docker pull rtgsglobal/gateway-emulator

Start the container, passing the webhook urls as environment variables ParticipantWebhookUrl and CounterpartyWebhookUrl:

docker run -it -p 3001:8080/tcp -e "ParticipantWebhookUrl=[your-initiating-bank-webhook-url]" -e "CounterpartyWebhookUrl=[your-partner-bank-webhook-url]" rtgsglobal/gateway-emulator

Open the Swagger documentation / invoke the endpoints by navigating to http://localhost:3001/swagger/index.html⁠

⁠Behaviours

A valid POST request to an endpoint will cause a 202 ACCEPTED response to be returned. One or more result messages will be issued as POST requests to the 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 detailed request/response contracts are available at: /swagger/index.html

⁠Request Catcher

When using request catcher⁠, it is recommended to create a single subdomain and use different paths for the participant and counterparty webhooks. For example;

docker run -it -p 3001:8080/tcp -e "ParticipantWebhookUrl=https://[subdomain].requestcatcher.com/participant/" -e "CounterpartyWebhookUrl=https://[subdomain].requestcatcher.com/counterparty/" rtgsglobal/gateway-emulator

⁠Possible responses

⁠Funds

⁠Fund/Defund

To emulate a defund workflow, include defund in the EndToEndId field of the request.

To emulate a fund workflow, include fund in the EndToEndId field of the request.

⁠Validation

Funds performs synchronous validation checks on the shape of the incoming message. Failure of any initial validation checks will cause a 400 BAD REQUEST response to be returned containing details of the failure:

{
  "FICdtTrf.CdtTrfTxInf[0]": [
    "'FICdtTrf.CdtTrfTxInf[0]' is missing child properties."
  ],
  "FICdtTrf.CdtTrfTxInf[0].IntrBkSttlmAmt": [
    "'IntrBkSttlmAmt' must not be empty."
  ]
}

⁠Status Updates

Assuming that initial validation has succeeded, subsequent status updates will be provided via the webhook mechanism described above.

The main response code is returned by the TransactionStatus field. It indicates high level status of the operation:

• Pending 'PDNG'
• SettlementInProgress 'ACSP'
• AcceptedSettlementCompleted 'ACSC'
• Rejected 'RJCT'

More detailed information on possible responses can be found in the table below:

⁠Payaway

Payaway performs synchronous validation checks on the shape of the incoming message. Failure of any initial validation checks will cause a 400 BAD REQUEST response to be returned containing details of the failure:

{
  "FIToFICstmrCdtTrf.CdtTrfTxInf[0]": [
    "'FIToFICstmrCdtTrf.CdtTrfTxInf[0]' is missing child properties."
  ],
  "FIToFICstmrCdtTrf.CdtTrfTxInf[0].CdtrAgt.FinInstnId": [
    "'BICFI' or 'LEI' must be provided."
  ],
  "FIToFICstmrCdtTrf.CdtTrfTxInf[0].IntrBkSttlmAmt": [
    "'IntrBkSttlmAmt' must not be empty."
  ]
}

Assuming that initial validation has succeeded, subsequent status updates will be provided via the webhook mechanism described above.

The main response code is returned by the TransactionStatus field. It indicates high level status of the operation:

• Pending 'PDNG'
• SettlementComplete 'ACSC'
• Completed 'ACCC'
• Rejected 'RJCT'

More detailed information on possible responses can be found in the table below:

⁠LinkAndSettle

The high level LinkAndSettle request status is returned in the TransactionStatus field, the possible values are:

• Completed 'ACCC'
• AcceptedSettlementInProcess 'ACSP'
• Pending 'PDNG'
• AcceptedWithoutPosting 'ACWP'
• Rejected 'RJCT'
• Cancelled 'CANC'

The following table identifies all the different transaction statuses and related status reasons returned on notifications:

⁠Testing error scenarios

To test out different error scenarios you can pass specific values as inputs in the request. The webhooks will be called with appropriate payloads.

⁠Funds scenarios

There is 1 endpoint, v1/funds/move, for the move funds workflow.

Include any of Testing Code values from the Funds possible responses table⁠ above in the EndToEndId field of the request to trigger the corresponding error scenario.

⁠Payaway scenarios

There is 1 endpoint, v1/payaway, for the Payaway workflow.

Include any of StatusReason6Choice/Code values from the Payaway possible responses table⁠ above in the EndToEndId field of the request to trigger the corresponding error scenario.

⁠LinkAndSettle scenarios

The endpoint, v1/linkandsettle/link, is for the LinkAndSettle workflow.

Include any of StatusReason6Choice/Code values from the LinkAndSettle possible responses table⁠ on MsgId of the request to trigger the corresponding error scenario. In order to trigger error scenarios with proprietary reason, use any of the following values on MsgId:

• OwnInsufficientFunds
• CounterpartyInsufficientFunds
• CounterpartyNotFound
• CounterpartyInvalid
• OwnIdentifierInCounterpartyField
• CurrencyMismatch
• VerificationFailed

The endpoint v1/linkandsettle/cancel is for the LinkAndSettle cancel workflow.

When cancelling a link with no corresponding link from a counterparty:

• Participant should expect a notification with CANC status and CancelledAsPerRequest reason.
• Counterparty should expect a notification with CANC status and CounterpartyRequestCancelled reason.

When cancelling a link where a corresponding request was sent from counterparty:

• Participant should expect a notification with CANC status and CancelledAsPerRequest reason.
• Counterparty should expect a notification with PDNG status and CounterpartyRequestCancelled reason.

Note: Debit and credit amounts and currencies are hard coded with dummy data for notifications sent as a part of cancel workflow.

To trigger cancelling a link where a corresponding request was sent from counterparty but failed to settle, include any of the following as the Identification field in the body of the message.

• CurrencyMismatch
• WrongAmount
• OwnInsufficientFunds
• CounterpartyInsufficientFunds

Debit and credit amounts and currencies will be hardcoded in the status update

To trigger the corresponding error scenario for the cancel endpoint, include any of the following as the Identification field in the body of the message.

• LinkIdentifiersOrUetrNotFound
• LinkAlreadySettled
• VerificationFailed

⁠FICreditTransfer scenarios

The endpoint, 'v1/credit/transfer', is for the FICreditTransfer workflow.

At the moment, it just implements validation and will return either 202 if the post request is valid, or 400 if the request is invalid.

⁠FX Quotes

Four POST endpoints exist for requesting and receiving FX quotes:

• '/v1/quote/request'
• '/v1/quote/offer'
• '/v1/quote/new-order-single'
• '/v1/quote/execution-report'

plus there is an additional GET endpoint for retrieving supported currency pairs:

• '/v1/quote/currency-pairs'

Terminology used:

• The initiating participant is the participant who initiates the FX Quote process by issuing a quote request.
• The counterparty participant is the participant who is identified by the initiating participant in their quote request and is expected to respond with their quote.

Expected message flow and sequence:

1. The initiating participant issues a quote request identifying desired counterparty participants.

   The counterparties field will accept any RTGS.global id, except RTGS:B:12345BAD. Including RTGS:B:12345BAD will trigger an invalid RTGS.global id validation error.

   The symbol specified in the quote request must match one of the currency pairs returned by the '/v1/quote/currency-pairs' endpoint, otherwise a validation error will be returned.

2. Some or all counterparty participants respond to the quote request with their quote.

3. The initiating participant examines the set of received quotes and calls the New Order (single) endpoint with the details of the quote that suits them best.

4. The counterparty participant who received the New Order (single) event responds with the Execution report to signify whether the order is confirmed and can be settled, or cancelled and will not go ahead.

For end to end processing, please use the same identifier across your quote, order and settlement messages. Where you are the quote requester, QuoteReqId > ClOrdId > LinkId, and where you are the responder, QuoteId > OrderId > LinkId

More detailed endpoint documentation can be found here: https://rtgs-global.gitbook.io/participant-and-central-bank-guide/participant-guide/api-and-documentation/api-documentation⁠

⁠Support

If you need any support getting up and running please contact the RTGS.global team.