Vouchers

Vouchers can be used as mean of payments and are treated like a "prepaid card". Therefor vouchers are added as payment details and their value is deducted from the amount left to pay. The value of a voucher must be determined the latest just before initializing the payment. In general there can be vouchers with a fixed value or a value which is dependent of the content of the order. So be aware that tha value of a voucher can change during the processing of an order.

Supported vouchers¶

The list of supported voucher providers:

E-Guma

Which voucher providers are supported in the order can be requested on the service. If there are no voucher providers returned then the "redeem voucher" input field should not be displayed to the guest.

RequestResponse

GET https://api.discover.swiss/test/market/v1/orders/{orderId}/voucherproviders

{
    "voucherProviders": [
        "EGuma"
    ]
}

Integration / Onboarding¶

To be able to use vouchers in orders please contact support.

Usage¶

Vouchers can be managed in an order only when all requirements are met.

Requirements¶

Vouchers can be added/deleted until the order has not been Paid yet.
Solution provider and the supplier of the product supports (has integrated) vouchers of the specific provider and organisation.
The voucher has a positive balance.

Add voucher to the order¶

If the order status is less then Paid - then the voucher will be validated and added to the order with its full available balance.

If order status is equal to Payment - then voucher will be validated and added to the order with full available balance. The order will be moved back to the Placed state. It will be necessary to initialize the payment again.

A voucher code will be tried to be used in all available voucher providers for the current order.

RequestRequest linkResponse

{
    "Code": "ABCD-EFG1-HIJK"
}

POST https://api.discover.swiss/test/market/v1/orders/{orderId}/voucher

{
    "validationMessages": [],
    "paymentDetail": {
        "id": "ebc91dd6-f54c-4b8a-b48b-87947cc2fcf5",
        "paymentType": "voucher",
        "paymentIntentId": "ABCDEFG1HIJK",
        "orderPaymentStatus": "New",
        "paymentProvider": "EGuma",
        "amountCurrency": 5.0,
        "currency": "CHF"
    }
}

Remove voucher from the order¶

It is possible to remove any voucher from the order until order has been Paid.
Use the PayentDetail.id to remove the voucher.

Request linkResponse

DELETE https://api.discover.swiss/test/market/v1/orders/{orderId}/voucher/{paymentDetailsId}

StatusCode: 200

View list of vouchers in the order¶

The list of added vouchers is available in the regular order response.

Vouchers are stored together with the rest of payments and in the OrderPaymentDetailsList property of the order.

A voucher in the order-response is represented as an OrderPaymentDetailsResponse object with the PaymentType property equal to voucher. The paymentIntentId contains the voucher code.

Sample of the order response with voucher:

{
    ...
    "orderPaymentDetailsList": [
        {
            "id": "ebc91dd6-f54c-4b8a-b48b-87947cc2fcf5",
            "paymentType": "voucher",
            "paymentIntentId": "ABCDEFG1HIJK",
            "orderPaymentStatus": "New",
            "paymentProvider": "EGuma",
            "amountCurrency": 5.0,
            "currency": "CHF",
            "description": "Balance: 20"
        }
    ],
    ...
}

Payment¶

Vouchers will be charged with the amount of money which does not exceed the total amount of the order.

Vouchers are charged according to FIFO principle. That mean that voucher which was added earlier (compared by PaymentDate) will be charged first. Vouchers for which is no amount left to be charged (e.g. previous voucher cover full price of order) - will be cancelled.

The amount left after charging the vouchers is what must be paid by the regular payment process.

Info

If during the initialization of payment all vouchers will be Initialized and total of vouchers will cover the full price of the order and there is nothing left to pay, the order will be automatically moved to Paid state without user interaction and the fulfillment gets started directly.

Warning

If it is not possible to charge amount of money which were in the voucher on the moment of payment initialization (e.g. current balance is less than it was) - order will be canceled and charged money refunded.

Refunds¶

PaymentDetails are refunded in the reversed order as they have been charged. That means, we first refund the payment by card and then the vouchers.

Update the amount of the vouchers in the order to the value they will be charged¶

This call is not mandatory, but going throught the process above there is no way you can see what the actual amount which will be charged on the voucher will be, before you initialize the payment. This steps calculates these amounts according to the current situation in the order. The balance of the voucher (maximal available amount) is written in the description property. The amount of the voucher paymentDetail will may change next time you call this endpoint or inititialize the payment, but it will not change automatically if you add more products to the order.

Request linkResponse

PUT https://api.discover.swiss/test/market/v1/orders/{orderId}/voucher

{
    "totalAmount": 50.0,
    "totalAmountCHF": 50.0,
    "totalAmountExcludingVouchers": 30.0,
    "totalAmountExcludingVouchersCHF": 30.0,
    "vouchers": [
        {
            "id": "ebc91dd6-f54c-4b8a-b48b-87947cc2fcf5",
            "paymentType": "voucher",
            "paymentIntentId": "5LRUXSHCGQJ4",
            "orderPaymentStatus": "Initialized",
            "paymentProvider": "EGuma",
            "amountCurrency": 5.0,
            "currency": "CHF",
            "description": "Balance: 5"
        },
        {
            "id": "bfb4bd0a-776a-4b76-a039-4fa751f2f9ba",
            "paymentType": "voucher",
            "paymentIntentId": "CVBP3PSX5KH3",
            "orderPaymentStatus": "New",
            "paymentProvider": "EGuma",
            "amountCurrency": 15.0,
            "currency": "CHF",
            "description": "Balance: 20"
        }
    ],
    "validationMessages": []
}