DRV STRING - Benutzerbeiträge [de]

Developers Area

2019-10-14T15:15:29Z

Neudeckh:

=== TODOs for the upcoming "Developer Camp" ===

* Create proof of concept application with STRING.
** Amadeus creates frontend (Martin)
** DaVinci / Phoenix Unlimited run as backends
* Create consistent style guide and apply to schemas
* Discuss authorization for STRING
** Built-in and/or HTTP based (e.g. OAuth2,...)
** Describe best/preferred practices
* Create external lists in for non trivial enums
** Reference and document in schema
** Make downloadable from wiki
* Documentation
** Further completion of in-schema documentation
** Further completion of wiki documentation
** Reference wiki documentation in schema where applicable
* Model and document ConfigurationRequest and ConfigurationResponse
* Discuss payment models
* Create table or graph of possible request-response sequences
* Simulate/Test workflow for cruises (Desktop Test)
* Create JIRA backlog for the tasks that cannot be completed

Payment Handling

2018-07-11T17:05:18Z

Neudeckh: /* CreditCardPaymentType */

== General information ==

The payment handling, provided by '''Payments''' elements, allows
* The user to enter payments
* The Tour Operator to inform on expected, desired and effected payments

Additionally there are further "functions" available to the Tour Operator / Organizer '''''and thus''''' within responses only:
* '''PaymentOptions''' to inform about the supported Form Of Payment (FOP) and possibly associated fees (surcharges) respectively
* '''PaymentOverview''' to present a payment summary at one glance.

[[Datei:PaymentHandling.jpg|475px|rahmenlos]]

So far this all is offered by two messages, the '''BookingRequest/Response''' and the dedicated payment message '''PaymentRequest/Response'''. For both - and possibly any other messages in the future - this is done the same identical way.
Therefore the following views are performed independently from the underlying message.

At first we focus on '''Payments''', followed by '''PaymentOptions''' and '''PaymentOverview'''

Finally we will present some xml examples.
 
 

== Payments ==

With a '''request''' one might enter '''one or more payments''' whereas the '''''responses''''' will inform you on '''''all existing payments''''' (payment positions) of the "booking" at that point in time, independent from the channel these have been entered.

In both - request and response - the underlying basic structure/complex of a concrete payment is from '''PaymentType''', with different characteristics respectively extensions for request and response; but the basic information is always the same.

So '''PaymentsRequestType/PaymentsResponseType''' inherits from '''PaymentType''' respectively.

Further '''Payments''' always signalizes that we are dealing with one or more payments while '''Payment''' elements are used for one concrete payment respectively.

[[Datei:PaymentsRequest-Response.jpg|690px|rahmenlos]]

In the following we will describe the used request and response structures more in detail. However, we only will show the information that is helpful for a general understanding in the treated context “payment handling”. The complete information on all available elements, attributes, values etc. can be taken from the [[XSD Documentation]].

Another chapter is dedicated to the different Form Of Payment (FOP)

We will start with the description of the '''@Collection''' attribute, which substantively is identical for request and response, with the only difference that it is mandatory for the response.

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Collection'''|| This is used to inform on

* The available encashment types supported/allowed by the Tour Operator for the treated operation / booking / agency and/or customer (response) - therefor it is mandatory here
* The encashment type chosen/desired by the user (request)

''Please notice, when entered here this is valid for all payments of the booking as a whole.''

{| class="wikitable sortable"

| '''''Agency'''''|| For agency debiting
|-
| '''''TourOperator'''''|| For Tour Operator debiting; i.e. the customer directely pays to the Tour Operator

|-
| '''''OnSite'''''|| In case the payment must be made on site, e.g. a sports course offered by the hotel

''Normally used for a concrete payment only''

|-
| '''''Mixed'''''|| Makes sense in the response only. The intention is that the Tour operator explicitly informs that agency and/or tour operator debiting will be allowed.
|}

|}

'''''If a Tour Operator likes to restrict the payments on a specific encashment type he can do it on Payments level; e.g.: To prohibit agency debiting at all he can provide "TourOperator" here, with the consequence that all payments must directly be handled between customer and Tour Operator.'''''

In all other cases the Tour Operator must use "Mixed". The user then can decide per payment which encashment to be used, i.e. it also allows the mix of encashment types.
 
 
=== Payment Request ===

[[Datei:PaymentRequest(Type).jpg|451px|rahmenlos|ohne]]
 
A payment request indeed is realized as a variant of '''PaymentType'''. To be more precise, a specialization of '''PaymentType''' depending on the chosen ''Form Of Payment'' will be used respectively.
 
 
The available specialized payment types are listed in ###. But at first we will look onto the base type.
 
 
==== Available top-level attributes ====

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Identifier'''|| This is a unique identifier within one message, which can be used to reference on a concrete payment
|-
| '''@Collection'''|| Compare with explanations given above, please

''But notice, that here the attribute is attached to a concrete payment respectively''
|}
 
==== PaymentScope ====

This describes the purpose of the payment(s); it is an enumeration with the following values
{| class="wikitable sortable"
|-
! Value!! Explanation
|-
| '''''Balance'''''|| This is used to mark the total price to be paid to the organizer / Tour Operator, less any down payment.

Initially, this amount is specified together with a due date by the organizer / Tour Operator.
|-
| '''''Deposit'''''|| This is used to mark the down payment amount expected by the organizer / Tour Operator, which is initially specified by them together with a due date.
|-
| '''''Interim'''''|| This is used to mark an interim payment with an amount less than the remaining payment amount when the due date for the remaining payment has not yet been reached.

So this is also used for marking installments in the case of installment payments
|}
 
==== FormOfPayment ====
In the following the currently supported form of payments are listed, which are mostly self-explanatory.

{|
|-
|
* '''''CreditCard'''''
||
|-
|
* '''''DirectDebit'''''
||
|-
|
* '''''EBanking'''''
|| Account based FOP using the online banking account of an user, like Giropay and Sofortueberweisung
|-
|
* '''''EWallet'''''
|| Account based FOP, like PayPal and Paydirect
|-
|
* '''''Invoice'''''
||
|-
|
* '''''Installment'''''
||
|-
|
* '''''Voucher'''''
||
|}

Which of these are supported by the Tour Operator is communicated by him via '''PaymentOptions''' (see [[Payment_Handling#PaymentOptions|chapter PaymentOptions]], please)

A ''more detailed look on the supported FOPs can be found in chapter [[Payment_Handling#Specialized payment request types |Specialized payment request types]], ''
 
 

==== PaymentAmount ====

[[Datei:PaymentAmount - CurrencyAmountType.jpg|363px|rahmenlos]]

'''''Just to record it again, all (payment) amount fields are always formed from a decimal value and the ISO currency'''''
 
 
==== PaymentServiceProvider ====

[[Datei:PaymentServiceProvider(Type).jpg|477px|rahmenlos]]

This more or less is self-explanatory.

Beside the name of the Payment/Financial Service Provider and the URL on a logo of the same also a description/explanation can be indicated herewith.
 
 
==== CashHolder ====

[[Datei:CashHolder(Type).jpg|588px|rahmenlos]]

The Cash Holder is the "owner" of the treated FOP. He/she is the person who is contacted if something went wrong with the corresponding payment, like exceeded credit limit with a credit card or a failed direct deposit.

The Cash Holder can be a person already involved in the booking, either as traveller and/or as booking owner or another independent person. For all cases we have the possiblity to inform on that person, while avoiding redundancies:

{| class="wikitable"
|-
| '''AssignedToBookingOwner'''|| As there is only one booking owner existing, it is sufficient to flag this by a boolean
|-
| '''AssignedToTraveller'''|| As there are one or more traveller in the booking existing, one must enter an according reference here
|-
| '''OwnerDetails'''|| To provide name, address and (media) contact details of that person.

''A more detailed description of '''CommonAddressType''' can be found #here#''
|}
 
==== Specialized payment request types ====
As mentioned above, all the payment request types listed hereafter are specializations of '''PaymentType'''. So in the following only the respective extensions will be shown and if so explained more in detail.
 
 
===== InvoicePaymentType =====
[[Datei:InvoicePaymentType.JPG|509px|rahmenlos]]

 
This is an "empty" specialization of the base '''PaymentType'''. In case of an invoice payment this information is sufficient here because '''InvoiceAddress''' in the '''BookingDetails''' provides the informtion on a possible invoice recipient. If this information should not be present the invoice is to be addressed to the booking owner, which is a mandatory information provided by '''BookingOwnerAddress''' in the '''BookingDetails'''.
 
 

===== CreditCardPaymentType =====
[[Datei:CreditCardPaymentType.JPG|533px|rahmenlos]]

 
This is the PaymentType extended with credit card or PCI token information. '''PCIToken''', '''PCITokenIssuer''' and '''PCIBin''' are used when credit card tokenization is involved.

The credit card information shown here is mostly self-explanatory, only the '''CreditCard''' element respectively '''CreditCardType''' needs a more detailed explanation.

[[Datei:CreditCard.JPG|287px|rahmenlos]]
 
 

===== DirectDebitingPaymentType =====
[[Datei:DirectDebitPaymentType.JPG|667px|rahmenlos]]

 

===== EBankingPaymentType =====
[[Datei:EBankingPaymentType.JPG|670px|rahmenlos]]

 

===== EWalletPaymentType =====
[[Datei:EWalletPaymentType.JPG|412px|rahmenlos]]

 

===== InstallmentPaymentType =====
[[Datei:InstallmentPaymentType.JPG|653px|rahmenlos]]

 

===== VoucherPaymentType =====
[[Datei:VoucherPaymentType.JPG|447px|rahmenlos]]

 

=== Payment Response ===

As extension of the request we here have the following additional information

[[Datei:PaymentResponse(Type).jpg|rahmenlos|ohne]]

Here we describe only the newly added or changed elements in comparison to the request

We don't repeat the information here which is identical with the request part documented above.
 
 
==== Status ====
The following payment status we are dealing with.

{| class="wikitable sortable"
|-
! Status!! Explanation
|-
| '''''Open'''''|| This is the initial status when a payment (wish) by the Tour Operator (TO) has been announced respectively requested.

Normally the TO informs about the requested deposit and balance payments
|-
| '''''Recorded'''''|| This is the status, when the payment was entered in the travel agency, which only can be the case with agency debiting.

From customer point of view this is a relevant status, as the payment is done or at least triggered then; the regarding amount immediately appears as "paid"
|-
| '''''Settled'''''|| From TO view respectively its bookkeeping this is the most important status as it means that the TO received the money

|-
| '''''Failed'''''|| This means that a payment failed.

The Tour Operator or the Agency will have to clarify the according payment with the designated Cash Holder of the regarding payment
|-
| '''''Confirmed'''''|| ???
|}

The normal "status flow" will be
* In case of Agency debiting: '''''Open''''' => '''''Recorded''''' => '''''Settled'''''
* In case of Tour Operator debiting: '''''Open''''' => '''''Settled'''''

With retrieving a booking one can follow / monitor the payment status.
 
 
==== Dates ====

[[Datei:PaymentDates(Type).jpg|313px|rahmenlos]]

The Dates elemets are more or less self-explanatory.

{| class="wikitable"
|-
| '''DueDate'''|| The date on which the requested payment (e.g. deposit or balance) is expected by the Tour Operator
|-
| '''EntryDate'''|| The date on which the payment has been entered by the Travel Agency.

At that time the status of the payment status changes from "open" to "recorded"
|-
| '''SettlementDate'''|| The actual date of receipt of payment by the tour operator.

In case of Tour Operator debiting this is the time when payment status changes from "open" to "settled"
|}
 
==== PaymentDetails ====

[[Datei:PaymentDetails(Type).jpg|369px|rahmenlos]]

This complex is self explanatory. It should only be explicitly pointed out here that the fee amount is only the fee charged in connection with the chosen payment method.
 
 

== PaymentOptions ==

[[Datei:PaymentOption.JPG|677px|rahmenlos]]

With '''PaymentOptions''' the Tour Operator can inform on the supported payment options in case of a Tour Operator collection. 
Indeed one '''PaymentOption''' is used per accepted '''FormOfPayment'''.

''For agency debiting there must exist an agreement between TO and the agency which defines the payment processing, but this is out of scope here.''

In the following only the elements are explained which appears here for the first time.

{| class="wikitable"
|-
| '''FixedFee'''|| Total amount of the surcharge for the chosen FOP, to be added to the sales price
|-
| '''PercentFee'''|| Percentage share of the sales price to be added as surcharge for the chosen FOP to the same
|}
 

== PaymentOverview ==

 
 

== Visualization / Examples ==
So we might follow the following workflow:

1. Pricing request / quote
This will display the expected payments with a status "open" which at least is the total payable amount of the booking. In that case the

2. Book
Within the request you can enter one or more payments
With the according response one will receive back the correspondign status from Tour Operator perspective

3. Retrieve / display the booking
Herewith you will receive back respectively the latest status of the (entered) payments at that time

Datei:CreditCard.JPG

2018-07-11T17:02:53Z

Neudeckh:

2018-07-05T16:14:37Z

Neudeckh: /* PaymentOptions */

== General information ==

The payment handling, provided by '''Payments''' elements, allows
* The user to enter payments
* The Tour Operator to inform on expected, desired and effected payments

Additionally there are further "functions" available to the Tour Operator / Organizer '''''and thus''''' within responses only:
* '''PaymentOptions''' to inform about the supported Form Of Payment (FOP) and possibly associated fees (surcharges) respectively
* '''PaymentOverview''' to present a payment summary at one glance.

[[Datei:PaymentHandling.jpg|475px|rahmenlos]]

So far this all is offered by two messages, the '''BookingRequest/Response''' and the dedicated payment message '''PaymentRequest/Response'''. For both - and possibly any other messages in the future - this is done the same identical way.
Therefore the following views are performed independently from the underlying message.

At first we focus on '''Payments''', followed by '''PaymentOptions''' and '''PaymentOverview'''

Finally we will present some xml examples.

== Payments ==

With a '''request''' one might enter '''one or more payments''' whereas the '''''responses''''' will inform you on '''''all existing payments''''' (payment positions) of the "booking" at that point in time, independent from the channel these have been entered.

In both - request and response - the underlying basic structure/complex of a concrete payment is from '''PaymentType''', with different characteristics respectively extensions for request and response; but the basic information is always the same.

So '''PaymentsRequestType/PaymentsResponseType''' inherits from '''PaymentType''' respectively.

Further '''Payments''' always signalizes that we are dealing with one or more payments while '''Payment''' elements are used for one concrete payment respectively.

[[Datei:PaymentsRequest-Response.jpg|690px|rahmenlos]]

In the following we will describe the used request and response structures more in detail. However, we only will show the information that is helpful for a general understanding in the treated context “payment handling”. The complete information on all available elements, attributes, values etc. can be taken from the [[XSD Documentation]].

Another chapter is dedicated to the different Form Of Payment (FOP)

We will start with the description of the '''@Collection''' attribute, which substantively is identical for request and response, with the only difference that it is mandatory for the response.

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Collection'''|| This is used to inform on

* The available encashment types supported/allowed by the Tour Operator for the treated operation / booking / agency and/or customer (response) - therefor it is mandatory here
* The encashment type chosen/desired by the user (request)

''Please notice, when entered here this is valid for all payments of the booking as a whole.''

{| class="wikitable sortable"

| '''''Agency'''''|| For agency debiting
|-
| '''''TourOperator'''''|| For Tour Operator debiting; i.e. the customer directely pays to the Tour Operator

|-
| '''''OnSite'''''|| In case the payment must be made on site, e.g. a sports course offered by the hotel

''Normally used for a concrete payment only''

|-
| '''''Mixed'''''|| Makes sense in the response only. The intention is that the Tour operator explicitly informs that agency and/or tour operator debiting will be allowed.
|}

|}

'''''If a Tour Operator likes to restrict the payments on a specific encashment type he can do it on Payments level; e.g.: To prohibit agency debiting at all he can provide "TourOperator" here, with the consequence that all payments must directly be handled between customer and Tour Operator.'''''

In all other cases the Tour Operator must use "Mixed". The user then can decide per payment which encashment to be used, i.e. it also allows the mix of encashment types.

=== Payment Request ===

[[Datei:PaymentRequest(Type).jpg|451px|rahmenlos|ohne]]

==== Available top-level attributes ====

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Identifier'''|| This is a unique identifier within one message, which can be used to reference on a concrete payment
|-
| '''@Collection'''|| Compare with explanations given above, please

''But notice, that here the attribute is attached to a concrete payment respectively''
|}

==== PaymentScope ====

This describes the purpose of the payment(s); it is an enumeration with the following values
{| class="wikitable sortable"
|-
! Value!! Explanation
|-
| '''''Balance'''''|| This is used to mark the total price to be paid to the organizer / Tour Operator, less any down payment.

Initially, this amount is specified together with a due date by the organizer / Tour Operator.
|-
| '''''Deposit'''''|| This is used to mark the down payment amount expected by the organizer / Tour Operator, which is initially specified by them together with a due date.
|-
| '''''Interim'''''|| This is used to mark an interim payment with an amount less than the remaining payment amount when the due date for the remaining payment has not yet been reached.

So this is also used for marking installments in the case of installment payments
|}

==== FormOfPayment ====
In the following the currently supported form of payments are listed which are mostly self-explanatory

{|
|-
|
* '''''CreditCard'''''
||
|-
|
* '''''DirectDebit'''''
||
|-
|
* '''''EBanking'''''
|| Account based FOP using the online banking account of an user, like Giropay and Sofortueberweisung
|-
|
* '''''EWallet'''''
|| Account based FOP, like PayPal and Paydirect
|-
|
* '''''Invoice'''''
||
|-
|
* '''''Installement'''''
||
|-
|
* '''''Voucher'''''
||
|}

A ''more detailed look on the supported FOPs can be found in chapter #here#''

==== PaymentAmount ====

[[Datei:PaymentAmount - CurrencyAmountType.jpg|363px|rahmenlos]]

'''''Just to record it again, all (payment) amount fields are always formed from a decimal value and the ISO currency'''''

==== PaymentServiceProvider ====

[[Datei:PaymentServiceProvider(Type).jpg|477px|rahmenlos]]

This more or less is self-explanatory.

Beside the name of the Payment/Financial Service Provider and the URL on a logo of the same also a description/explanation can be indicated herewith.

==== CashHolder ====

[[Datei:CashHolder(Type).jpg|588px|rahmenlos]]

The Cash Holder is the "owner" of the treated FOP. He/she is the person who is contacted if something went wrong with the corresponding payment, like exceeded credit limit with a credit card or a failed direct deposit.

The Cash Holder can be a person already involved in the booking, either as traveller and/or as booking owner or another independent person. For all cases we have the possiblity to inform on that person, while avoiding redundancies:

{| class="wikitable"
|-
| '''AssignedToBookingOwner'''|| As there is only one booking owner existing, it is sufficient to flag this by a boolean
|-
| '''AssignedToTraveller'''|| As there are one or more traveller in the booking existing, one must enter an according reference here
|-
| '''OwnerDetails'''|| To provide name, address and (media) contact details of that person.

''A more detailed description of '''CommonAddressType''' can be found #here#''
|}

=== Payment Response ===

As extension of the request we here have the following additional information

[[Datei:PaymentResponse(Type).jpg|rahmenlos|ohne]]

Here we describe only the newly added or changed elements in comparison to the request

We don't repeat the information here which is identical with the request part documented above.

==== Status ====
The following payment status we are dealing with.

{| class="wikitable sortable"
|-
! Status!! Explanation
|-
| '''''Open'''''|| This is the initial status when a payment (wish) by the Tour Operator (TO) has been announced respectively requested.

Normally the TO informs about the requested deposit and balance payments
|-
| '''''Recorded'''''|| This is the status, when the payment was entered in the travel agency, which only can be the case with agency debiting.

From customer point of view this is a relevant status, as the payment is done or at least triggered then; the regarding amount immediately appears as "paid"
|-
| '''''Settled'''''|| From TO view respectively its bookkeeping this is the most important status as it means that the TO received the money

|-
| '''''Failed'''''|| This means that a payment failed.

The Tour Operator or the Agency will have to clarify the according payment with the designated Cash Holder of the regarding payment
|-
| '''''Confirmed'''''|| ???
|}

The normal "status flow" will be
* In case of Agency debiting: '''''Open''''' => '''''Recorded''''' => '''''Settled'''''
* In case of Tour Operator debiting: '''''Open''''' => '''''Settled'''''

With retrieving a booking one can follow / monitor the payment status.

==== Dates ====

[[Datei:PaymentDates(Type).jpg|313px|rahmenlos]]

The Dates elemets are more or less self-explanatory.

{| class="wikitable"
|-
| '''DueDate'''|| The date on which the requested payment (e.g. deposit or balance) is expected by the Tour Operator
|-
| '''EntryDate'''|| The date on which the payment has been entered by the Travel Agency.

At that time the status of the payment status changes from "open" to "recorded"
|-
| '''SettlementDate'''|| The actual date of receipt of payment by the tour operator.

In case of Tour Operator debiting this is the time when payment status changes from "open" to "settled"
|}

==== PaymentDetails ====

[[Datei:PaymentDetails(Type).jpg|369px|rahmenlos]]

This complex is self explanatory. It should only be explicitly pointed out here that the fee amount is only the fee charged in connection with the chosen payment method.

== PaymentOptions ==

[[Datei:PaymentOption.JPG|677px|rahmenlos]]

With '''PaymentOptions''' the Tour Operator can inform on the supported payment options in case of a Tour Operator collection. 
Indeed one '''PaymentOption''' is used per accepted '''FormOfPayment'''.

''For agency debiting there must exist an agreement between TO and the agency which defines the payment processing, but this is out of scope here.''

In the following only the elements are explained which appears here for the first time.

{| class="wikitable"
|-
| '''FixedFee'''|| Total amount of the surcharge for the chosen FOP, to be added to the sales price
|-
| '''PercentFee'''|| Percentage share of the sales price to be added as surcharge for the chosen FOP to the same
|}

== PaymentOverview ==

== Visualization / Examples ==
So we might follow the following workflow:

1. Pricing request / quote
This will display the expected payments with a status "open" which at least is the total payable amount of the booking. In that case the

2. Book
Within the request you can enter one or more payments
With the according response one will receive back the correspondign status from Tour Operator perspective

3. Retrieve / display the booking
Herewith you will receive back respectively the latest status of the (entered) payments at that time

Payment Handling

2018-07-05T15:55:04Z

Neudeckh: /* PaymentOptions */

== General information ==

The payment handling, provided by '''Payments''' elements, allows
* The user to enter payments
* The Tour Operator to inform on expected, desired and effected payments

Additionally there are further "functions" available to the Tour Operator / Organizer '''''and thus''''' within responses only:
* '''PaymentOptions''' to inform about the supported Form Of Payment (FOP) and possibly associated fees (surcharges) respectively
* '''PaymentOverview''' to present a payment summary at one glance.

[[Datei:PaymentHandling.jpg|475px|rahmenlos]]

So far this all is offered by two messages, the '''BookingRequest/Response''' and the dedicated payment message '''PaymentRequest/Response'''. For both - and possibly any other messages in the future - this is done the same identical way.
Therefore the following views are performed independently from the underlying message.

At first we focus on '''Payments''', followed by '''PaymentOptions''' and '''PaymentOverview'''

Finally we will present some xml examples.

== Payments ==

With a '''request''' one might enter '''one or more payments''' whereas the '''''responses''''' will inform you on '''''all existing payments''''' (payment positions) of the "booking" at that point in time, independent from the channel these have been entered.

In both - request and response - the underlying basic structure/complex of a concrete payment is from '''PaymentType''', with different characteristics respectively extensions for request and response; but the basic information is always the same.

So '''PaymentsRequestType/PaymentsResponseType''' inherits from '''PaymentType''' respectively.

Further '''Payments''' always signalizes that we are dealing with one or more payments while '''Payment''' elements are used for one concrete payment respectively.

[[Datei:PaymentsRequest-Response.jpg|690px|rahmenlos]]

In the following we will describe the used request and response structures more in detail. However, we only will show the information that is helpful for a general understanding in the treated context “payment handling”. The complete information on all available elements, attributes, values etc. can be taken from the [[XSD Documentation]].

Another chapter is dedicated to the different Form Of Payment (FOP)

We will start with the description of the '''@Collection''' attribute, which substantively is identical for request and response, with the only difference that it is mandatory for the response.

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Collection'''|| This is used to inform on

* The available encashment types supported/allowed by the Tour Operator for the treated operation / booking / agency and/or customer (response) - therefor it is mandatory here
* The encashment type chosen/desired by the user (request)

''Please notice, when entered here this is valid for all payments of the booking as a whole.''

{| class="wikitable sortable"

| '''''Agency'''''|| For agency debiting
|-
| '''''TourOperator'''''|| For Tour Operator debiting; i.e. the customer directely pays to the Tour Operator

|-
| '''''OnSite'''''|| In case the payment must be made on site, e.g. a sports course offered by the hotel

''Normally used for a concrete payment only''

|-
| '''''Mixed'''''|| Makes sense in the response only. The intention is that the Tour operator explicitly informs that agency and/or tour operator debiting will be allowed.
|}

|}

'''''If a Tour Operator likes to restrict the payments on a specific encashment type he can do it on Payments level; e.g.: To prohibit agency debiting at all he can provide "TourOperator" here, with the consequence that all payments must directly be handled between customer and Tour Operator.'''''

In all other cases the Tour Operator must use "Mixed". The user then can decide per payment which encashment to be used, i.e. it also allows the mix of encashment types.

=== Payment Request ===

[[Datei:PaymentRequest(Type).jpg|451px|rahmenlos|ohne]]

==== Available top-level attributes ====

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Identifier'''|| This is a unique identifier within one message, which can be used to reference on a concrete payment
|-
| '''@Collection'''|| Compare with explanations given above, please

''But notice, that here the attribute is attached to a concrete payment respectively''
|}

==== PaymentScope ====

This describes the purpose of the payment(s); it is an enumeration with the following values
{| class="wikitable sortable"
|-
! Value!! Explanation
|-
| '''''Balance'''''|| This is used to mark the total price to be paid to the organizer / Tour Operator, less any down payment.

Initially, this amount is specified together with a due date by the organizer / Tour Operator.
|-
| '''''Deposit'''''|| This is used to mark the down payment amount expected by the organizer / Tour Operator, which is initially specified by them together with a due date.
|-
| '''''Interim'''''|| This is used to mark an interim payment with an amount less than the remaining payment amount when the due date for the remaining payment has not yet been reached.

So this is also used for marking installments in the case of installment payments
|}

==== FormOfPayment ====
In the following the currently supported form of payments are listed which are mostly self-explanatory

{|
|-
|
* '''''CreditCard'''''
||
|-
|
* '''''DirectDebit'''''
||
|-
|
* '''''EBanking'''''
|| Account based FOP using the online banking account of an user, like Giropay and Sofortueberweisung
|-
|
* '''''EWallet'''''
|| Account based FOP, like PayPal and Paydirect
|-
|
* '''''Invoice'''''
||
|-
|
* '''''Installement'''''
||
|-
|
* '''''Voucher'''''
||
|}

A ''more detailed look on the supported FOPs can be found in chapter #here#''

==== PaymentAmount ====

[[Datei:PaymentAmount - CurrencyAmountType.jpg|363px|rahmenlos]]

'''''Just to record it again, all (payment) amount fields are always formed from a decimal value and the ISO currency'''''

==== PaymentServiceProvider ====

[[Datei:PaymentServiceProvider(Type).jpg|477px|rahmenlos]]

This more or less is self-explanatory.

Beside the name of the Payment/Financial Service Provider and the URL on a logo of the same also a description/explanation can be indicated herewith.

==== CashHolder ====

[[Datei:CashHolder(Type).jpg|588px|rahmenlos]]

The Cash Holder is the "owner" of the treated FOP. He/she is the person who is contacted if something went wrong with the corresponding payment, like exceeded credit limit with a credit card or a failed direct deposit.

The Cash Holder can be a person already involved in the booking, either as traveller and/or as booking owner or another independent person. For all cases we have the possiblity to inform on that person, while avoiding redundancies:

{| class="wikitable"
|-
| '''AssignedToBookingOwner'''|| As there is only one booking owner existing, it is sufficient to flag this by a boolean
|-
| '''AssignedToTraveller'''|| As there are one or more traveller in the booking existing, one must enter an according reference here
|-
| '''OwnerDetails'''|| To provide name, address and (media) contact details of that person.

''A more detailed description of '''CommonAddressType''' can be found #here#''
|}

=== Payment Response ===

As extension of the request we here have the following additional information

[[Datei:PaymentResponse(Type).jpg|rahmenlos|ohne]]

Here we describe only the newly added or changed elements in comparison to the request

We don't repeat the information here which is identical with the request part documented above.

==== Status ====
The following payment status we are dealing with.

{| class="wikitable sortable"
|-
! Status!! Explanation
|-
| '''''Open'''''|| This is the initial status when a payment (wish) by the Tour Operator (TO) has been announced respectively requested.

Normally the TO informs about the requested deposit and balance payments
|-
| '''''Recorded'''''|| This is the status, when the payment was entered in the travel agency, which only can be the case with agency debiting.

From customer point of view this is a relevant status, as the payment is done or at least triggered then; the regarding amount immediately appears as "paid"
|-
| '''''Settled'''''|| From TO view respectively its bookkeeping this is the most important status as it means that the TO received the money

|-
| '''''Failed'''''|| This means that a payment failed.

The Tour Operator or the Agency will have to clarify the according payment with the designated Cash Holder of the regarding payment
|-
| '''''Confirmed'''''|| ???
|}

The normal "status flow" will be
* In case of Agency debiting: '''''Open''''' => '''''Recorded''''' => '''''Settled'''''
* In case of Tour Operator debiting: '''''Open''''' => '''''Settled'''''

With retrieving a booking one can follow / monitor the payment status.

==== Dates ====

[[Datei:PaymentDates(Type).jpg|313px|rahmenlos]]

The Dates elemets are more or less self-explanatory.

{| class="wikitable"
|-
| '''DueDate'''|| The date on which the requested payment (e.g. deposit or balance) is expected by the Tour Operator
|-
| '''EntryDate'''|| The date on which the payment has been entered by the Travel Agency.

At that time the status of the payment status changes from "open" to "recorded"
|-
| '''SettlementDate'''|| The actual date of receipt of payment by the tour operator.

In case of Tour Operator debiting this is the time when payment status changes from "open" to "settled"
|}

==== PaymentDetails ====

[[Datei:PaymentDetails(Type).jpg|369px|rahmenlos]]

This complex is self explanatory. It should only be explicitly pointed out here that the fee amount is only the fee charged in connection with the chosen payment method.

== PaymentOptions ==

[[Datei:PaymentOption.JPG|677px|rahmenlos]]

With '''PaymentOptions''' the Tour Operator can inform on the supported payment options in case of a Tour Operator collection. 
Indeed one '''PaymentOption''' is used per accepted '''FormOfPayment'''.

''For agency debiting there must exist an agreement between TO and the agency which defines the payment processing, but this is out of scope here.''

In the following only the elements are explained which appears here for the first time.

== PaymentOverview ==

== Visualization / Examples ==
So we might follow the following workflow:

1. Pricing request / quote
This will display the expected payments with a status "open" which at least is the total payable amount of the booking. In that case the

2. Book
Within the request you can enter one or more payments
With the according response one will receive back the correspondign status from Tour Operator perspective

3. Retrieve / display the booking
Herewith you will receive back respectively the latest status of the (entered) payments at that time

Datei:PaymentDetails(Type).jpg

2018-07-05T15:51:13Z

Neudeckh: Neudeckh lud eine neue Version von Datei:PaymentDetails(Type).jpg hoch

Payment Handling

2018-07-05T15:42:45Z

Neudeckh: /* PaymentOptions */

== General information ==

The payment handling, provided by '''Payments''' elements, allows
* The user to enter payments
* The Tour Operator to inform on expected, desired and effected payments

Additionally there are further "functions" available to the Tour Operator / Organizer '''''and thus''''' within responses only:
* '''PaymentOptions''' to inform about the supported Form Of Payment (FOP) and possibly associated fees (surcharges) respectively
* '''PaymentOverview''' to present a payment summary at one glance.

[[Datei:PaymentHandling.jpg|475px|rahmenlos]]

So far this all is offered by two messages, the '''BookingRequest/Response''' and the dedicated payment message '''PaymentRequest/Response'''. For both - and possibly any other messages in the future - this is done the same identical way.
Therefore the following views are performed independently from the underlying message.

At first we focus on '''Payments''', followed by '''PaymentOptions''' and '''PaymentOverview'''

Finally we will present some xml examples.

== Payments ==

With a '''request''' one might enter '''one or more payments''' whereas the '''''responses''''' will inform you on '''''all existing payments''''' (payment positions) of the "booking" at that point in time, independent from the channel these have been entered.

In both - request and response - the underlying basic structure/complex of a concrete payment is from '''PaymentType''', with different characteristics respectively extensions for request and response; but the basic information is always the same.

So '''PaymentsRequestType/PaymentsResponseType''' inherits from '''PaymentType''' respectively.

Further '''Payments''' always signalizes that we are dealing with one or more payments while '''Payment''' elements are used for one concrete payment respectively.

[[Datei:PaymentsRequest-Response.jpg|690px|rahmenlos]]

In the following we will describe the used request and response structures more in detail. However, we only will show the information that is helpful for a general understanding in the treated context “payment handling”. The complete information on all available elements, attributes, values etc. can be taken from the [[XSD Documentation]].

Another chapter is dedicated to the different Form Of Payment (FOP)

We will start with the description of the '''@Collection''' attribute, which substantively is identical for request and response, with the only difference that it is mandatory for the response.

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Collection'''|| This is used to inform on

* The available encashment types supported/allowed by the Tour Operator for the treated operation / booking / agency and/or customer (response) - therefor it is mandatory here
* The encashment type chosen/desired by the user (request)

''Please notice, when entered here this is valid for all payments of the booking as a whole.''

{| class="wikitable sortable"

| '''''Agency'''''|| For agency debiting
|-
| '''''TourOperator'''''|| For Tour Operator debiting; i.e. the customer directely pays to the Tour Operator

|-
| '''''OnSite'''''|| In case the payment must be made on site, e.g. a sports course offered by the hotel

''Normally used for a concrete payment only''

|-
| '''''Mixed'''''|| Makes sense in the response only. The intention is that the Tour operator explicitly informs that agency and/or tour operator debiting will be allowed.
|}

|}

'''''If a Tour Operator likes to restrict the payments on a specific encashment type he can do it on Payments level; e.g.: To prohibit agency debiting at all he can provide "TourOperator" here, with the consequence that all payments must directly be handled between customer and Tour Operator.'''''

In all other cases the Tour Operator must use "Mixed". The user then can decide per payment which encashment to be used, i.e. it also allows the mix of encashment types.

=== Payment Request ===

[[Datei:PaymentRequest(Type).jpg|451px|rahmenlos|ohne]]

==== Available top-level attributes ====

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Identifier'''|| This is a unique identifier within one message, which can be used to reference on a concrete payment
|-
| '''@Collection'''|| Compare with explanations given above, please

''But notice, that here the attribute is attached to a concrete payment respectively''
|}

==== PaymentScope ====

This describes the purpose of the payment(s); it is an enumeration with the following values
{| class="wikitable sortable"
|-
! Value!! Explanation
|-
| '''''Balance'''''|| This is used to mark the total price to be paid to the organizer / Tour Operator, less any down payment.

Initially, this amount is specified together with a due date by the organizer / Tour Operator.
|-
| '''''Deposit'''''|| This is used to mark the down payment amount expected by the organizer / Tour Operator, which is initially specified by them together with a due date.
|-
| '''''Interim'''''|| This is used to mark an interim payment with an amount less than the remaining payment amount when the due date for the remaining payment has not yet been reached.

So this is also used for marking installments in the case of installment payments
|}

==== FormOfPayment ====
In the following the currently supported form of payments are listed which are mostly self-explanatory

{|
|-
|
* '''''CreditCard'''''
||
|-
|
* '''''DirectDebit'''''
||
|-
|
* '''''EBanking'''''
|| Account based FOP using the online banking account of an user, like Giropay and Sofortueberweisung
|-
|
* '''''EWallet'''''
|| Account based FOP, like PayPal and Paydirect
|-
|
* '''''Invoice'''''
||
|-
|
* '''''Installement'''''
||
|-
|
* '''''Voucher'''''
||
|}

A ''more detailed look on the supported FOPs can be found in chapter #here#''

==== PaymentAmount ====

[[Datei:PaymentAmount - CurrencyAmountType.jpg|363px|rahmenlos]]

'''''Just to record it again, all (payment) amount fields are always formed from a decimal value and the ISO currency'''''

==== PaymentServiceProvider ====

[[Datei:PaymentServiceProvider(Type).jpg|477px|rahmenlos]]

This more or less is self-explanatory.

Beside the name of the Payment/Financial Service Provider and the URL on a logo of the same also a description/explanation can be indicated herewith.

==== CashHolder ====

[[Datei:CashHolder(Type).jpg|588px|rahmenlos]]

The Cash Holder is the "owner" of the treated FOP. He/she is the person who is contacted if something went wrong with the corresponding payment, like exceeded credit limit with a credit card or a failed direct deposit.

The Cash Holder can be a person already involved in the booking, either as traveller and/or as booking owner or another independent person. For all cases we have the possiblity to inform on that person, while avoiding redundancies:

{| class="wikitable"
|-
| '''AssignedToBookingOwner'''|| As there is only one booking owner existing, it is sufficient to flag this by a boolean
|-
| '''AssignedToTraveller'''|| As there are one or more traveller in the booking existing, one must enter an according reference here
|-
| '''OwnerDetails'''|| To provide name, address and (media) contact details of that person.

''A more detailed description of '''CommonAddressType''' can be found #here#''
|}

=== Payment Response ===

As extension of the request we here have the following additional information

[[Datei:PaymentResponse(Type).jpg|rahmenlos|ohne]]

Here we describe only the newly added or changed elements in comparison to the request

We don't repeat the information here which is identical with the request part documented above.

==== Status ====
The following payment status we are dealing with.

{| class="wikitable sortable"
|-
! Status!! Explanation
|-
| '''''Open'''''|| This is the initial status when a payment (wish) by the Tour Operator (TO) has been announced respectively requested.

Normally the TO informs about the requested deposit and balance payments
|-
| '''''Recorded'''''|| This is the status, when the payment was entered in the travel agency, which only can be the case with agency debiting.

From customer point of view this is a relevant status, as the payment is done or at least triggered then; the regarding amount immediately appears as "paid"
|-
| '''''Settled'''''|| From TO view respectively its bookkeeping this is the most important status as it means that the TO received the money

|-
| '''''Failed'''''|| This means that a payment failed.

The Tour Operator or the Agency will have to clarify the according payment with the designated Cash Holder of the regarding payment
|-
| '''''Confirmed'''''|| ???
|}

The normal "status flow" will be
* In case of Agency debiting: '''''Open''''' => '''''Recorded''''' => '''''Settled'''''
* In case of Tour Operator debiting: '''''Open''''' => '''''Settled'''''

With retrieving a booking one can follow / monitor the payment status.

==== Dates ====

[[Datei:PaymentDates(Type).jpg|313px|rahmenlos]]

The Dates elemets are more or less self-explanatory.

{| class="wikitable"
|-
| '''DueDate'''|| The date on which the requested payment (e.g. deposit or balance) is expected by the Tour Operator
|-
| '''EntryDate'''|| The date on which the payment has been entered by the Travel Agency.

At that time the status of the payment status changes from "open" to "recorded"
|-
| '''SettlementDate'''|| The actual date of receipt of payment by the tour operator.

In case of Tour Operator debiting this is the time when payment status changes from "open" to "settled"
|}

==== PaymentDetails ====

[[Datei:PaymentDetails(Type).jpg|369px|rahmenlos]]

This complex is self explanatory. It should only be explicitly pointed out here that the fee amount is only the fee charged in connection with the chosen payment method.

== PaymentOptions ==

[[Datei:PaymentOption.JPG|677px|rahmenlos]]

With '''PaymentOptions''' the Tour Operator can inform on the supported PaymentOptions in case of a Tour Operator encashment. 
Indeed one '''PaymentOption''' is used per accepted '''FormOfPayment'''

''For agency debiting there must exist an agreement between TO and the agency which defines the payment processing, but this is out of scope here.''

In the following only the elements are explained which appears here for the first time.

== PaymentOverview ==

== Visualization / Examples ==
So we might follow the following workflow:

1. Pricing request / quote
This will display the expected payments with a status "open" which at least is the total payable amount of the booking. In that case the

2. Book
Within the request you can enter one or more payments
With the according response one will receive back the correspondign status from Tour Operator perspective

3. Retrieve / display the booking
Herewith you will receive back respectively the latest status of the (entered) payments at that time

Payment Handling

2018-07-05T15:26:07Z

Neudeckh: /* PaymentOptions */

== General information ==

The payment handling, provided by '''Payments''' elements, allows
* The user to enter payments
* The Tour Operator to inform on expected, desired and effected payments

Additionally there are further "functions" available to the Tour Operator / Organizer '''''and thus''''' within responses only:
* '''PaymentOptions''' to inform about the supported Form Of Payment (FOP) and possibly associated fees (surcharges) respectively
* '''PaymentOverview''' to present a payment summary at one glance.

[[Datei:PaymentHandling.jpg|475px|rahmenlos]]

So far this all is offered by two messages, the '''BookingRequest/Response''' and the dedicated payment message '''PaymentRequest/Response'''. For both - and possibly any other messages in the future - this is done the same identical way.
Therefore the following views are performed independently from the underlying message.

At first we focus on '''Payments''', followed by '''PaymentOptions''' and '''PaymentOverview'''

Finally we will present some xml examples.

== Payments ==

With a '''request''' one might enter '''one or more payments''' whereas the '''''responses''''' will inform you on '''''all existing payments''''' (payment positions) of the "booking" at that point in time, independent from the channel these have been entered.

In both - request and response - the underlying basic structure/complex of a concrete payment is from '''PaymentType''', with different characteristics respectively extensions for request and response; but the basic information is always the same.

So '''PaymentsRequestType/PaymentsResponseType''' inherits from '''PaymentType''' respectively.

Further '''Payments''' always signalizes that we are dealing with one or more payments while '''Payment''' elements are used for one concrete payment respectively.

[[Datei:PaymentsRequest-Response.jpg|690px|rahmenlos]]

In the following we will describe the used request and response structures more in detail. However, we only will show the information that is helpful for a general understanding in the treated context “payment handling”. The complete information on all available elements, attributes, values etc. can be taken from the [[XSD Documentation]].

Another chapter is dedicated to the different Form Of Payment (FOP)

We will start with the description of the '''@Collection''' attribute, which substantively is identical for request and response, with the only difference that it is mandatory for the response.

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Collection'''|| This is used to inform on

* The available encashment types supported/allowed by the Tour Operator for the treated operation / booking / agency and/or customer (response) - therefor it is mandatory here
* The encashment type chosen/desired by the user (request)

''Please notice, when entered here this is valid for all payments of the booking as a whole.''

{| class="wikitable sortable"

| '''''Agency'''''|| For agency debiting
|-
| '''''TourOperator'''''|| For Tour Operator debiting; i.e. the customer directely pays to the Tour Operator

|-
| '''''OnSite'''''|| In case the payment must be made on site, e.g. a sports course offered by the hotel

''Normally used for a concrete payment only''

|-
| '''''Mixed'''''|| Makes sense in the response only. The intention is that the Tour operator explicitly informs that agency and/or tour operator debiting will be allowed.
|}

|}

'''''If a Tour Operator likes to restrict the payments on a specific encashment type he can do it on Payments level; e.g.: To prohibit agency debiting at all he can provide "TourOperator" here, with the consequence that all payments must directly be handled between customer and Tour Operator.'''''

In all other cases the Tour Operator must use "Mixed". The user then can decide per payment which encashment to be used, i.e. it also allows the mix of encashment types.

=== Payment Request ===

[[Datei:PaymentRequest(Type).jpg|451px|rahmenlos|ohne]]

==== Available top-level attributes ====

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Identifier'''|| This is a unique identifier within one message, which can be used to reference on a concrete payment
|-
| '''@Collection'''|| Compare with explanations given above, please

''But notice, that here the attribute is attached to a concrete payment respectively''
|}

==== PaymentScope ====

This describes the purpose of the payment(s); it is an enumeration with the following values
{| class="wikitable sortable"
|-
! Value!! Explanation
|-
| '''''Balance'''''|| This is used to mark the total price to be paid to the organizer / Tour Operator, less any down payment.

Initially, this amount is specified together with a due date by the organizer / Tour Operator.
|-
| '''''Deposit'''''|| This is used to mark the down payment amount expected by the organizer / Tour Operator, which is initially specified by them together with a due date.
|-
| '''''Interim'''''|| This is used to mark an interim payment with an amount less than the remaining payment amount when the due date for the remaining payment has not yet been reached.

So this is also used for marking installments in the case of installment payments
|}

==== FormOfPayment ====
In the following the currently supported form of payments are listed which are mostly self-explanatory

{|
|-
|
* '''''CreditCard'''''
||
|-
|
* '''''DirectDebit'''''
||
|-
|
* '''''EBanking'''''
|| Account based FOP using the online banking account of an user, like Giropay and Sofortueberweisung
|-
|
* '''''EWallet'''''
|| Account based FOP, like PayPal and Paydirect
|-
|
* '''''Invoice'''''
||
|-
|
* '''''Installement'''''
||
|-
|
* '''''Voucher'''''
||
|}

A ''more detailed look on the supported FOPs can be found in chapter #here#''

==== PaymentAmount ====

[[Datei:PaymentAmount - CurrencyAmountType.jpg|363px|rahmenlos]]

'''''Just to record it again, all (payment) amount fields are always formed from a decimal value and the ISO currency'''''

==== PaymentServiceProvider ====

[[Datei:PaymentServiceProvider(Type).jpg|477px|rahmenlos]]

This more or less is self-explanatory.

Beside the name of the Payment/Financial Service Provider and the URL on a logo of the same also a description/explanation can be indicated herewith.

==== CashHolder ====

[[Datei:CashHolder(Type).jpg|588px|rahmenlos]]

The Cash Holder is the "owner" of the treated FOP. He/she is the person who is contacted if something went wrong with the corresponding payment, like exceeded credit limit with a credit card or a failed direct deposit.

The Cash Holder can be a person already involved in the booking, either as traveller and/or as booking owner or another independent person. For all cases we have the possiblity to inform on that person, while avoiding redundancies:

{| class="wikitable"
|-
| '''AssignedToBookingOwner'''|| As there is only one booking owner existing, it is sufficient to flag this by a boolean
|-
| '''AssignedToTraveller'''|| As there are one or more traveller in the booking existing, one must enter an according reference here
|-
| '''OwnerDetails'''|| To provide name, address and (media) contact details of that person.

''A more detailed description of '''CommonAddressType''' can be found #here#''
|}

=== Payment Response ===

As extension of the request we here have the following additional information

[[Datei:PaymentResponse(Type).jpg|rahmenlos|ohne]]

Here we describe only the newly added or changed elements in comparison to the request

We don't repeat the information here which is identical with the request part documented above.

==== Status ====
The following payment status we are dealing with.

{| class="wikitable sortable"
|-
! Status!! Explanation
|-
| '''''Open'''''|| This is the initial status when a payment (wish) by the Tour Operator (TO) has been announced respectively requested.

Normally the TO informs about the requested deposit and balance payments
|-
| '''''Recorded'''''|| This is the status, when the payment was entered in the travel agency, which only can be the case with agency debiting.

From customer point of view this is a relevant status, as the payment is done or at least triggered then; the regarding amount immediately appears as "paid"
|-
| '''''Settled'''''|| From TO view respectively its bookkeeping this is the most important status as it means that the TO received the money

|-
| '''''Failed'''''|| This means that a payment failed.

The Tour Operator or the Agency will have to clarify the according payment with the designated Cash Holder of the regarding payment
|-
| '''''Confirmed'''''|| ???
|}

The normal "status flow" will be
* In case of Agency debiting: '''''Open''''' => '''''Recorded''''' => '''''Settled'''''
* In case of Tour Operator debiting: '''''Open''''' => '''''Settled'''''

With retrieving a booking one can follow / monitor the payment status.

==== Dates ====

[[Datei:PaymentDates(Type).jpg|313px|rahmenlos]]

The Dates elemets are more or less self-explanatory.

{| class="wikitable"
|-
| '''DueDate'''|| The date on which the requested payment (e.g. deposit or balance) is expected by the Tour Operator
|-
| '''EntryDate'''|| The date on which the payment has been entered by the Travel Agency.

At that time the status of the payment status changes from "open" to "recorded"
|-
| '''SettlementDate'''|| The actual date of receipt of payment by the tour operator.

In case of Tour Operator debiting this is the time when payment status changes from "open" to "settled"
|}

==== PaymentDetails ====

[[Datei:PaymentDetails(Type).jpg|369px|rahmenlos]]

This complex is self explanatory. It should only be explicitly pointed out here that the fee amount is only the fee charged in connection with the chosen payment method.

== PaymentOptions ==

[[Datei:PaymentOption.JPG|677px|rahmenlos]]

== PaymentOverview ==

== Visualization / Examples ==
So we might follow the following workflow:

1. Pricing request / quote
This will display the expected payments with a status "open" which at least is the total payable amount of the booking. In that case the

2. Book
Within the request you can enter one or more payments
With the according response one will receive back the correspondign status from Tour Operator perspective

3. Retrieve / display the booking
Herewith you will receive back respectively the latest status of the (entered) payments at that time

Payment Handling

2018-07-05T15:24:47Z

Neudeckh: /* PaymentOptions */

== General information ==

The payment handling, provided by '''Payments''' elements, allows
* The user to enter payments
* The Tour Operator to inform on expected, desired and effected payments

Additionally there are further "functions" available to the Tour Operator / Organizer '''''and thus''''' within responses only:
* '''PaymentOptions''' to inform about the supported Form Of Payment (FOP) and possibly associated fees (surcharges) respectively
* '''PaymentOverview''' to present a payment summary at one glance.

[[Datei:PaymentHandling.jpg|475px|rahmenlos]]

So far this all is offered by two messages, the '''BookingRequest/Response''' and the dedicated payment message '''PaymentRequest/Response'''. For both - and possibly any other messages in the future - this is done the same identical way.
Therefore the following views are performed independently from the underlying message.

At first we focus on '''Payments''', followed by '''PaymentOptions''' and '''PaymentOverview'''

Finally we will present some xml examples.

== Payments ==

With a '''request''' one might enter '''one or more payments''' whereas the '''''responses''''' will inform you on '''''all existing payments''''' (payment positions) of the "booking" at that point in time, independent from the channel these have been entered.

In both - request and response - the underlying basic structure/complex of a concrete payment is from '''PaymentType''', with different characteristics respectively extensions for request and response; but the basic information is always the same.

So '''PaymentsRequestType/PaymentsResponseType''' inherits from '''PaymentType''' respectively.

Further '''Payments''' always signalizes that we are dealing with one or more payments while '''Payment''' elements are used for one concrete payment respectively.

[[Datei:PaymentsRequest-Response.jpg|690px|rahmenlos]]

In the following we will describe the used request and response structures more in detail. However, we only will show the information that is helpful for a general understanding in the treated context “payment handling”. The complete information on all available elements, attributes, values etc. can be taken from the [[XSD Documentation]].

Another chapter is dedicated to the different Form Of Payment (FOP)

We will start with the description of the '''@Collection''' attribute, which substantively is identical for request and response, with the only difference that it is mandatory for the response.

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Collection'''|| This is used to inform on

* The available encashment types supported/allowed by the Tour Operator for the treated operation / booking / agency and/or customer (response) - therefor it is mandatory here
* The encashment type chosen/desired by the user (request)

''Please notice, when entered here this is valid for all payments of the booking as a whole.''

{| class="wikitable sortable"

| '''''Agency'''''|| For agency debiting
|-
| '''''TourOperator'''''|| For Tour Operator debiting; i.e. the customer directely pays to the Tour Operator

|-
| '''''OnSite'''''|| In case the payment must be made on site, e.g. a sports course offered by the hotel

''Normally used for a concrete payment only''

|-
| '''''Mixed'''''|| Makes sense in the response only. The intention is that the Tour operator explicitly informs that agency and/or tour operator debiting will be allowed.
|}

|}

'''''If a Tour Operator likes to restrict the payments on a specific encashment type he can do it on Payments level; e.g.: To prohibit agency debiting at all he can provide "TourOperator" here, with the consequence that all payments must directly be handled between customer and Tour Operator.'''''

In all other cases the Tour Operator must use "Mixed". The user then can decide per payment which encashment to be used, i.e. it also allows the mix of encashment types.

=== Payment Request ===

[[Datei:PaymentRequest(Type).jpg|451px|rahmenlos|ohne]]

==== Available top-level attributes ====

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Identifier'''|| This is a unique identifier within one message, which can be used to reference on a concrete payment
|-
| '''@Collection'''|| Compare with explanations given above, please

''But notice, that here the attribute is attached to a concrete payment respectively''
|}

==== PaymentScope ====

This describes the purpose of the payment(s); it is an enumeration with the following values
{| class="wikitable sortable"
|-
! Value!! Explanation
|-
| '''''Balance'''''|| This is used to mark the total price to be paid to the organizer / Tour Operator, less any down payment.

Initially, this amount is specified together with a due date by the organizer / Tour Operator.
|-
| '''''Deposit'''''|| This is used to mark the down payment amount expected by the organizer / Tour Operator, which is initially specified by them together with a due date.
|-
| '''''Interim'''''|| This is used to mark an interim payment with an amount less than the remaining payment amount when the due date for the remaining payment has not yet been reached.

So this is also used for marking installments in the case of installment payments
|}

==== FormOfPayment ====
In the following the currently supported form of payments are listed which are mostly self-explanatory

{|
|-
|
* '''''CreditCard'''''
||
|-
|
* '''''DirectDebit'''''
||
|-
|
* '''''EBanking'''''
|| Account based FOP using the online banking account of an user, like Giropay and Sofortueberweisung
|-
|
* '''''EWallet'''''
|| Account based FOP, like PayPal and Paydirect
|-
|
* '''''Invoice'''''
||
|-
|
* '''''Installement'''''
||
|-
|
* '''''Voucher'''''
||
|}

A ''more detailed look on the supported FOPs can be found in chapter #here#''

==== PaymentAmount ====

[[Datei:PaymentAmount - CurrencyAmountType.jpg|363px|rahmenlos]]

'''''Just to record it again, all (payment) amount fields are always formed from a decimal value and the ISO currency'''''

==== PaymentServiceProvider ====

[[Datei:PaymentServiceProvider(Type).jpg|477px|rahmenlos]]

This more or less is self-explanatory.

Beside the name of the Payment/Financial Service Provider and the URL on a logo of the same also a description/explanation can be indicated herewith.

==== CashHolder ====

[[Datei:CashHolder(Type).jpg|588px|rahmenlos]]

The Cash Holder is the "owner" of the treated FOP. He/she is the person who is contacted if something went wrong with the corresponding payment, like exceeded credit limit with a credit card or a failed direct deposit.

The Cash Holder can be a person already involved in the booking, either as traveller and/or as booking owner or another independent person. For all cases we have the possiblity to inform on that person, while avoiding redundancies:

{| class="wikitable"
|-
| '''AssignedToBookingOwner'''|| As there is only one booking owner existing, it is sufficient to flag this by a boolean
|-
| '''AssignedToTraveller'''|| As there are one or more traveller in the booking existing, one must enter an according reference here
|-
| '''OwnerDetails'''|| To provide name, address and (media) contact details of that person.

''A more detailed description of '''CommonAddressType''' can be found #here#''
|}

=== Payment Response ===

As extension of the request we here have the following additional information

[[Datei:PaymentResponse(Type).jpg|rahmenlos|ohne]]

Here we describe only the newly added or changed elements in comparison to the request

We don't repeat the information here which is identical with the request part documented above.

==== Status ====
The following payment status we are dealing with.

{| class="wikitable sortable"
|-
! Status!! Explanation
|-
| '''''Open'''''|| This is the initial status when a payment (wish) by the Tour Operator (TO) has been announced respectively requested.

Normally the TO informs about the requested deposit and balance payments
|-
| '''''Recorded'''''|| This is the status, when the payment was entered in the travel agency, which only can be the case with agency debiting.

From customer point of view this is a relevant status, as the payment is done or at least triggered then; the regarding amount immediately appears as "paid"
|-
| '''''Settled'''''|| From TO view respectively its bookkeeping this is the most important status as it means that the TO received the money

|-
| '''''Failed'''''|| This means that a payment failed.

The Tour Operator or the Agency will have to clarify the according payment with the designated Cash Holder of the regarding payment
|-
| '''''Confirmed'''''|| ???
|}

The normal "status flow" will be
* In case of Agency debiting: '''''Open''''' => '''''Recorded''''' => '''''Settled'''''
* In case of Tour Operator debiting: '''''Open''''' => '''''Settled'''''

With retrieving a booking one can follow / monitor the payment status.

==== Dates ====

[[Datei:PaymentDates(Type).jpg|313px|rahmenlos]]

The Dates elemets are more or less self-explanatory.

{| class="wikitable"
|-
| '''DueDate'''|| The date on which the requested payment (e.g. deposit or balance) is expected by the Tour Operator
|-
| '''EntryDate'''|| The date on which the payment has been entered by the Travel Agency.

At that time the status of the payment status changes from "open" to "recorded"
|-
| '''SettlementDate'''|| The actual date of receipt of payment by the tour operator.

In case of Tour Operator debiting this is the time when payment status changes from "open" to "settled"
|}

==== PaymentDetails ====

[[Datei:PaymentDetails(Type).jpg|369px|rahmenlos]]

This complex is self explanatory. It should only be explicitly pointed out here that the fee amount is only the fee charged in connection with the chosen payment method.

== PaymentOptions ==

[[Datei:PaymentOption.JPG|rahmenlos]]

== PaymentOverview ==

== Visualization / Examples ==
So we might follow the following workflow:

1. Pricing request / quote
This will display the expected payments with a status "open" which at least is the total payable amount of the booking. In that case the

2. Book
Within the request you can enter one or more payments
With the according response one will receive back the correspondign status from Tour Operator perspective

3. Retrieve / display the booking
Herewith you will receive back respectively the latest status of the (entered) payments at that time

Datei:PaymentOption.JPG

2018-07-05T15:19:26Z

Neudeckh:

Payment Handling

2018-07-04T16:19:38Z

Neudeckh: /* Payment Response */

== General information ==

The payment handling, provided by '''Payments''' elements, allows
* The user to enter payments
* The Tour Operator to inform on expected, desired and effected payments

Additionally there are further "functions" available to the Tour Operator / Organizer '''''and thus''''' within responses only:
* '''PaymentOptions''' to inform about the supported Form Of Payment (FOP) and possibly associated fees (surcharges) respectively
* '''PaymentOverview''' to present a payment summary at one glance.

[[Datei:PaymentHandling.jpg|475px|rahmenlos]]

So far this all is offered by two messages, the '''BookingRequest/Response''' and the dedicated payment message '''PaymentRequest/Response'''. For both - and possibly any other messages in the future - this is done the same identical way.
Therefore the following views are performed independently from the underlying message.

At first we focus on '''Payments''', followed by '''PaymentOptions''' and '''PaymentOverview'''

Finally we will present some xml examples.

== Payments ==

With a '''request''' one might enter '''one or more payments''' whereas the '''''responses''''' will inform you on '''''all existing payments''''' (payment positions) of the "booking" at that point in time, independent from the channel these have been entered.

In both - request and response - the underlying basic structure/complex of a concrete payment is from '''PaymentType''', with different characteristics respectively extensions for request and response; but the basic information is always the same.

So '''PaymentsRequestType/PaymentsResponseType''' inherits from '''PaymentType''' respectively.

Further '''Payments''' always signalizes that we are dealing with one or more payments while '''Payment''' elements are used for one concrete payment respectively.

[[Datei:PaymentsRequest-Response.jpg|690px|rahmenlos]]

In the following we will describe the used request and response structures more in detail. However, we only will show the information that is helpful for a general understanding in the treated context “payment handling”. The complete information on all available elements, attributes, values etc. can be taken from the [[XSD Documentation]].

Another chapter is dedicated to the different Form Of Payment (FOP)

We will start with the description of the '''@Collection''' attribute, which substantively is identical for request and response, with the only difference that it is mandatory for the response.

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Collection'''|| This is used to inform on

* The available encashment types supported/allowed by the Tour Operator for the treated operation / booking / agency and/or customer (response) - therefor it is mandatory here
* The encashment type chosen/desired by the user (request)

''Please notice, when entered here this is valid for all payments of the booking as a whole.''

{| class="wikitable sortable"

| '''''Agency'''''|| For agency debiting
|-
| '''''TourOperator'''''|| For Tour Operator debiting; i.e. the customer directely pays to the Tour Operator

|-
| '''''OnSite'''''|| In case the payment must be made on site, e.g. a sports course offered by the hotel

''Normally used for a concrete payment only''

|-
| '''''Mixed'''''|| Makes sense in the response only. The intention is that the Tour operator explicitly informs that agency and/or tour operator debiting will be allowed.
|}

|}

'''''If a Tour Operator likes to restrict the payments on a specific encashment type he can do it on Payments level; e.g.: To prohibit agency debiting at all he can provide "TourOperator" here, with the consequence that all payments must directly be handled between customer and Tour Operator.'''''

In all other cases the Tour Operator must use "Mixed". The user then can decide per payment which encashment to be used, i.e. it also allows the mix of encashment types.

=== Payment Request ===

[[Datei:PaymentRequest(Type).jpg|451px|rahmenlos|ohne]]

==== Available top-level attributes ====

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Identifier'''|| This is a unique identifier within one message, which can be used to reference on a concrete payment
|-
| '''@Collection'''|| Compare with explanations given above, please

''But notice, that here the attribute is attached to a concrete payment respectively''
|}

==== PaymentScope ====

This describes the purpose of the payment(s); it is an enumeration with the following values
{| class="wikitable sortable"
|-
! Value!! Explanation
|-
| '''''Balance'''''|| This is used to mark the total price to be paid to the organizer / Tour Operator, less any down payment.

Initially, this amount is specified together with a due date by the organizer / Tour Operator.
|-
| '''''Deposit'''''|| This is used to mark the down payment amount expected by the organizer / Tour Operator, which is initially specified by them together with a due date.
|-
| '''''Interim'''''|| This is used to mark an interim payment with an amount less than the remaining payment amount when the due date for the remaining payment has not yet been reached.

So this is also used for marking installments in the case of installment payments
|}

==== FormOfPayment ====
In the following the currently supported form of payments are listed which are mostly self-explanatory

{|
|-
|
* '''''CreditCard'''''
||
|-
|
* '''''DirectDebit'''''
||
|-
|
* '''''EBanking'''''
|| Account based FOP using the online banking account of an user, like Giropay and Sofortueberweisung
|-
|
* '''''EWallet'''''
|| Account based FOP, like PayPal and Paydirect
|-
|
* '''''Invoice'''''
||
|-
|
* '''''Installement'''''
||
|-
|
* '''''Voucher'''''
||
|}

A ''more detailed look on the supported FOPs can be found in chapter #here#''

==== PaymentAmount ====

[[Datei:PaymentAmount - CurrencyAmountType.jpg|363px|rahmenlos]]

'''''Just to record it again, all (payment) amount fields are always formed from a decimal value and the ISO currency'''''

==== PaymentServiceProvider ====

[[Datei:PaymentServiceProvider(Type).jpg|477px|rahmenlos]]

This more or less is self-explanatory.

Beside the name of the Payment/Financial Service Provider and the URL on a logo of the same also a description/explanation can be indicated herewith.

==== CashHolder ====

[[Datei:CashHolder(Type).jpg|588px|rahmenlos]]

The Cash Holder is the "owner" of the treated FOP. He/she is the person who is contacted if something went wrong with the corresponding payment, like exceeded credit limit with a credit card or a failed direct deposit.

The Cash Holder can be a person already involved in the booking, either as traveller and/or as booking owner or another independent person. For all cases we have the possiblity to inform on that person, while avoiding redundancies:

{| class="wikitable"
|-
| '''AssignedToBookingOwner'''|| As there is only one booking owner existing, it is sufficient to flag this by a boolean
|-
| '''AssignedToTraveller'''|| As there are one or more traveller in the booking existing, one must enter an according reference here
|-
| '''OwnerDetails'''|| To provide name, address and (media) contact details of that person.

''A more detailed description of '''CommonAddressType''' can be found #here#''
|}

=== Payment Response ===

As extension of the request we here have the following additional information

[[Datei:PaymentResponse(Type).jpg|rahmenlos|ohne]]

Here we describe only the newly added or changed elements in comparison to the request

We don't repeat the information here which is identical with the request part documented above.

==== Status ====
The following payment status we are dealing with.

{| class="wikitable sortable"
|-
! Status!! Explanation
|-
| '''''Open'''''|| This is the initial status when a payment (wish) by the Tour Operator (TO) has been announced respectively requested.

Normally the TO informs about the requested deposit and balance payments
|-
| '''''Recorded'''''|| This is the status, when the payment was entered in the travel agency, which only can be the case with agency debiting.

From customer point of view this is a relevant status, as the payment is done or at least triggered then; the regarding amount immediately appears as "paid"
|-
| '''''Settled'''''|| From TO view respectively its bookkeeping this is the most important status as it means that the TO received the money

|-
| '''''Failed'''''|| This means that a payment failed.

The Tour Operator or the Agency will have to clarify the according payment with the designated Cash Holder of the regarding payment
|-
| '''''Confirmed'''''|| ???
|}

The normal "status flow" will be
* In case of Agency debiting: '''''Open''''' => '''''Recorded''''' => '''''Settled'''''
* In case of Tour Operator debiting: '''''Open''''' => '''''Settled'''''

With retrieving a booking one can follow / monitor the payment status.

==== Dates ====

[[Datei:PaymentDates(Type).jpg|313px|rahmenlos]]

The Dates elemets are more or less self-explanatory.

{| class="wikitable"
|-
| '''DueDate'''|| The date on which the requested payment (e.g. deposit or balance) is expected by the Tour Operator
|-
| '''EntryDate'''|| The date on which the payment has been entered by the Travel Agency.

At that time the status of the payment status changes from "open" to "recorded"
|-
| '''SettlementDate'''|| The actual date of receipt of payment by the tour operator.

In case of Tour Operator debiting this is the time when payment status changes from "open" to "settled"
|}

==== PaymentDetails ====

[[Datei:PaymentDetails(Type).jpg|369px|rahmenlos]]

This complex is self explanatory. It should only be explicitly pointed out here that the fee amount is only the fee charged in connection with the chosen payment method.

== PaymentOptions ==

== PaymentOverview ==

== Visualization / Examples ==
So we might follow the following workflow:

1. Pricing request / quote
This will display the expected payments with a status "open" which at least is the total payable amount of the booking. In that case the

2. Book
Within the request you can enter one or more payments
With the according response one will receive back the correspondign status from Tour Operator perspective

3. Retrieve / display the booking
Herewith you will receive back respectively the latest status of the (entered) payments at that time

Payment Handling

2018-07-04T16:18:44Z

Neudeckh: /* FormOfPayment */

== General information ==

The payment handling, provided by '''Payments''' elements, allows
* The user to enter payments
* The Tour Operator to inform on expected, desired and effected payments

Additionally there are further "functions" available to the Tour Operator / Organizer '''''and thus''''' within responses only:
* '''PaymentOptions''' to inform about the supported Form Of Payment (FOP) and possibly associated fees (surcharges) respectively
* '''PaymentOverview''' to present a payment summary at one glance.

[[Datei:PaymentHandling.jpg|475px|rahmenlos]]

So far this all is offered by two messages, the '''BookingRequest/Response''' and the dedicated payment message '''PaymentRequest/Response'''. For both - and possibly any other messages in the future - this is done the same identical way.
Therefore the following views are performed independently from the underlying message.

At first we focus on '''Payments''', followed by '''PaymentOptions''' and '''PaymentOverview'''

Finally we will present some xml examples.

== Payments ==

With a '''request''' one might enter '''one or more payments''' whereas the '''''responses''''' will inform you on '''''all existing payments''''' (payment positions) of the "booking" at that point in time, independent from the channel these have been entered.

In both - request and response - the underlying basic structure/complex of a concrete payment is from '''PaymentType''', with different characteristics respectively extensions for request and response; but the basic information is always the same.

So '''PaymentsRequestType/PaymentsResponseType''' inherits from '''PaymentType''' respectively.

Further '''Payments''' always signalizes that we are dealing with one or more payments while '''Payment''' elements are used for one concrete payment respectively.

[[Datei:PaymentsRequest-Response.jpg|690px|rahmenlos]]

In the following we will describe the used request and response structures more in detail. However, we only will show the information that is helpful for a general understanding in the treated context “payment handling”. The complete information on all available elements, attributes, values etc. can be taken from the [[XSD Documentation]].

Another chapter is dedicated to the different Form Of Payment (FOP)

We will start with the description of the '''@Collection''' attribute, which substantively is identical for request and response, with the only difference that it is mandatory for the response.

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Collection'''|| This is used to inform on

* The available encashment types supported/allowed by the Tour Operator for the treated operation / booking / agency and/or customer (response) - therefor it is mandatory here
* The encashment type chosen/desired by the user (request)

''Please notice, when entered here this is valid for all payments of the booking as a whole.''

{| class="wikitable sortable"

| '''''Agency'''''|| For agency debiting
|-
| '''''TourOperator'''''|| For Tour Operator debiting; i.e. the customer directely pays to the Tour Operator

|-
| '''''OnSite'''''|| In case the payment must be made on site, e.g. a sports course offered by the hotel

''Normally used for a concrete payment only''

|-
| '''''Mixed'''''|| Makes sense in the response only. The intention is that the Tour operator explicitly informs that agency and/or tour operator debiting will be allowed.
|}

|}

'''''If a Tour Operator likes to restrict the payments on a specific encashment type he can do it on Payments level; e.g.: To prohibit agency debiting at all he can provide "TourOperator" here, with the consequence that all payments must directly be handled between customer and Tour Operator.'''''

In all other cases the Tour Operator must use "Mixed". The user then can decide per payment which encashment to be used, i.e. it also allows the mix of encashment types.

=== Payment Request ===

[[Datei:PaymentRequest(Type).jpg|451px|rahmenlos|ohne]]

==== Available top-level attributes ====

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Identifier'''|| This is a unique identifier within one message, which can be used to reference on a concrete payment
|-
| '''@Collection'''|| Compare with explanations given above, please

''But notice, that here the attribute is attached to a concrete payment respectively''
|}

==== PaymentScope ====

This describes the purpose of the payment(s); it is an enumeration with the following values
{| class="wikitable sortable"
|-
! Value!! Explanation
|-
| '''''Balance'''''|| This is used to mark the total price to be paid to the organizer / Tour Operator, less any down payment.

Initially, this amount is specified together with a due date by the organizer / Tour Operator.
|-
| '''''Deposit'''''|| This is used to mark the down payment amount expected by the organizer / Tour Operator, which is initially specified by them together with a due date.
|-
| '''''Interim'''''|| This is used to mark an interim payment with an amount less than the remaining payment amount when the due date for the remaining payment has not yet been reached.

So this is also used for marking installments in the case of installment payments
|}

==== FormOfPayment ====
In the following the currently supported form of payments are listed which are mostly self-explanatory

{|
|-
|
* '''''CreditCard'''''
||
|-
|
* '''''DirectDebit'''''
||
|-
|
* '''''EBanking'''''
|| Account based FOP using the online banking account of an user, like Giropay and Sofortueberweisung
|-
|
* '''''EWallet'''''
|| Account based FOP, like PayPal and Paydirect
|-
|
* '''''Invoice'''''
||
|-
|
* '''''Installement'''''
||
|-
|
* '''''Voucher'''''
||
|}

A ''more detailed look on the supported FOPs can be found in chapter #here#''

==== PaymentAmount ====

[[Datei:PaymentAmount - CurrencyAmountType.jpg|363px|rahmenlos]]

'''''Just to record it again, all (payment) amount fields are always formed from a decimal value and the ISO currency'''''

==== PaymentServiceProvider ====

[[Datei:PaymentServiceProvider(Type).jpg|477px|rahmenlos]]

This more or less is self-explanatory.

Beside the name of the Payment/Financial Service Provider and the URL on a logo of the same also a description/explanation can be indicated herewith.

==== CashHolder ====

[[Datei:CashHolder(Type).jpg|588px|rahmenlos]]

The Cash Holder is the "owner" of the treated FOP. He/she is the person who is contacted if something went wrong with the corresponding payment, like exceeded credit limit with a credit card or a failed direct deposit.

The Cash Holder can be a person already involved in the booking, either as traveller and/or as booking owner or another independent person. For all cases we have the possiblity to inform on that person, while avoiding redundancies:

{| class="wikitable"
|-
| '''AssignedToBookingOwner'''|| As there is only one booking owner existing, it is sufficient to flag this by a boolean
|-
| '''AssignedToTraveller'''|| As there are one or more traveller in the booking existing, one must enter an according reference here
|-
| '''OwnerDetails'''|| To provide name, address and (media) contact details of that person.

''A more detailed description of '''CommonAddressType''' can be found #here#''
|}

=== Payment Response ===

As extension of the request we here have the following additional information

[[Datei:PaymentResponse(Type).jpg|rahmenlos|ohne]]

Here we describe only the newly added or changed elements in comparison to the request

We don't repeat the information here which is identical with the request part documented above.

==== Status ====
The following payment status we are dealing with.

{| class="wikitable sortable"
|-
! Status!! Explanation
|-
| '''''Open'''''|| This is the initial status when a payment (wish) by the Tour Operator (TO) has been announced respectively requested.

Normally the TO informs about the requested deposit and balance payments
|-
| '''''Recorded'''''|| This is the status, when the payment was entered in the travel agency, which only can be the case with agency debiting.

From customer point of view this is a relevant status, as the payment is done or at least triggered then; the regarding amount immediately appears as "paid"
|-
| '''''Settled'''''|| From TO view respectively its bookkeeping this is the most important status as it means that the TO received the money

|-
| '''''Failed'''''|| This means that a payment failed.

The Tour Operator or the Agency will have to clarify the according payment with the designated Cash Holder of the regarding payment
|-
| '''''Confirmed'''''|| ???
|}

The normal "status flow" will be
* In case of Agency debiting: '''''Open''''' => '''''Recorded''''' => '''''Settled'''''
* In case of Tour Operator debiting: '''''Open''''' => '''''Settled'''''

With retrieving a booking one can follow / monitor the payment status.

==== Dates ====

[[Datei:PaymentDates(Type).jpg|313px|rahmenlos]]

The Dates elemets are more or less self-explanatory.

{| class="wikitable"
|-
| '''DueDate'''|| The date on which the requested payment (e.g. deposit or balance) is expected by the Tour Operator
|-
| '''EntryDate'''|| The date on which the payment has been entered by the Travel Agency.

At that time the status of the payment status changes from "open" to "recorded"
|-
| '''SettlementDate'''|| The actual date of receipt of payment by the tour operator.

In case of Tour Operator debiting this is the time when payment status changes from "open" to "settled"
|}

==== PaymentDetails ====

[[Datei:PaymentDetails(Type).jpg|369px|rahmenlos]]

This complex is self explanatory. It should only be explicitly pointed out here that the fee amount is only the fee charged in connection with the chosen payment method.

== PaymentOptions ==

== PaymentOverview ==

== Visualization / Examples ==
So we might follow the following workflow:

1. Pricing request / quote
This will display the expected payments with a status "open" which at least is the total payable amount of the booking. In that case the

2. Book
Within the request you can enter one or more payments
With the according response one will receive back the correspondign status from Tour Operator perspective

3. Retrieve / display the booking
Herewith you will receive back respectively the latest status of the (entered) payments at that time

Payment Handling

2018-07-04T16:18:03Z

Neudeckh: /* PaymentDetails */

== General information ==

The payment handling, provided by '''Payments''' elements, allows
* The user to enter payments
* The Tour Operator to inform on expected, desired and effected payments

Additionally there are further "functions" available to the Tour Operator / Organizer '''''and thus''''' within responses only:
* '''PaymentOptions''' to inform about the supported Form Of Payment (FOP) and possibly associated fees (surcharges) respectively
* '''PaymentOverview''' to present a payment summary at one glance.

[[Datei:PaymentHandling.jpg|475px|rahmenlos]]

So far this all is offered by two messages, the '''BookingRequest/Response''' and the dedicated payment message '''PaymentRequest/Response'''. For both - and possibly any other messages in the future - this is done the same identical way.
Therefore the following views are performed independently from the underlying message.

At first we focus on '''Payments''', followed by '''PaymentOptions''' and '''PaymentOverview'''

Finally we will present some xml examples.

== Payments ==

With a '''request''' one might enter '''one or more payments''' whereas the '''''responses''''' will inform you on '''''all existing payments''''' (payment positions) of the "booking" at that point in time, independent from the channel these have been entered.

In both - request and response - the underlying basic structure/complex of a concrete payment is from '''PaymentType''', with different characteristics respectively extensions for request and response; but the basic information is always the same.

So '''PaymentsRequestType/PaymentsResponseType''' inherits from '''PaymentType''' respectively.

Further '''Payments''' always signalizes that we are dealing with one or more payments while '''Payment''' elements are used for one concrete payment respectively.

[[Datei:PaymentsRequest-Response.jpg|690px|rahmenlos]]

In the following we will describe the used request and response structures more in detail. However, we only will show the information that is helpful for a general understanding in the treated context “payment handling”. The complete information on all available elements, attributes, values etc. can be taken from the [[XSD Documentation]].

Another chapter is dedicated to the different Form Of Payment (FOP)

We will start with the description of the '''@Collection''' attribute, which substantively is identical for request and response, with the only difference that it is mandatory for the response.

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Collection'''|| This is used to inform on

* The available encashment types supported/allowed by the Tour Operator for the treated operation / booking / agency and/or customer (response) - therefor it is mandatory here
* The encashment type chosen/desired by the user (request)

''Please notice, when entered here this is valid for all payments of the booking as a whole.''

{| class="wikitable sortable"

| '''''Agency'''''|| For agency debiting
|-
| '''''TourOperator'''''|| For Tour Operator debiting; i.e. the customer directely pays to the Tour Operator

|-
| '''''OnSite'''''|| In case the payment must be made on site, e.g. a sports course offered by the hotel

''Normally used for a concrete payment only''

|-
| '''''Mixed'''''|| Makes sense in the response only. The intention is that the Tour operator explicitly informs that agency and/or tour operator debiting will be allowed.
|}

|}

'''''If a Tour Operator likes to restrict the payments on a specific encashment type he can do it on Payments level; e.g.: To prohibit agency debiting at all he can provide "TourOperator" here, with the consequence that all payments must directly be handled between customer and Tour Operator.'''''

In all other cases the Tour Operator must use "Mixed". The user then can decide per payment which encashment to be used, i.e. it also allows the mix of encashment types.

=== Payment Request ===

[[Datei:PaymentRequest(Type).jpg|451px|rahmenlos|ohne]]

==== Available top-level attributes ====

{| class="wikitable sortable"
|-
! Attribute!! Values / Explanation
|-
| '''@Identifier'''|| This is a unique identifier within one message, which can be used to reference on a concrete payment
|-
| '''@Collection'''|| Compare with explanations given above, please

''But notice, that here the attribute is attached to a concrete payment respectively''
|}

==== PaymentScope ====

This describes the purpose of the payment(s); it is an enumeration with the following values
{| class="wikitable sortable"
|-
! Value!! Explanation
|-
| '''''Balance'''''|| This is used to mark the total price to be paid to the organizer / Tour Operator, less any down payment.

Initially, this amount is specified together with a due date by the organizer / Tour Operator.
|-
| '''''Deposit'''''|| This is used to mark the down payment amount expected by the organizer / Tour Operator, which is initially specified by them together with a due date.
|-
| '''''Interim'''''|| This is used to mark an interim payment with an amount less than the remaining payment amount when the due date for the remaining payment has not yet been reached.

So this is also used for marking installments in the case of installment payments
|}

==== FormOfPayment ====
In the following the currently supported form of payments are listed which are mostly self-explanatory

{|
|-
|
* '''''CreditCard'''''
||
|-
|
* '''''DirectDebit'''''
||
|-
|
* '''''EBanking'''''
|| Account based FOP using the online banking account of an user, like Giropay and Sofortueberweisung
|-
|
* '''''EWallet'''''
|| Account based FOP, like PayPal and Paydirect
|-
|
* '''''Invoice'''''
||
|-
|
* '''''Installement'''''
||
|-
|
* '''''Voucher'''''
||
|}

A ''more detailed look at the supported FOPs can be found in chapter #here#''

==== PaymentAmount ====

[[Datei:PaymentAmount - CurrencyAmountType.jpg|363px|rahmenlos]]

'''''Just to record it again, all (payment) amount fields are always formed from a decimal value and the ISO currency'''''

==== PaymentServiceProvider ====

[[Datei:PaymentServiceProvider(Type).jpg|477px|rahmenlos]]

This more or less is self-explanatory.

Beside the name of the Payment/Financial Service Provider and the URL on a logo of the same also a description/explanation can be indicated herewith.

==== CashHolder ====

[[Datei:CashHolder(Type).jpg|588px|rahmenlos]]

The Cash Holder is the "owner" of the treated FOP. He/she is the person who is contacted if something went wrong with the corresponding payment, like exceeded credit limit with a credit card or a failed direct deposit.

The Cash Holder can be a person already involved in the booking, either as traveller and/or as booking owner or another independent person. For all cases we have the possiblity to inform on that person, while avoiding redundancies:

{| class="wikitable"
|-
| '''AssignedToBookingOwner'''|| As there is only one booking owner existing, it is sufficient to flag this by a boolean
|-
| '''AssignedToTraveller'''|| As there are one or more traveller in the booking existing, one must enter an according reference here
|-
| '''OwnerDetails'''|| To provide name, address and (media) contact details of that person.

''A more detailed description of '''CommonAddressType''' can be found #here#''
|}

=== Payment Response ===

As extension of the request we here have the following additional information

[[Datei:PaymentResponse(Type).jpg|rahmenlos|ohne]]

Here we describe only the newly added or changed elements in comparison to the request

We don't repeat the information here which is identical with the request part documented above.

==== Status ====
The following payment status we are dealing with.

{| class="wikitable sortable"
|-
! Status!! Explanation
|-
| '''''Open'''''|| This is the initial status when a payment (wish) by the Tour Operator (TO) has been announced respectively requested.

Normally the TO informs about the requested deposit and balance payments
|-
| '''''Recorded'''''|| This is the status, when the payment was entered in the travel agency, which only can be the case with agency debiting.

From customer point of view this is a relevant status, as the payment is done or at least triggered then; the regarding amount immediately appears as "paid"
|-
| '''''Settled'''''|| From TO view respectively its bookkeeping this is the most important status as it means that the TO received the money

|-
| '''''Failed'''''|| This means that a payment failed.

The Tour Operator or the Agency will have to clarify the according payment with the designated Cash Holder of the regarding payment
|-
| '''''Confirmed'''''|| ???
|}

The normal "status flow" will be
* In case of Agency debiting: '''''Open''''' => '''''Recorded''''' => '''''Settled'''''
* In case of Tour Operator debiting: '''''Open''''' => '''''Settled'''''

With retrieving a booking one can follow / monitor the payment status.

==== Dates ====

[[Datei:PaymentDates(Type).jpg|313px|rahmenlos]]

The Dates elemets are more or less self-explanatory.

{| class="wikitable"
|-
| '''DueDate'''|| The date on which the requested payment (e.g. deposit or balance) is expected by the Tour Operator
|-
| '''EntryDate'''|| The date on which the payment has been entered by the Travel Agency.

At that time the status of the payment status changes from "open" to "recorded"
|-
| '''SettlementDate'''|| The actual date of receipt of payment by the tour operator.

In case of Tour Operator debiting this is the time when payment status changes from "open" to "settled"
|}

==== PaymentDetails ====

[[Datei:PaymentDetails(Type).jpg|369px|rahmenlos]]

This complex is self explanatory. It should only be explicitly pointed out here that the fee amount is only the fee charged in connection with the chosen payment method.

== PaymentOptions ==

== PaymentOverview ==

== Visualization / Examples ==
So we might follow the following workflow:

1. Pricing request / quote
This will display the expected payments with a status "open" which at least is the total payable amount of the booking. In that case the

2. Book
Within the request you can enter one or more payments
With the according response one will receive back the correspondign status from Tour Operator perspective

3. Retrieve / display the booking
Herewith you will receive back respectively the latest status of the (entered) payments at that time