Using Vouchers With APIv3

Owned by Nigel Martin
Last updated: Jun 23, 2017 by Nick Naves
19 min read

This article will outline the process behind paying using a voucher in APIv3. This article assumes the user has already taken the steps to set up a valid voucher /wiki/spaces/II/pages/9839915.

In the booking and reservation payment requests there is a portion dedicated to voucher payment. If present and properly populated with valid data, this information can be use to pay for a reservation. Here is what the voucher section of the booking XML looks like:

This is located under the 'Payment' node in the booking request.

                        <int1:RedeemVoucher>
                            <int1:CurrencyCode>?</int1:CurrencyCode>
                            <int1:Firstname>?</int1:Firstname>
                            <int1:Lastname>?</int1:Lastname>
                            <int1:PIN>?</int1:PIN>
                            <int1:Password>?</int1:Password>
                            <int1:RedeemAmount>0</int1:RedeemAmount>
                            <int1:SerialNumber>?</int1:SerialNumber>
                        </int1:RedeemVoucher>

In order to get the required information to complete this request, the user must first get the voucher they wish to use. This can be achieved by using the 'GetVoucher()' operation under the Booking service. Here is a sample of that request:

        <tem:GetVoucher>
            <tem:request>
                <int:Password>123</int:Password>
                <int:Pin>123</int:Pin>
                <int:RequestedCurrencyCode>USD</int:RequestedCurrencyCode>
                <int:SerialNumber>VKBQY0LZAO</int:SerialNumber>
            </tem:request>
        </tem:GetVoucher>
  • The voucher may not require a password and pin depending on how it was originally setup
  • If the voucher you are looking for is not returning, verify that the currency code in the request is correct

The response of this request will look something like the following:

                <a:Voucher xmlns:b="http://schemas.datacontract.org/2004/07/InteliSys.Amelia">
                    <b:Airports>
                        <b:VoucherAirports>
                            <b:Arrival>
                                <b:Code>GOM</b:Code>
                                <b:Name>Goma International</b:Name>
                            </b:Arrival>
                            <b:Departure>
                                <b:Code>ABL</b:Code>
                                <b:Name>Athabasca Lodge</b:Name>
                            </b:Departure>
                        </b:VoucherAirports>
                        <b:VoucherAirports>
                            <b:Arrival>
                                <b:Code>YMM</b:Code>
                                <b:Name>Fort McMurray</b:Name>
                            </b:Arrival>
                            <b:Departure>
                                <b:Code>ABL</b:Code>
                                <b:Name>Athabasca Lodge</b:Name>
                            </b:Departure>
                        </b:VoucherAirports>
                    </b:Airports>
                    <b:Available>1</b:Available>
                    <b:Companies>
                        <b:VoucherCompany>
                            <b:Code>68686868</b:Code>
                            <b:Name>ABC Travel</b:Name>
                        </b:VoucherCompany>
                        <b:VoucherCompany>
                            <b:Code>5</b:Code>
                            <b:Name>XYZ Sky</b:Name>
                        </b:VoucherCompany>
                    </b:Companies>
                    <b:Count>0</b:Count>
                    <b:Currency>
                        <b:Abbreviation>USD</b:Abbreviation>
                        <b:Description>US dollars</b:Description>
                        <b:ExchangeRate>1</b:ExchangeRate>
                        <b:Format>$#,##0.00</b:Format>
                    </b:Currency>
                    <b:CurrencyValue>0</b:CurrencyValue>
                    <b:DefinedCurrencyValue>0</b:DefinedCurrencyValue>
                    <b:DefinedValue>0</b:DefinedValue>
                    <b:Expires>2017-06-28T14:36:00</b:Expires>
                    <b:Fares>
                        <b:VoucherFare>
                            <b:Description>One Way Leisure</b:Description>
                            <b:Name>B</b:Name>
                        </b:VoucherFare>
                    </b:Fares>
                    <b:IncludeCharges>true</b:IncludeCharges>
                    <b:Name>TEST1</b:Name>
                    <b:PaxName i:nil="true"/>
                    <b:PinPasswordRequired>false</b:PinPasswordRequired>
                    <b:Purchased>false</b:Purchased>
                    <b:Status>Current</b:Status>
                    <b:Transferrable>false</b:Transferrable>
                    <b:UseOneTime>false</b:UseOneTime>
                    <b:UsePayment>true</b:UsePayment>
                    <b:ValidFrom>2016-12-29T00:00:00</b:ValidFrom>
                    <b:ValidTo>2017-01-07T23:59:00</b:ValidTo>
                    <b:Value>0</b:Value>
                </a:Voucher>

With this information, the user can populate the payment information and successfully pay using a voucher.

Worked Example

This example assumes the following criteria have been met:

  • The voucher has already been assigned to the passenger
  • The user has the serial number and pin/password (if applicable) for the voucher intended to be used

Step 1: Get the voucher

Run the GetVoucher request located under the booking service OR the GetVoucher request under the reservation payment service. Here is a sample of the request:

        <tem:GetVoucher>
            <tem:request>
                <int:Password>123</int:Password>
                <int:Pin>123</int:Pin>
                <int:RequestedCurrencyCode>USD</int:RequestedCurrencyCode>
                <int:SerialNumber>VKBQY0LZAO</int:SerialNumber>
            </tem:request>
        </tem:GetVoucher>

The response will look something like this:

                <a:Voucher xmlns:b="http://schemas.datacontract.org/2004/07/InteliSys.Amelia">
                    <b:Airports>
                        <b:VoucherAirports>
                            <b:Arrival>
                                <b:Code>GOM</b:Code>
                                <b:Name>Goma International</b:Name>
                            </b:Arrival>
                            <b:Departure>
                                <b:Code>ABL</b:Code>
                                <b:Name>Athabasca Lodge</b:Name>
                            </b:Departure>
                        </b:VoucherAirports>
                        <b:VoucherAirports>
                            <b:Arrival>
                                <b:Code>YMM</b:Code>
                                <b:Name>Fort McMurray</b:Name>
                            </b:Arrival>
                            <b:Departure>
                                <b:Code>ABL</b:Code>
                                <b:Name>Athabasca Lodge</b:Name>
                            </b:Departure>
                        </b:VoucherAirports>
                    </b:Airports>
                    <b:Available>1</b:Available>
                    <b:Companies>
                        <b:VoucherCompany>
                            <b:Code>68686868</b:Code>
                            <b:Name>ABC Travel</b:Name>
                        </b:VoucherCompany>
                        <b:VoucherCompany>
                            <b:Code>5</b:Code>
                            <b:Name>XYZ Sky</b:Name>
                        </b:VoucherCompany>
                    </b:Companies>
                    <b:Count>0</b:Count>
                    <b:Currency>
                        <b:Abbreviation>USD</b:Abbreviation>
                        <b:Description>US dollars</b:Description>
                        <b:ExchangeRate>1</b:ExchangeRate>
                        <b:Format>$#,##0.00</b:Format>
                    </b:Currency>
                    <b:CurrencyValue>0</b:CurrencyValue>
                    <b:DefinedCurrencyValue>0</b:DefinedCurrencyValue>
                    <b:DefinedValue>0</b:DefinedValue>
                    <b:Expires>2017-06-28T14:36:00</b:Expires>
                    <b:Fares>
                        <b:VoucherFare>
                            <b:Description>One Way Leisure</b:Description>
                            <b:Name>B</b:Name>
                        </b:VoucherFare>
                    </b:Fares>
                    <b:IncludeCharges>true</b:IncludeCharges>
                    <b:Name>TEST1</b:Name>
                    <b:PaxName>COLLINGS, CASSIDY</b:PaxName>
                    <b:PinPasswordRequired>false</b:PinPasswordRequired>
                    <b:Purchased>false</b:Purchased>
                    <b:Status>Current</b:Status>
                    <b:Transferrable>false</b:Transferrable>
                    <b:UseOneTime>false</b:UseOneTime>
                    <b:UsePayment>true</b:UsePayment>
                    <b:ValidFrom>2016-12-29T00:00:00</b:ValidFrom>
                    <b:ValidTo>2017-01-07T23:59:00</b:ValidTo>
                    <b:Value>0</b:Value>
                </a:Voucher>

Step 2: Put required information into the payment request

From the response of the above operation, take all required information and populate the payment portion of the reservation payment request. The request will look something like this:

If the voucher will not pay off the balance of the reservation. The Payment.PayBalance flag needs to be set to false or else the voucher will become unusable. This is caused by AMELIA-6487


        <tem:ReservationPayment>
            <tem:reservationPaymentRequest>
                <int:Payment>
                    <int1:CurrencyCode>USD</int1:CurrencyCode>
                    <int1:PayAllPassengers>true</int1:PayAllPassengers>
                    <int1:PayBalance>true</int1:PayBalance>
                    <int1:Payment>
                        <int1:Amount>139.29</int1:Amount> <-------------------- Amount owing on res
                        <int1:CurrencyCode>USD</int1:CurrencyCode> <----------- Payment currency
                        <int1:PaymentType>VoucherOnly</int1:PaymentType>
                        <int1:ProcessingFee>0</int1:ProcessingFee> <----------- Will be zero unless setup differently 
                        <int1:ProcessingFeeTax>0</int1:ProcessingFeeTax>
                        <int1:RedeemVoucher>
                            <int1:CurrencyCode>USD</int1:CurrencyCode>
                            <int1:Firstname>Cassidy</int1:Firstname>
                            <int1:Lastname>Collings</int1:Lastname>
                            <int1:PIN>123</int1:PIN>
                            <int1:Password>123</int1:Password>
                            <int1:RedeemAmount>139.29</int1:RedeemAmount>
                            <int1:SerialNumber>VKBQY0LZAO</int1:SerialNumber>
                        </int1:RedeemVoucher>
                    </int1:Payment>
                    <int1:ReservationNumber>11438</int1:ReservationNumber>
                </int:Payment>
            </tem:reservationPaymentRequest>
        </tem:ReservationPayment>

Step 3: Submit the request and review the response

If the request is successful the operation message should say 'OK' and OperationSucceeded should be 'true':

        <ReservationPaymentResponse xmlns="http://tempuri.org/">
            <ReservationPaymentResult xmlns:a="http://schemas.datacontract.org/2004/07/InteliSys.Amelia.API" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
                <a:AuditKey>b06c3c8f-8aa0-4779-ae18-6b04c3cddfb1</a:AuditKey>
                <a:OperationMessage>OK</a:OperationMessage>
                <a:OperationSucceeded>true</a:OperationSucceeded>
                <a:OperationUID>b06c3c8f-8aa0-4779-ae18-6b04c3cddfb1</a:OperationUID>
                <a:PaymentResult......

Also, under the 'Payments' node it should show the Voucher payment:

                        <b:Payment>
                            <b:CurrencyAmount>139.29</b:CurrencyAmount>
                            <b:DatedLocal>2016-12-28T11:23:00</b:DatedLocal>
                            <b:DatedZulu>2016-12-28T16:23:00</b:DatedZulu>
                            <b:Description/>
                            <b:Firstname>CASSIDY</b:Firstname>
                            <b:Lastname>COLLINGS</b:Lastname>
                            <b:Payer>Collings, Cassidy</b:Payer>
                            <b:PaymentMethodCode>VO</b:PaymentMethodCode>
                            <b:ReceiptNumber>11202</b:ReceiptNumber>
                            <b:TakenBy>USERNAME</b:TakenBy>
                        </b:Payment>

Additional Information

  • Vouchers can be used for partial payments. The redeemed amount will be deducted from the reservations balance.

Common errors

  • Payment method not found
    → Verify that the users agency is setup for the voucher payment method.
    → If everything seems to be setup correctly, verify that the voucher payment method's Type Code is 'VO'. If the type code is anything else the payment will fail.
  • Voucher failed validation
    → This is almost always because the voucher is setup incorrectly. Verify that the voucher is valid on the day of travel for the reservation.
    → If it's still not working, check that the Fare Class/City Pairs/Company is applicable for the voucher you're trying to use.