Payment process

Payment Setup – Optional

The payment setup step is optional, but it's advisable to implement it when you require assurance of secure payment initiation. Omitting the implementation of this step is possible when you don't need to identify individual payments in the system, but just need information that someone has paid you a certain amount. This is suitable for example when implementing donation contributions or topping up customer virtual account funds, when you only care about who topped up and how much, but don't need to distinguish individual top-ups or limit them to a minimum amount etc. The procedure is detailed in the Simple Integration - Without Payment Setup section.

For a traditional e-shop, where the buyer pays for specific goods, the payment setup step is important, and its omission is not recommended.

The e-shop initiates the payment with an HTTP request to the payment gateway server. Payment parameters, including a unique payment reference number, are passed as POST parameters of the HTTP protocol. This communication takes place between the client's server and the payment gateway server. The payer does not see this and cannot change the payment parameters. The payment gateway server returns to the client a unique transaction ID (identifier in the Comgate payment system) and a URL to which the payer should be redirected.

Example of Background Payment Setup – HTTP request using cURL

curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-0%Help&refId=2010102600&method=ALL&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/create

Example of Background Payment Setup – HTTP response:

HTTP/2 200 OK
content-type: application/x-www-form-urlencoded; charset=UTF-8
code=0&message=OK&transId=AB12-CD34-EF56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DAB12-CD34-EF56

The communication between the client's system and the payment gateway is secured using a password and IP whitelist (access is allowed only from the client's system IP addresses). It is essential to use the HTTPS protocol, which prevents the revelation of the password in case the communication is intercepted. The password is passed as a POST parameter (not a GET parameter) so that it does not get stored in the web server's communication log.

Redirect to the Payment Gateway

After setting up the payment in the background, the e-shop receives a payment URL to display the payment gateway. The payment gateway can be displayed in two ways. The first method is by redirecting the payer to the address received by the e-shop in the HTTP response. The redirect is usually performed by sending an HTTP 302 response:

HTTP response 302

HTTP/2 302 Found
Location: https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56

The second option is to display the payment gateway directly on the e-shop page using an iframe. For this option, you need to generate a payment URL in the standard way, but instead of redirecting the customer to the gateway, an iframe with the payment URL is displayed on the e-shop page.

Simple Integration – Without Payment Initiation

The payment gateway allows for skipping the first step of initiating payment in the background. In this case, the Payer is redirected to the payment gateway without prior payment initiation. The redirection can be done either by submitting a form using the POST method or a direct link using the GET method. We recommend the method of using a form.

Example of Simple Integration – Form Submission (POST)

<form method="POST" action="https://payments.comgate.cz/v1.0/create">

    <input type="hidden" name="merchant" value="XXXX" /> <!-- Identifier of the e-shop in the Comgate system -->

    <input type="hidden" name="price" value="100" /> <!-- 100 = 1.00 CZK -->

    <input type="hidden" name="curr" value="CZK" />

    <input type="hidden" name="label" value="My service" />

    <input type="hidden" name="refId" value="123456" />

    <input type="hidden" name="method" value="ALL" />

    <input type="hidden" name="country" value="CZ" />

    <button type="submit">Purchase</button>

</form>

Example of Simple Integration - Redirection Using Link (GET)

<a href="https://payments.comgate.cz/v1.0/create?merchant=XXXX&price=100&curr=CZK&label=My%20service&refId=10980891&method=ALL&country=CZ" rel="nofollow">Pay</a>

In the hyperlink parameters, keep the rel="nofollow" parameter.

Back-end Payment Result Transfer

Implementing this part ensures the automatic delivery of each payment transaction's status directly to your server as soon as the payment status is known. Background payment result delivery is mandatory. Its implementation and parameters are described in the Push Notifications section.

The payment result is delivered to the Client via an HTTP request from the payment gateway server to the Client's server. Identifiers and the payment result are provided as POST parameters of the HTTP protocol. This communication occurs in the background.

The Payer is redirected to the Client's website, and payment identifiers are passed as GET parameters of the HTTP protocol. The delivery of goods or services to the Payer must be tied to the background payment result delivery rather than to the final redirection of the Payer to the Client’s website, as information passed through redirection can be easily manipulated by the Payer.

Redirecting the Payer to the Client's website

Based on the payment status, the payer is redirected to one of three URLs that the e-shop selected when activating the service. Payment identifiers are passed as GET parameters of the HTTP protocol. The client's system must be able to handle two basic situations:

• When redirecting the Payer to the client's website, the payment result is not yet known. The payment is in PENDING status. This situation is absolutely normal and the e-shop should not present it as an error to the Payer. The system is waiting either for the payment to be credited to the bank account or for confirmation from the Payment Provider. The e-shop will find out the final result of the payment later, either by transmitting the payment result in the background, by email, or in the client portal.
• If the payment gateway learns the result of the payment immediately after the payment is made by the Payer, the Payer is directed to the appropriate URL (PAID or CANCELLED). If the e-shop has implemented the background payment result transmission, the redirection to the client's website will be carried out only after the successful transmission of the payment result in the background. It is not possible to send the goods or service ordered by the Payer based solely on the URL used for redirection, because the Payer could forge the payment result by changing the URL in the web browser.

Example of redirecting the Payer to the client's website - HTTP request

GET /result_ok.php?refId=2010102600&transId=AB12-EF34-IJ56 HTTP/2
Host: eshop.com