Voucher provision for POS

Operations and Messages

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

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 dual messaging systems this is followed by a confirmation phase in which the transaction is confirmed.

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

Successful Voucher Provision: Dual Messaging

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 originating system sends a TenderAdvice confirmation message to the /vouchers/confirmations endpoint of the API (confirmVoucher.) Electrum immediately sends a TenderAdvice response back to the originating system. The confirmation message is sent to the service provider via a store-and-forward queue. The message is repeated until Electrum receives a response.

Successful Voucher Provision: Single Messaging

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 Originating System

1. The originating system sends a POST call to the /vouchers API endpoint (provisionVoucher operation).
2. A timeout (no response received) or other error is encountered at the originating system.
3. The originating system retries the ProvisionRequest (retryProvisionVoucher operation) up to three times (or more, depending on the originating system's business rules).
4. The originating system receives a successful ProvisionResponse containing the details of the voucher within three retries or fewer.
5. The transaction is concluded as follows according to one of the following scenarios.

• In the case of a single messaging system, the transaction is complete.
• In the case of a dual messaging system, the originating system sends a TenderAdvice confirmation message (confirmVoucher operation), and Electrum immediately sends a TenderAdvice response. Electrum sends a confirmation message to the service provider via a store-and-forward queue until a response is received.

Error or Timeout at Originating System: Retries Fail

1. The originating system sends a POST call to the /vouchers API endpoint (provisionVoucher operation).
2. A timeout (no response received) or other error is encountered at the originating system.
3. The originating system retries the ProvisionRequest (retryProvisionVoucher operation) up to three times (or more, depending on the originating system's business rules).
4. The originating system receives a timeout response after three retries. No voucher details are received.
5. The originating system sends a BasicReversal message to Electrum (reverseVoucher operation) and immediately receives a response.
6. Electrum sends a reversal message to the service provider – if the provider supports reversal messaging – via a store-and-forward queue until a response is received.

Error Upstream: Transaction Failed

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

If the error message indicates that the transaction outcome is unknown, then the provision request may be retried, as described below.

Error Upstream: Unknown Transaction Outcome

1. The originating system sends a POST call to the /vouchers API endpoint (provisionVoucher operation).
2. An error occurs at Electrum or the service provider.
3. Electrum responds to the originating system with an HTTP status of 500, 503, or 504, and an ErrorDetail message payload.
4. The error is due to a timeout or the ErrorDetail message contains an errorType of UPSTREAM_UNAVAILABLE or VOUCHER_STATUS_UNKNOWN.
5. The originating system retries the ProvisionRequest (retryProvisionVoucher operation) up to three times (or more, depending on the originating system's business rules).
6. The originating system receives a successful ProvisionResponse containing the details of the voucher within three retries or fewer.
7. The transaction is concluded according to one of the following scenarios.

• In the case of a single messaging system, the transaction is complete.
• In the case of a dual messaging system, the originating system sends a TenderAdvice confirmation message (confirmVoucher operation), and Electrum immediately sends a TenderAdvice response. Electrum sends a confirmation message to the service provider via a store-and-forward queue until a response is returned.

Error Upstream: Retries Fail

1. The originating system sends a POST call to the /vouchers API endpoint (provisionVoucher operation).
2. An error occurs at Electrum or the service provider.
3. Electrum responds to the originating system with an HTTP status of 500, 503, or 504, and an ErrorDetail message payload.
4. The error is due to a timeout or the ErrorDetail message contains an errorType of UPSTREAM_UNAVAILABLE or VOUCHER_STATUS_UNKNOWN.
5. The originating system retries the ProvisionRequest (retryProvisionVoucher operation) up to three times (or more, depending on the originating system's business rules).
6. The originating system either receives an ErrorDetail (hard decline) at any point, or does not receive a successful voucher response within the three retries.
7. The originating system sends a BasicReversal message to Electrum (reverseVoucher operation) and immediately receives a response.
8. Electrum sends a reversal message to the service provider – if the provider supports reversal messaging – via a store-and-forward queue until a response is returned.