Voucher provision for digital channels

Operations and Messages

The table below lists the single messaging transactions that make up digital voucher provisions and the API calls you will need to implement for your digital channel.

Message Flows

The voucher provision phase of a digital voucher purchase initiates the transaction and returns a digital voucher from the service provider. In the case of single messaging Electrum manages confirmation messages and reversals on behalf of the originating system.

The sections below describe successful voucher provision transactions and error scenarios.

Successful Voucher Provision

1. The originating system sends a POST call to the /vouchers API endpoint (provisionVoucher operation).
2. The API responds with a ProvisionResponse message payload containing the details of the voucher.
3. The transaction is complete.

Error or Timeout at Service Provider

1. The originating system sends a POST call to the /vouchers API endpoint (provisionVoucher operation).
2. A hard decline or other error is encountered at the service provider.
3. Electrum responds to the originating system with an HTTP status of 404 and an ErrorDetail message payload.
4. In the case of a hard decline, no further messaging is required from the originating system.

Timeout or Other Error at Electrum

1. The originating system sends a POST call to the /vouchers API endpoint (provisionVoucher operation).
2. Electrum forwards the ProvisionRequest message to the service provider.
3. A timeout (no response received) or other error is encountered at Electrum before receiving a successful ProvisionResponse from the service provider.
4. Electrum sends an ErrorDetail message payload to the originating system and immediately sends a reversal message to the service provider.

Timeout Downstream: Successful Retry

1. The originating system sends a POST call to the /vouchers API endpoint (provisionVoucher operation).
2. Electrum forwards the provisionRequest message to the service provider.
3. The service provider returns a provisionResponse message payload containing the details of the voucher to Electrum. Electrum forwards this response to the originating system.
4. A timeout occurs at the originating system.
5. The originating system initiates a retryProvisionVoucher to resubmit the transaction.
6. Electrum searches for the original transaction outcome and responds with a provisionResponse message payload containing the details of the voucher to the originating system.
7. The originating system successfully receives a response with the voucher details.

Timeout Downstream: Unsuccessful Retry

1. The originating system sends a POST call to the /vouchers API endpoint (provisionVoucher operation).
2. Electrum forwards the provisionRequest message to the service provider.
3. The service provider returns a provisionResponse message payload containing the details of the voucher to Electrum. Electrum forwards this response to the originating system.
4. A timeout occurs at the originating system.
5. The originating system initiates a retryProvisionVoucher to resubmit the transaction.
6. Electrum searches for the original transaction outcome and responds with an ErrorDetail message payload to the originating system.

If the originating system continues to time out before receiving a response from Electrum, it will send a BasicReversal message via a store-and-forward queue to Electrum, who will forward the message to the service provider as below:

Error Downstream: Timeout Persists

1. The originating system sends a POST call to the /vouchers API endpoint (provisionVoucher operation).
2. Electrum forwards the provisionRequest message to the service provider.
3. The service provider returns a provisionResponse message payload containing the details of the voucher to Electrum. Electrum forwards this response to the originating system.
4. A timeout occurs at the originating system.
5. The originating system initiates a retryProvisionVoucher to resubmit the transaction.
6. The originating system continues to time out before receiving a response from Electrum.
7. The originating system sends a BasicReversal message via a store-and-forward queue to Electrum.
8. Electrum forwards the BasicReversal message to the service provider and the service provider reverses the transaction.
9. Electrum forwards the response to the originating system.