GP webpay - Practical Examples

Transcription

1 GP webpay - Practical Examples Version: 2.0 Global Payments Europe, s.r.o. Created Last update

2 Author Dimitrij Holovka Manager Approved by Version 2.0 Confidentiality Internal Document history: Version Date Author Comments V. Keřka Original document: GP_webpay_Prakticke_scenare_072013_2.doc D. Holovka New template, versioning Fastpay Recurring payments PUSH payments Table of contents 1. Formula clause Introduction Purpose of this document practical examples Examples Example 1: Purchase of goods creating an order with authorization Example 2: Purchase of goods immediate request for transferring the amount from the card holder s account Example 3: Delivery of goods Transfer of the amount from the card holder s account to the merchant s account Example 4: Delivery of goods Incorrectly entered amount Example 5: Order cancellation Example 6: Card holder s complaints Example 7: Closing an order Example 8: Deleting an order Example 9: Pre-filled payment card data on the payment gateway Example 10: Recurring payments Registration of the master payment Processing of a subsequent payment Example 11: PUSH payments shortened payment link PUSH payment creation Payment made by the customer Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 2 / 16

3 1. Formula clause This document including any possible annexes and links is intended solely for the needs of an e- shop service provider (hereinafter referred to as Customer ). Information included in this document (hereinafter referred to as "Information") are subject to intellectual property and copyright protection of the Global Payments Europe, s.r.o. (hereinafter referred to as "GPE") and are of a commercially confidential nature in accordance with the provisions of the section 504 of the Act No. 89/2012 Coll., Civil Code. The Customer is aware of the legal obligations in relation to the handling of Information. Information or any part thereof may not be provided or in any way made available to third parties without the prior written consent of the GPE. At the same time, Information may not be used by the Customer for purposes other than for the purpose for which it serves. To avoid any doubts, without the prior written consent of the GPE, Information or any part thereof may be provided or in any way made available neither to companies providing payment processing services on the Internet. The GPE to the extent permitted by applicable law retains all rights to this document and Information contained therein. Any reproduction, use, exposure, or other publication, or dissemination of Information or its part by methods known and as yet undiscovered without the prior written consent of the GPE is strictly prohibited. The GPE is not in any way responsible for any errors or omissions in Information. GPE reserves the right, without giving any reason, to amend or repeal any Information. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 3 / 16

4 2. Introduction 2.1 Purpose of this document practical examples This document describes the most frequent cases of processing orders in the GP webpay system. It does not include any strict instructions as to how to process orders. The document is only for your information and presents some recommendations on how to process orders in the GP webpay system. The document was prepared based on practical experience of GP webpay users. 3. Examples 3.1 Example 1: Purchase of goods creating an order with authorization Creating an order with authorization i.e. blocking of the required amount on the card holder s bank account. This type of payment is used when physical products are purchased. As soon as GP webpay receives an order, it sends automatically a request to authorize this order - after successful authorization the amount is blocked on the card holder s bank account. When the goods are delivered, the merchant sends an online request to processdeposit(), or the merchant can use the instruction Payment / Deposit for the order via the administrative web interface of the GP webpay system. For details, see Delivery of goods. Procedure: 1) The card holder selects GP webpay as a method of payment on the merchant s web page; 2) The merchant redirects the card holder s Internet browser to GP webpay web pages. He/she sends a request to create an order (CREATE_ORDER) containing the DEPOSITFLAG parameter with value 0; 3) The card holder enters sensitive data on the GP webpay web pages; 4) As the data is entered and the request is confirmed, GP webpay verifies the payment with the Directory Server of the respective association (MasterCard, VISA, DC, AMEX) to find out whether 3D Secure authentication is required for the payment card used; 5) If 3D Secure authentication is required for the card holder, the card holder is redirected to the Access Control Server page of his/her bank where his/her identity is verified; 6) Depending on the result of the card holder s authentication, GP webpay continues/discontinues with the request for authorization of the order: Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 4 / 16

5 if the card holder has been successfully authenticated, a request for authorization ensues; if the card holder has not been successfully authenticated (incorrect filling of information requested for authentication of the cardholder), it is not possible to continue. The merchant is informed about unsuccessful authentication of the card holder by sending a response to URL address given in CREATE_ORDER with relevant parameters; if the card holder s bank or the card holder do not participate in 3D Secure, system continues in order authorization in the customer s bank. 7) Depending on the result of the authentication, an indicator is sent to the authorization centre describing the result of the card holder s authentication in 3D Secure. The indicator is one of the factors that the bank uses to either approve or decline the request for authorization. It is the responsibility of the particular banks to decide whether they accept or decline a 3D non-authenticated transaction in this step. If the bank declines the request for authorization because the card holder was not authenticated in the 3D Secure system, this information will be resent to the merchant who can display following information to the card holder: Your transaction was declined due to the impossibility of authentication of the card holder in 3D Secure. Ask your issuer bank to make this service available to you. 8) The merchant is notified about the result of authorization in the form of calling out the URL address given in CREATE_ORDER with relevant parameters that confirm success or indicate causes of failure; 9) The processing ends in this step, unless the card holder has stopped entering data in any of the previous steps. In this case, it cannot be guaranteed that the merchant s URL address is called out with the parameters describing the result. In this case, the result has to be verified by sending a request getorderstate() with the order number or by checking the order status in the GP administrative web interface; 10) If the request is successfully authorized but the merchant has not delivered or will not deliver the goods to the buyer, a request processauthorizationreverse() must be sent to unblock the amount on the card holder s bank account. If the merchant does not send the request processauthorizationreverse(), the amount will be blocked on the card holder s account for the period specified by the card holder s bank. It will be unblocked automatically upon expiry of this period; 11) When the URL address is called out, the merchant informs the card holder of the result; 12) Based on the previous procedure, an order (ORDER) is created in GP webpay. The Unique order identifier is the ORDERNUMBER field. The order may be in any of the following statuses: Requested The order has been initialized. It will remain in this status until the card holder enters sensitive data and ends the communication; Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 5 / 16

6 Pending The order is in this status after a request is sent to the 3D Directory Server of the respective financial association; Created The order is in this status after a positive response is received from the 3D Directory Server. Then the order is authorized; Declined The order is in this status if a negative response is received from the 3D Directory Server. The order authorization cannot continue; Approved The order is in this status if the authorization has been successful; Unapproved The order is in this status if the authorization has not been successful. 13) When the order status is verified by sending a getorderstate() request, it may take some time until a response is delivered due to the interaction between the 3D systems and the authorization centre. There are also some other factors that may cause a delay and that cannot be influenced, it is necessary to bear in mind: Entering sensitive data by the card holder on GP webpay web pages; Entering card holder s identification data on the 3D Secure Access Control Server; 14) Calling out of the merchant s URL address with the result of the CREATE_ORDER request is also delayed from the same reasons as those mentioned in para 13) above; 15) It is useless to send the getorderstate() request immediately after the card holder is redirected to GP webpay. It can be asserted for certain that after passing of 60 minutes since the card holder was redirected to GP webpay, the card holder has finished all the communication and the order status is final after this period. The same applies to the verification of the order status using the web graphical user interface. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 6 / 16

7 3.2 Example 2: Purchase of goods immediate request for transferring the amount from the card holder s account This type of transaction is used when products are purchased and delivered immediately distribution of files, insurance, registration, etc. The merchant sends a request to create a new order (CREATE_ORDER) with the DEPOSITFLAG parameter set to 1. Example 2 is quite similar to Example 1, except for Step 10. If the procedure does not end with the calling out of the merchant s URL address showing the result of the processing, there may have been an error caused by difficulties in the Internet communication. The order may have been processed correctly. With regard to the DEPOSITFLAG value, the authorization of the order has been followed by a request for clearing of the order. The order is in the Deposited_batch_open status and at the successive entering into accounts the request to transfer the amount from the card holder s account to the merchant s account will be sent. If the merchant has not received any message about the result and has not delivered the product, the order status has to be verified by sending the getorderstate()request. If the order is in the Deposited_batch_open status the processdepositreverse() request (for details, see Example 4) has to be sent to cancel the accounting for the order, followed by the processauthorizationreverse() request (for details, see Example 5) to unblock the amount on the card holder s account. If the batch containing the transaction has been closed (and accounted for) in the meantime, a processcredit() request (for details, see Example 6) can be sent to transfer the money back from the merchant s account to the card holder s account. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 7 / 16

8 3.3 Example 3: Delivery of goods Transfer of the amount from the card holder s account to the merchant s account This is the case when the customer has ordered goods from the merchant and the steps described in Example 1 have been successfully completed. The order is in the Approved status (Authorized). The merchant delivers desired goods to the customer and therefore sends a request to transfer the amount blocked in his/her favour on the customer s bank account to his/her account. Procedure: 1) The merchant sends a processdeposit() request to the GP webpay Web Services interface or chooses the instruction "Deposit" for the order via the administrative web interface; 2) A payment transaction is created for the order. The payment transaction is a part of the merchant s batch. The order status changes to Deposited_batch_open. At the end of the day, all open batches of all merchants are automatically closed; 3) Transactions contained in a batch are entered into accounts once in a day. All batches that are closed at the moment of creating the export file, but that have not been entered into accounts yet, are part of the data export, which is subsequently entered into accounts by the bank. The merchant cannot influence the time when transactions are entered into accounts (time, yes/no, etc.). This is an automatic procedure; 4) When the batch containing the order is closed, the order status changes to Deposited_batch_closed; 5) Closing the batch is the standard ending of most purchases. No other action is required from the merchant. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 8 / 16

9 3.4 Example 4: Delivery of goods Incorrectly entered amount If the merchant s administrator in charge of the GP webpay interface finds out that a payment (see Example 2) has been entered incorrectly either due to the selection of an incorrect order or due to entering an incorrect amount, he/she can correct the error. Procedure: 1) If the error is discovered before the batch is closed and the order has been created without a request for automatic amount transfer (DEPOSITFLAG with value set to 0),the order is still in the Deposited_batch_open status, a processdepositreverse() request can be sent or Deposit Reversal can be selected via the administrative web interface. The order status returns to Approved. Then a new processdeposit() request can be sent or the instruction Deposit" can be selected via the administrative web interface; 2) If the batch containing the order has already been closed or if it has been create with the final amount (DEPOSITFLAG with value set to 1), the order is in the Deposited_batch_closed status and the payment can no longer be reversed. If it is requested to return the amount to the card holder, a processcredit() request can be sent or the instruction Credit can be selected via the administrative web interface. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 9 / 16

10 3.5 Example 5: Order cancellation After the card holder purchased goods on the merchant s web pages (Example 1), he/she was authenticated successfully in the 3D systems and the result of the authorization was positive, the order is in the Approved status (Authorized). As long as the order is in this status, the customer may ask the merchant to cancel the order, or the merchant may decide not to deliver goods (e.g. goods will not be available for delivery in future). The merchant s administrator in charge of GP webpay sends the method processauthorizationreverse() to the GP webpay Web Services interface or selects the instruction Approve reversal for the respective order via the administrative web interface. The order status changes to Approve reversed", i.e. Authorization reversed. No further authorization is possible for this order. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 10 / 16

11 3.6 Example 6: Card holder s complaints The customer has made a successful complaint about a product or a service, and the merchant requests a transfer of the money in the original amount (or reduced amount) back to the card holder s account. With regard to the fact that the order has been paid already, the order reversal cannot be used. In this case, the merchant s administrator sends the method processcredit() to GP webpay Web Services interface or enters the instruction Credit" via the administrative web interface for the order, which is in the Deposited_batch_closed status. To enter the refund, the administrator enters the amount to be refunded. This amount must not exceed the amount originally paid. More than one refund can be created for one order. However, the sum of the refunds must not exceed the amount originally paid. If the refund has been entered incorrectly, the merchant s administrator can send the method processcreditreverse() to GP webpay Web Services interface or enters the instruction CREDIT_REVERSAL" via the administrative web interface. If at least one reversal exists for the order in an open batch, the order is in the Credited_batch_open status. If all reversals for the order are in closed batches the order is in the Credited_batch_closed status. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 11 / 16

12 3.7 Example 7: Closing an order If the merchant does not expect any more changes in the order and considers the order to be closed, the merchant s administrator can send the method processorderclose() to GP webpay Web Services interface or enters the instruction CLOSE_ORDER" or Closing of the order via the administrative web interface for the given order. The order status changes to Closed. The only operation allowed for a closed order is DELETE, i.e. deletion of the order. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 12 / 16

13 3.8 Example 8: Deleting an order If the order is in the Closed / Declined / Unapproved / Approve_reversed status and the merchant wants to delete it (that is, the order will no longer be displayed), the merchant s administrator can send the method processorderdelete() to GP webpay Web Services interface or enters the instruction Delete" or Remove via the administrative web interface for the given order. The order status changes to Deleted. The order will no longer be displayed but it will still be stored in the system for the purpose of accounting. Its unique ORDERNUMBER identifier cannot be used for another order. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 13 / 16

14 3.9 Example 9: Pre-filled payment card data on the payment gateway To improve the comfort of payment procedure for the customer, it is possible to display pre-filled data on the customer s payment card on the payment gateway. To pre-fill data if enabled for the merchant by his bank it is sufficient when creating a new order to fill the FASTPAYID field by a value of any previous successfully paid order. On the payment page there is displayed the card number replaced by asterisks, validity and text explaining security aspects. The customer is requested to enter only the CVV/CVC2 value. Then the order is processed in a standard way. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 14 / 16

15 3.10 Example 10: Recurring payments The GP webpay system enables to work with so-called recurring payments. The entire process is performed so that in the first place it is necessary to create the so-called registration ( master ) order via standard HTTP interface and later it is possible to create subsequent payments to this registration order via web services (WS) Registration of the master payment An order to be considered the registration one, it is necessary at its creation to fill and send USERPARAM1 parameter set to value R to the GP webpay interface. By this step, the order is considered to be registration one and is marked as the so-called master (sample/registration) order. Further processing runs in a standard way as in case of any other order. Registration order cannot be paid due to limitations by the Master Card association by a Maestro card. In this case, the payment gateway displays information about non-supported type of card and requests another payment card Processing of a subsequent payment The subsequent payment is processed via WS, because the card holder s presence is no more necessary. Before creation of a subsequent payment is enabled, the order is necessary to be successfully authorized and credited i.e. there has to be physical payment (from the GP webpay system point of view, the batch containing this payment has to be closed). Void of the registration payment can be made two ways: 1. void is made by the payment card issuer via special return code from the authorization process 2. automatically after a one-year inactivity i.e. there has been made no subsequent payment for the registration order for more than a year Subsequent/recurring payment is made via processrecurringpayment() WS method, where one of the input parameters is ORDERNUMBER of the master order. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 15 / 16

16 3.11 Example 11: PUSH payments shortened payment link PUSH payment enables the merchant to initiate card payments. The merchant can initiate individual payments via GP webpay application. GP webpay sets up an order for the requested payment and creates a short, repeatable link, which can be sent to the customer s . An advantage of creating orders this way is a possibility to integrate the payment link in , electronic invoice Payment link can be used for repeated opening of the payment gateway and it is possible to make up to 3 attempts to pay (payment data entering) PUSH payment creation To create a PUSH order is widely used the GP webpay graphical interface in the application menu, there is an item Create PUSH payment. After selecting this option, a form with requested payment data and as it is filled out, it is possible to send a notification to the customer, or the created link can be re-copied to their own or document. PUSH payment can be created also by means of the createpaymentlink() WS method. Method parameters are identical to the form in GUI. Return value is created by a link to the created order. The link is valid for max. 3 months and be shortened by setting up validity in GUI, or in the WS parameter. Once the link is created, it cannot be changed, it can only be made invalid in GUI (if no payment has been made via this link) Payment made by the customer The customer has received an in the wording approved by the merchant, or the link is a part of the electronic invoice. If he decides to use the received link for payment, as the link is clicked, he is - if the order is found and valid redirected to the GP webpay payment gateway. There the payment can be made. Payment is made in a fully standard way and the merchant is informed about a successful payment. if the order is not found or it cannot be made informed about impossibility to make a payment. Global Payments Europe, s.r.o., V Olšinách 80/626, Prague 10 Strašnice, Czech Republic 16 / 16