Technical description of a standard payment

A standard payment is the one used most often and is used for a one-off payment for a service or goods at the merchant's outlet.

The payment is created through the GoPay web service, which is located at:

https://gw.sandbox.gopay.com/axis/EPaymentServiceV2?wsdl in test mode, and at
https://gate.gopay.cz/axis/EPaymentServiceV2?wsdl for production mode.

Creating a standard payment is done by a call over SOAP, so you need to have a SOAP client installed on the server. The call is made using a method from the GoPay payment gateway API and takes as its parameter the payment order (paymentCommand), which is described in detail in the table.

Parameter name	Parameter description	Mandatory
successURL	Return URL called once the payment process has completed successfully. Format according to RFC 2396.	YES
failedURL	Return URL called once the payment has been cancelled. Format according to RFC 2396.	YES
productName	Description of the goods/service (max. 256 characters)	YES
targetGoId	Identification of the payee. A unique designation of the merchant outlet / GoPay user within GoPay. An integer identifier - defined during the integration of the merchant outlet.	YES
orderNumber	Identification of the order within the merchant outlet. An alphanumeric order designation (max. 128 characters).	YES
totalPrice	Price of the goods/service in hundredths. An integer expression of the price.	YES
currency	The currency in which the price for the goods/service is paid. The currency format follows the international currency standard ISO 4217.	YES
paymentChannels	A list of the payment methods displayed on the payment gateway. You can find the payment method codes here - CZK or EUR. The individual codes are separated by ",". This is an optional parameter; if it is not given, all the payment methods are displayed. Only payment methods that are activated for the given merchant outlet can be displayed.	NO
defaultPaymentChannel	A text string designating the pre-selected payment method; for the values it takes, see here - EUR and CZK.	NO
preAuthorization	To create a pre-authorized payment, set 1. It can take the value 0 (NO) or 1 (YES). To complete the payment (the goods are in stock) you need to call the GoPay payment completion service, see here.	NO
recurrencePayment	To create a recurring payment, set 1. It can take the value 0 (NO) or 1 (YES). The frequency of the repetition is described by the following parameters.	NO
recurrenceCycle	Takes the values [DAY, WEEK, MONTH], which set the basic time unit of the repetition. For repetition from ČS a.s. only the value DAY can be used.	YES - if recurrent
recurrencePeriod	Together with recurrenceCycle it defines the period of the recurring payment. For example, with the configuration DAY 5, the payment will be made every 5th day.	Payment=1
recurrenceDateTo	Defines the date until which the recurring payments will be made. It is a text string in the format yyyy-mm-dd.	Payment=1
encryptedSignature	Signature of the payment order. For assembling the string for the signature, see below.	YES
customerData.firstName	Customer's first name (max. 128 characters).	NO
customerData.lastName	Customer's surname (max. 128 characters).	NO
customerData.email	Customer's e-mail address (max. 128 characters).	YES
customerData.phoneNumber	Telephone contact for the customer.	NO
customerData.street	Customer's address - street (max. 256 characters).	NO
customerData.city	Customer's address - town (max. 128 characters).	NO
customerData.postalCode	Customer's address - postal code.	NO
customerData.countryCode	Customer's address - country code.	NO
p1 - p4	Optional parameter (max. 512 characters). The parameters are returned unchanged as part of the redirect back to the merchant outlet and of the notification about the change in the payment status.	NO
lang	Explicit setting of the language version of the payment gateway.	NO

String for the signature

The encrypted signature is assembled from the properties of the payment order. The signature is encrypted with a secret key designated as secureKey, which is passed as part of the integration.

String for assembling the signature

targetGoId+'|'+productName+'|'+totalPrice+'|'+currency+'|'+orderNumber+'|'+failedURL+'|'+successURL+'|'+preAuthorization+'|'+recurrentPayment+'|'+recurrenceDateTo+'|'+recurrenceCycle+'|'+recurrencePeriod+'|'+paymentChannels+'|'+secureKey

As a result of creating the payment, the Payment status (paymentStatus) is returned, which contains the parameters of the payment and the identification of the payment on GoPay's side (amount, name of the goods, variable symbol, paymentSessionId, and so on). You can find a detailed table describing the payment status below.

Parameter name	Parameter description	Mandatory
paymentSessionId	Identification of the payment in the GoPay system. An integer.	YES
parentPaymentSessionId	Identification of the parent payment. Used for recurring payments.	NO
targetGoId	Identification of the merchant outlet / GoPay user within GoPay. An integer identifier - defined during the integration of the merchant outlet.	YES
productName	Description of the goods/service passed when the payment was created.	YES
orderNumber	Identification of the order within the merchant outlet. An alphanumeric order designation, max. 128 characters.	YES
totalPrice	Price of the goods/service in hundredths. An integer expression of the price. Passed when the payment was created.	YES
currency	Determines the currency of the payment. The currency format follows ISO 4217.	YES
sessionState	Payment status	YES
sessionSubState	Supplementary payment status - the codes represent specific situations: 101 An online payment method has been selected for payment. 102 An offline payment method has been selected for payment. The customer has received an information e-mail with instructions for making the payment.	NO
sessionSubStateDesc	Text description of the supplementary information.	NO
result	CALL_COMPLETED - the WS call completed without error, CALL_FAILED - the WS call completed with an error (for example a non-matching signature).	YES
resultDescription	Description of the error situation in the case of CALL_FAILED.	NO
preAuthorization	Indicates whether the payment was created as a pre-authorized payment.	NO
recurrentPayment	Indicates whether the payment was created as a recurring payment.	NO
paymentChannel	Determines the payment method the customer selected to make the payment; for the values, see CZK and EUR.	YES
encryptedSignature	Signature of the payment order. For assembling the string for the signature, see below.	YES
p1 - p4	Optional parameter (max. 512 characters).	NO

String for the signature

The encrypted signature is assembled from the properties of the payment order. The signature is encrypted with a secret key designated as secureKey, which is passed as part of the integration.

String for assembling the signature

targetGoId+'|'+productName+'|'+totalPrice+'|'+currency+'|'+orderNumber+'|'+failedURL+'|'+successURL+'|'+preAuthorization+'|'+recurrentPayment+'|'+recurrenceDateTo+'|'+recurrenceCycle+'|'+recurrencePeriod+'|'+paymentChannels+'|'+secureKey

On the merchant outlet's side you need to create a relation between the order and the payment paymentSessionId.

You can find sample implementations of creating a payment enclosed in the example folder of the individual APIs.

Once the payment has been created, the customer has to be redirected to it. The URL of the payment gateway is used for that. This URL is:

for test mode - https://gw.sandbox.gopay.com/gw/pay-full-v2
for production mode - https://gate.gopay.cz/gw/pay-full-v2

The redirect contains the parameters paymentSession. The individual parameters (except for the paymentChannel parameter) carry the prefix sessionInfo.

Parameter name	Parameter description	Mandatory
paymentSessionId	Identification of the payment in the GoPay system. An integer.	YES
targetGoId	Identification of the merchant outlet / GoPay user within GoPay. An integer identifier - defined during the integration of the merchant outlet.	YES
encryptedSignature	Signature of the payment order. For assembling the string for the signature, see below	YES

String for the signature

The encrypted signature is assembled from the properties of the payment session. The signature is encrypted with a secret key designated as secureKey, which is passed as part of the integration of the e-shop.

String for assembling the signature

targetGoId+'|'+paymentSessionId+'|'+secureKey

The redirect may look like this, for example:

https://gate.gopay.cz/gw/pay-full-v2?sessionInfo.paymentSessionId=3803928540&sessionInfo.targetGoId=1803628540&sessionInfo.encryptedSignature=25ee53a1eccc253a8317bc9487174d09ba6b00a0f5267d2de6b483f58af9676d883e26600ce3316a

You can find sample implementations for assembling the redirect in the same source code as for creating the payment.

After the redirect the customer either makes the payment or does not, and is then redirected back to the merchant outlet, to the success or failed URL specified when the payment was created. Once redirected back to the merchant outlet, the merchant outlet makes a call for the payment status using the web service. This call is described in more detail in the article Description of the communication with the payment gateway.

When the payment status changes, a notification is delivered to the merchant outlet. Processing it is described in the article on Notifications.