Test Server

Electrum hosts a number of test servers that can be used to test that an Electrum API has been implemented correctly.

The QR Code Payments test server replicates the behaviour of the Electrum Switch by validating incoming API request payloads and returning a relevant API response. Each QR Code Payments operation can be tested against the following base URL endpoint:

https://wiremock.exosphere.electrum.dev

The Electrum QR Code Payment Service Interface Documentation and the Electrum QR Code Payment Service Implementation Guide specify how each QR Code Payment operation must be implemented and populated.

If a given request does not follow the Electrum specification, the test server will return a mismatch error detailing the formatting issue of the delivered API request.

Authorisation

The Electrum test servers have a built-in mock OAuth 2.0 authorisation scheme. All requests to the Electrum test server require an 'Authorization' header.

To acquire an OAuth 2.0 token, Electrum has a generic service to generate new tokens:

Authorisation Details

Access Token Url: https://auth.electrum.dev/auth/realms/Mock-Server-Switch-Testing/protocol/openid-connect/token

Client Id: electrum-test-client

Client Secret: 83a9a5d0-60a0-4a04-a5b9-ea708953b777

Grant Type: Client Credentials

Alternatively, if you will not be calling or making use of OAuth 2.0 token generation while integrating with the test servers, you can manually set the authorisation header to match the following format and regex:

Plain text
‘Authorization’ : Bearer\s[A-Za-z0-9-]+.[A-Za-z0-9-]+.[A-Za-z0-9-_]+$

Scenarios

There are a number of different test scenarios for each operation. To ensure that you route requests to the correct test scenario, populate the id field in the request payload with a designated suffix value.

Scenario	Description	Designated suffix value
Success	The originating system receives a successful API response from Electrum.	[any string]000100
Delayed	The originating system receives a delayed API response from Electrum, outside of the originating system’s internal timeout period.	[any string]000200
Timeout 1	The originating system receives no response from Electrum.	[any string]000300
Timeout 2	The originating system receives a timeout error message from Electrum, indicating that the upstream entity did not respond.	[any string]000301
Decline 1	The originating system receives a `GENERAL_ERROR` error message from Electrum.	[any string]000400
Decline 2	The originating system receives a `FORMAT_ERROR` error message from Electrum.	[any string]000401

Operations

The Electrum QR Code Payments test server facilitates routing to API endpoints, mirroring the conventional Electrum endpoint format.

The supported operations, the request method, the endpoints, and the available test scenarios are listed below. Route requests to the correct test scenario by populating the id field in the request payload with the designated suffix value.

Note

Not all scenarios are available for every operation. The notifyScan, confirmPayment, and reversePayment operations support only the Success, Timeout 2, and Decline 1 scenarios. If you attempt to trigger a scenario that is not supported by a particular operation then this will result in a mismatch error from the test server.

Operation	Method	Endpoint	Routing field	Available scenarios
`createQrCode`	`POST`	`/qr/v1/qrCodes`	`id`	Success, Delayed, Timeout 1, Timeout 2, Decline 1, Decline 2
`pay`	`POST`	`/qr/v1/payments`	`id`	Success, Delayed, Timeout 1, Timeout 2, Decline 1, Decline 2
`notifyScan`	`POST`	`/scans`	`id`	Success, Timeout 2, Decline 1
`confirmPayment`	`POST`	`/qr/v1/payments/confirmations`	`id`	Success, Timeout 2, Decline 1
`reversePayment`	`POST`	`/qr/v1/payments/reversals`	`id`	Success, Timeout 2, Decline 1

The operations listed above encompass the full set of available API requests that can be tested against the Electrum QR Code Payments test server. Originating systems and/or service providers should utilise only operations that are relevant to their specific integration.

Static Response Values

The test server will populate (using generic values) all fields in an API response message that the VAS service provider would typically populate in a real transaction.

So, there may be instances where the response message contains an optional field that is not required for your specific project integration. You can ignore these fields if they are not relevant to your specific integration.

Usage Notes

All responses received from the test server are populated with generic test data.
Ensure that all requests sent to the test server use the correct HTTP method (POST) for all QR operations. Information on request payloads is available on the Electrum QR Code Payment Service Interface Documentation.
The notifyScan operation is initiated by the payment partner/service provider (e.g., PayJustNow) towards Electrum when a consumer scans the displayed QR code. Electrum acknowledges receipt with an HTTP 202 response before processing the payment authorisation.
The pay operation supports both payment authorisation (tranType = GOODS_AND_SERVICES) and refund processing (tranType = RETURNS). Ensure the appropriate tranType value is set when testing each flow.
The tranId field links a pay request to its preceding createQrCode response. The tranId returned by createQrCode must be included in the subsequent pay request payload.
The allowedPartners field should be populated in both createQrCode and pay requests to enable Electrum to validate partners.
Confirmation (confirmPayment) and reversal (reversePayment) messages are sent as store-and-forward (SAF) advice messages.