Payment handling examples

Overview

The examples on this page illustrate how payment is handled in the posps interface. They show several scenarios which can happen when shopping at the visavia.

The visavia system carries out the payment before it dispenses the articles in order to guarantee that the handed out articles are really paid for. However, if the articles cannot be dispensed for some reason, the visavia will cancel the payment and give the money back to the customer. Because the information if the payment is canceled or not is only available after the dispensing, the visavia calls the confirmSalePayment only after confirming the delivery, even though the actual payment is carried out earlier.

While the examples are given for sales, the payment handling for pickups is the same. See Examples for an explanation of the elements shown here.

Straightforward cash payment

The customer has chosen articles for a total of EUR30.00 and checks out.

  • The customer chooses to pay cash.
  • He inserts a EUR50.00 bill.
  • The visavia orders the articles, opens the output tray and calls confirmSaleDelivery.
  • The visavia pays out EUR20.00 change.
  • It confirms the payment by calling confirmSalePayment:

confirmSalePayment

Request

<sale:confirmSalePayment>
    <saleId code="example-1" />
    <payment xsi:type="pptype:PaymentCash">
        <!-- the customer has given EUR50.00 -->
        <given>5000</given>
        <!-- the visavia returned EUR20.00 change -->
        <returned>2000</returned>
    </payment>
    <!-- the payment has not been canceled (rolled back) -->
    <canceled>false</canceled>
</sale:confirmSalePayment>

Response

<sale:confirmSalePaymentResponse>
    <sale>
        <saleId code="example-1" />
        
        <position>
            <positionId code="position-1" />
            <positionData>
                <articleId code="1234567" />
                <name>Example Article</name>
                <packaging>
                    <size>1</size>
                    <unit>P</unit>
                </packaging>
                <amount>1</amount>
                <delivered>1</delivered>
                <articlePrice>3000</articlePrice>
                <positionPrice>3000</positionPrice>
                <vatRate>19</vatRate>
                <pharmaceutic />
            </positionData>
        </position>
        
        <total>
            <vat>
                <vatRate>19</vatRate>
                <price>479</price>
            </vat>
            <total>3000</total>
        </total>
        
        <!-- the server has added the following payment element as a
             result of the invocation of the operation -->
        <payment>
            <payment xsi:type="pptype:PaymentCash">
                <given>5000</given>
                <returned>2000</returned>
            </payment>
        </payment>
        
    </sale>
</sale:confirmSalePaymentResponse>

Payment for a total of 0

It often happens that a the customer doesn't have to pay anything. For a sale this can for example be the case if the customer hands in a prescription which is exempt from co-payment. For a pickup, the customer might already have paid in advance. In these cases, the server sends a total amount of 0. The client nevertheless calls confirmSalePayment with the special type PaymentNone.

confirmSalePayment

Request

<sale:confirmSalePayment>
    <saleId code="example-2" />
    <payment xsi:type="pptype:PaymentNone" />
    <!-- the payment has not been canceled (rolled back) -->
    <canceled>false</canceled>
</sale:confirmSalePayment>

Response

        <sale:confirmSalePaymentResponse>
            <sale>
                <saleId code="example-2" />
                
                <position>
                    <positionId code="position-1" />
                    <positionData>
                        <articleId code="1234567" />
                        <!-- the position is dispensed for a prescription which
                             is exempt from co-payment -->
                        <prescriptionId code="prescription-1" />
                        <name>Example Article</name>
                        <packaging>
                            <size>1</size>
                            <unit>P</unit>
                        </packaging>
                        <amount>1</amount>
                        <delivered>1</delivered>
                        <articlePrice>0</articlePrice>
                        <positionPrice>0</positionPrice>
                        <vatRate>0</vatRate>
                        <pharmaceutic />
                    </positionData>
                </position>
                
                <prescription>
                    <prescriptionId code="prescription-1" />
                    <prescriptionData>
                        <countrySpecific xsi:type="pptype:PrescriptionDE">
                            <rezeptart>gkv</rezeptart>
                            <!-- this prescription is exempt from co-payment -->
                            <gebuehrenfrei>true</gebuehrenfrei>
                            <kinderrezept>true</kinderrezept>
                            <noctu>false</noctu>
                        </countrySpecific>
                    </prescriptionData>
                </prescription>

                <!-- the customer doesn't have to pay anything -->
                <total>
                    <total>0</total>
                </total>

                <!-- the server has added the following payment element as a
                     result of the invocation of the operation -->
                <payment>
                    <payment xsi:type="pptype:PaymentNone"/>
                </payment>
            </sale>
        </sale:confirmSalePaymentResponse>

Canceled payment after a failed delivery

Not surprisingly, the visavia collects the money from the customer before it dispenses the articles. If the delivery fails, for example due to a hardware error, the visavia will pay the money back in case of a cash payment or rollback the card payment transaction. It informs the server of the canceled payment by a confirmSalePayment call with the canceled parameter set to true. If the visavia can't recover from the error it will close the sale next. Since no payment has happened and no articles have been delivered, this sale counts as aborted.

Canceled card payment

confirmSalePayment

Request

<sale:confirmSalePayment>
    <saleId code="example-3a" />
    <payment xsi:type="pptype:PaymentCard">
        <type>Maestro</type>
    </payment>
    <!-- the payment has been canceled (rolled back) -->
    <canceled>true</canceled>
</sale:confirmSalePayment>

Response

<sale:confirmSalePaymentResponse>
    <sale>
        <saleId code="example-3a" />
        
        <position>
            <positionId code="position-1" />
            <positionData>
                <articleId code="1234567" />
                <name>Example Article</name>
                <packaging>
                    <size>1</size>
                    <unit>P</unit>
                </packaging>
                <amount>1</amount>
                <!-- the delivery has failed -->
                <delivered>0</delivered>
                <articlePrice>3000</articlePrice>
                <positionPrice>3000</positionPrice>
                <vatRate>19</vatRate>
                <pharmaceutic />
            </positionData>
        </position>
        
        <total>
            <vat>
                <vatRate>19</vatRate>
                <price>479</price>
            </vat>
            <total>3000</total>
        </total>
        
        <!-- the server has added the following payment element as a
             result of the invocation of the operation -->
        <payment>
            <payment xsi:type="pptype:PaymentCard">
                <type>Maestro</type>
            </payment>
            <!-- this payment has been canceled -->
            <canceled />
        </payment>
    </sale>
</sale:confirmSalePaymentResponse>

Canceled cash payment

This example assumes that the customer has paid with a EUR50.00 bill. Since the payment is canceled, the visavia pays back the complete amount.

confirmSalePayment

Request

<sale:confirmSalePayment>
    <saleId code="example-3b" />
    <payment xsi:type="pptype:PaymentCash">
        <given>5000</given><!-- EUR50.00 -->
        <returned>5000</returned><!-- returned the full amount -->
    </payment>
    <!-- the payment has been canceled (rolled back) -->
    <canceled>true</canceled>
</sale:confirmSalePayment>

Response

<sale:confirmSalePaymentResponse>
    <sale>
        <saleId code="example-3b" />
        
        <position>
            <positionId code="position-1" />
            <positionData>
                <articleId code="1234567" />
                <name>Example Article</name>
                <packaging>
                    <size>1</size>
                    <unit>P</unit>
                </packaging>
                <amount>1</amount>
                <!-- the delivery has failed -->
                <delivered>0</delivered>
                <articlePrice>3000</articlePrice>
                <positionPrice>3000</positionPrice>
                <vatRate>19</vatRate>
                <pharmaceutic />
            </positionData>
        </position>
        
        <total>
            <vat>
                <vatRate>19</vatRate>
                <price>479</price>
            </vat>
            <total>3000</total>
        </total>
        
        <!-- the server has added the following payment element as a
             result of the invocation of the operation -->
        <payment>
            <payment xsi:type="pptype:PaymentCash">
                <given>5000</given><!-- EUR50.00 -->
                <returned>5000</returned><!-- returned the full amount -->
            </payment>
            <!-- this payment has been canceled -->
            <canceled />
        </payment>
    </sale>
</sale:confirmSalePaymentResponse>

Change of payment type/Credit

The visavia system allows the customer to cancel an ongoing payment, perhaps because the customer wants to change the payment method. In this example, the customer starts with cash payment and then switches to card payment because he doesn't have enough cash.

This example also demonstrates the credit element. If the customer cancels a cash payment, the visavia doesn't pay back the bills which the customer has entered but money from its cash dispensers. If there is not enough cash left in the dispensers, the visavia can't pay back the complete amount. In this case it uses the credit element to give this information to the PS and prints out a receipt to the customer for the remaining money. (The pharmacist can look up this information on the visavia itself, so the PS doesn't have to offer any additional functionality to handle these cases).

The customer has chosen articles for a total of EUR30.00 and checks out.

  • The customer chooses to pay cash.
  • He inserts a EUR20.00 bill.
  • After discovering that he doesn't have enough money left, he cancels the payment.
  • The visavia tries to pay back the inserted EUR20.00, but only has EUR15.00 change left. It prints a receipt for the remaining money.
  • The visavia informs the PS by invoking confirmSalePayment.

cofirmSalePayment

Request

<sale:confirmSalePayment>
    <saleId code="example-4" />
    <payment xsi:type="pptype:PaymentCash">
        <given>2000</given><!-- EUR20.00 -->
        <!-- the visavia only had EUR15.00 change -->
        <returned>1500</returned>
        <!-- the visavia owes the customer EUR5.00 -->
        <credit>
            <amount>500</amount>
            <reason>Not enough change.</reason>
        </credit>
    </payment>
    <!-- the payment has been canceled (rolled back) -->
    <canceled>true</canceled>
</sale:confirmSalePayment>

Response

<sale:confirmSalePaymentResponse>
    <sale>
        <saleId code="example-4" />
        
        <position>
            <positionId code="position-1" />
            <positionData>
                <articleId code="1234567" />
                <name>Example Article</name>
                <packaging>
                    <size>1</size>
                    <unit>P</unit>
                </packaging>
                <amount>1</amount>
                <!-- the delivery has failed -->
                <delivered>0</delivered>
                <articlePrice>3000</articlePrice>
                <positionPrice>3000</positionPrice>
                <vatRate>19</vatRate>
                <pharmaceutic />
            </positionData>
        </position>
        
        <total>
            <vat>
                <vatRate>19</vatRate>
                <price>479</price>
            </vat>
            <total>3000</total>
        </total>
        
        <!-- the server has added the following payment element as a
            result of the invocation of the operation -->
        <payment>
            <payment xsi:type="pptype:PaymentCash">
                <given>2000</given>
                <returned>1500</returned>
                <credit>
                    <amount>500</amount>
                    <reason>Not enough change.</reason>
                </credit>
            </payment>
            <!-- this payment has been canceled -->
            <canceled />
        </payment>
    </sale>
</sale:confirmSalePaymentResponse>
  • The customer still wants his article, so he chooses card payment.
  • After the card payment succeeds, the visavia orders the article and delivers it.
  • The visavia confirms the card payment.

confirmSalePayment

Request

<sale:confirmSalePayment>
    <saleId code="example-4" />
    <payment xsi:type="pptype:PaymentCard">
        <type>Maestro</type>
    </payment>
    <!-- the payment has not been canceled -->
    <canceled>false</canceled>
</sale:confirmSalePayment>

Response

        <sale:confirmSalePaymentResponse>
            <sale>
                <saleId code="example-4" />
                
                <position>
                    <positionId code="position-1" />
                    <positionData>
                        <articleId code="1234567" />
                        <name>Example Article</name>
                        <packaging>
                            <size>1</size>
                            <unit>P</unit>
                        </packaging>
                        <amount>1</amount>
                        <!-- the delivery has failed -->
                        <delivered>0</delivered>
                        <articlePrice>3000</articlePrice>
                        <positionPrice>3000</positionPrice>
                        <vatRate>19</vatRate>
                        <pharmaceutic />
                    </positionData>
                </position>
                
                <total>
                    <vat>
                        <vatRate>19</vatRate>
                        <price>479</price>
                    </vat>
                    <total>3000</total>
                </total>

                <!-- the payment element from the previous call is retained -->
                <payment>
                    <payment xsi:type="pptype:PaymentCash">
                        <given>2000</given>
                        <returned>1500</returned>
                        <credit>
                            <amount>500</amount>
                            <reason>Not enough change.</reason>
                        </credit>
                    </payment>
                    <!-- this payment has been canceled -->
                    <canceled />
                </payment>

                <!-- this payment element is added as a result of the current
                    operation -->
                <payment>
                    <payment xsi:type="pptype:PaymentCard">
                        <type>Maestro</type>
                    </payment>
                </payment>
            </sale>
        </sale:confirmSalePaymentResponse>

The sale process is now completed and the visavia closes it.