Operations

redeemVoucher

Redeems a voucher.

POST /redemptions

This operation is performed when a voucher is used as a form of tender. When used as a form of tender the consumer redeems the requestAmount against the voucher. The voucher vendor is responsible for authorizing the redemption. Once redeemed, the voucher may not be used as a form of tender again.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes A redemption request. RedemptionRequest

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation RedemptionResponse
201 Created RedemptionResponse
400 Bad Request ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

confirmRedeem

Confirm a voucher redemption request that completed successfully.

POST /redemptions/confirmations

Once a redemptionRequest has completed successfully there is typically no need to notify the voucher vendor of the successful completion of the sale. However, this API recognises that client implementations may be very familiar with dual message APIs and this confirmation operation is provided to achieve consistency across the API with respect to single vs dual message operations. By performing this operation the client indicates that no subsequent reversal of the redemption will be performed. Note though that the successful completion of the confirmRedemption operation does not guarantee that the voucher will not be refunded in future.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes A voucher redemption confirmation. BasicAdvice

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation BasicAdvice
202 Accepted BasicAdvice
400 Bad Request ErrorDetail
404 Not Found ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

reverseRedeem

Reverse a voucher redemption request.

POST /redemptions/reversals

If a voucherRedemption request fails with one of the 5xx HTTP statuses code, or no response was received within the timeout period, it must be reversed to ensure the vendor does not consider the voucher to be in redeemed state. reverseRedemption must be repeated until a final HTTP status code is received (i.e. not 5xx). reverseRedemption may be called repeatedly on the same voucher resource without negative effect. If a voucher redemption is reversed there is no need to perform a refund against the voucher.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes A voucher redemption reversal. BasicReversal

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation BasicReversal
202 Accepted BasicReversal
400 Bad Request ErrorDetail
404 Not Found ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

lookupRedemption

Looks up and returns the outcome of a prior voucher redemption.

GET /redemptions/{requestId}

This operation may be used to obtain the result of a previous redemption request. It returns one of five classes of response: the original approved response,the original error response, a HTTP status code of 102 if the original request is still being processed and no response is available yet, a HTTP status code of 403 if the client did not submit the original request and is therefore not permitted to obtain the response, a HTTP status code of 404 if the original request was not received.

Security

  • httpBasic

Request

Parameters

Name Located in Required Description Default Schema
requestId path yes The randomly generated UUID of this request. string

Response

Content-Type: application/json

Status Code Reason Response Model
102 Processing
200 OK RedemptionResponse
400 Bad Request ErrorDetail
403 Forbidden
404 Not Found
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

refundVoucher

Refunds a voucher.

POST /refunds

This operation is performed when a voucher was previously successfully redeemed. Should a consumer request a refund from the merchant, the merchant may use the refundVoucher operation to request the voucher be placed back into an unredeemed state. The voucher vendor is responsible for authorizing the refund. Once refunded, the voucher may be used as a form of tender again if allowed by the voucher vendor.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes A refund request. RefundRequest

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation RefundResponse
201 Created RefundResponse
400 Bad Request ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

confirmRefund

Confirm a voucher refund request that completed successfully.

POST /refunds/confirmations

Once a refundRequest has completed successfully there is typically no need to notify the voucher vendor of the successful completion of the refund. However, this API recognises that client implementations may be very familiar with dual message APIs and this confirmation operation is provided to achieve consistency across the API with respect to single vs dual message operations. However, by performing this operation the client indicates that no subsequent reversal of the refund will be performed.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes A voucher refund confirmation. BasicAdvice

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation BasicAdvice
202 Accepted BasicAdvice
400 Bad Request ErrorDetail
404 Not Found ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

reverseRefund

Reverse a voucher refund request.

POST /refunds/reversals

If a voucherRefund request fails with one of the 5xx HTTP statuses code, or no response was received within the timeout period, it must be reversed to ensure the vendor does not consider the voucher to be in a refunded state. reverseRefund must be repeated until a final HTTP status code is received (i.e. not 5xx). reverseRefund may be called repeatedly on the same voucher resource without negative effect.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes A voucher refund reversal. BasicReversal

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation BasicReversal
202 Accepted BasicReversal
400 Bad Request ErrorDetail
404 Not Found ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

lookupVoucher

Lookup a voucher using the voucher code.

GET /vouchers

This operation is used to verify the validity of a voucher and possibly establish the value of a previously issued voucher (if supported by the server). This operation has no financial impact and is informative only.

Security

  • httpBasic

Request

Parameters

Name Located in Required Description Default Schema
voucherCode query no The voucher code to be looked up. string
provisionRequestId query no The provision request id that was part of the original provision request to obtain a voucher. string
receiverInstId query no The institution which issued the voucher. This assists to direct the voucher lookup request if the destination cannot be determined from the voucher code alone. string
settlementEntityInstId query no The institution via which the lookup should be processed. This serves to better direct the lookup request in the case that multiple upstream parties are able to process the request. string
voucherSerialNumber query no The serial number of the voucher being looked up. string

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation VoucherLookupResponse
202 Accepted VoucherLookupResponse
400 Bad Request ErrorDetail
404 Not Found ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

provisionVoucher

Request a voucher be provisioned.

POST 504

Requests a voucher from the voucher vendor.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes A provision request. ProvisionRequest

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation ProvisionResponse
201 Created ProvisionResponse
400 Bad Request ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

confirmVoucher

Confirm a voucher provision request that completed successfully.

POST /vouchers/confirmations

Once a consumer has paid for a voucher and received the voucher from the merchant the merchant must notify the vendor that the voucher may be redeemed at some point in the future as per the voucher vendor's instructions. confirmVoucher must be repeated until a final HTTP status code is received (i.e. not HTTP 5xx). confirmVoucher may be called repeatedly on the same voucher resource without negative effect.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes A voucher provision confirmation. TenderAdvice

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation TenderAdvice
202 Accepted TenderAdvice
400 Bad Request ErrorDetail
404 Not Found ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

reverseVoucher

Reverse a voucher provision request that failed or timed out.

POST /vouchers/reversals

If a voucherProvision request fails with one of the 5xx HTTP statuses code, or no response was received within the timeout period, it must be reversed to ensure the vendor knows to never expect further messages pertaining to the voucher. reverseVoucher must be repeated until a final HTTP status code is received (i.e. not 5xx). reverseVoucher may be called repeatedly on the same voucher resource without negative effect.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes A voucher provision reversal. BasicReversal

Response

Content-Type: application/json

Status Code Reason Response Model
200 successful operation BasicReversal
202 Accepted BasicReversal
400 Bad Request ErrorDetail
404 Not Found ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail