I 48 Accept Payment Vouchers - UnionInternationalCheminsdeFer/OSDM GitHub Wiki

I-48 Accept Payment-Vouchers

Description

Support for the use of vouchers when buying new tickets.

Vouchers might be issued in case of accepted compensation claims or reimboursements. The customer should be able to use these vouchers when buying new products.

Owner

  • Ralf Bayer (DB)
  • Clemens Gantert (DB/UIC)

Business Value

For allocators

who issue vouchers when reimbursing certain tickets or in compensation claims

the ability to redeem such vouchers in new bookings

is a necessary feature

that completes the life cycle of these vouchers.

Business Outcomes

Happy customers who can use their vouchers for further business.

Leading Indicators

The early measures that will help predict the business outcome hypothesis.

Nonfunctional Requirements

Nonfunctional requirements (NFRs) associated with the epic.

No specific requirements.

Specification Effort: MEDIUM

Context

Legal requirements

When issuing vouchers, the allocator also needs to allow these vouchers to be redeemed.

Regarding VAT, these vouchers are treated like other means of payment, i.e. they do not affect the ticket price or the VAT to be paid on the purchase.

Scope

Issuing and reedeeming of vouchers is only relevant for the allocator-ticket vendor API. It is not relevant in the allocator-carrier API.

Implementation ideas

Issuing of vouchers

Vouchers are issued as fulfillments both in compensation claims and in after sales (i.e. refund of certain tariffs, e.g. DB Sparpreis) transactions.

FulfillmentDocument.type allows to indicate vouchers.

Redeeming of vouchers

Vouchers can be added to a pre-booking, so that the validity of the voucher can be assessed by the allocator. When the booking is confirmed, the voucher is invalidated in the allocator's system.

API: extend the BookingRequest so that it can hold a structure similar to the promotionCodes in parallel to this:

paymentVouchers: 
  type: array
  items:
    $ref: "#/components/schemas/PaymentVoucher"

with PaymentVoucher having the properties "code" and "issuer", similar to the PromotionCode.

Alternatively: change the existing PromotionCode structure / promotionCodes attribute to something that covers both promotion vouchers / codes and payment vouchers / code, i.e. keep the structure but rename it. Disadvantage is that this would be a breaking change to the API.

Note that overpayment (i.e. voucher value is greater than the value of the products) can be handled in two ways without affecting the API:

  • the value of the voucher is reduced
  • the voucher is invalidated and a new voucher for the remaining value is issued

Both alternatives can be handled without affecting the API.

Offer Parts

Vouchers will be modeled as an ancillary.

After sales of bookings involving vouchers

When a booking which was partially or fully paid with a voucher, there are again two options:

  • the original vouchers can be re-instated, any vouchers issued due to over payment are cancelled
  • a new voucher is generated to cover the amount paid by voucher, any vouchers issued in the booking process remain valid

Security

Note that the voucher codes are basically the equivalent of cash, so they need to be communicated carefully.

Providers may decide to only send them to the email of the purchaser and not transmit them over the API.