GoPay technical documentation
This documentation describes the integration of the GoPay payment gateway using the REST API. It is targeted at developers. If you’re looking for GoPay plugins for e-commerce platforms, kindly refer to this article.
The documentation contains two parts - integration guide and API reference. You can also use one of our SDKs:
PHP
- PHP >= 8.1
- GitHub: https://github.com/gopaycommunity/gopay-php-api
- Packagist: https://packagist.org/packages/gopay/payments-sdk-php
- Instalation:
composer require gopay/payments-sdk-php
Python
- Python >= 3.6
- GitHub: https://github.com/gopaycommunity/gopay-python-api
- PyPi: https://pypi.org/project/gopay/
- Instalation:
pip install gopay
.NET (C#)
- .NET Standard >= 2.0
- GitHub: https://github.com/gopaycommunity/gopay-dotnet-api
- NuGet: https://www.nuget.org/packages/GoPay.NET
- Instalation:
dotnet add package GoPay.NET
Java
- Java >= 11
- GitHub: https://github.com/gopaycommunity/gopay-java-api.git
- Maven: https://mvnrepository.com/artifact/cz.gopay
- Instalace:
git clone https://github.com/gopaycommunity/gopay-java-api.git
cd gopay-java-api
mvn package
API Endpoints
Sandbox enviroment - https://gw.sandbox.gopay.com/api
Production enviroment - https://gate.gopay.cz/apiThe API uses the OAuth2.0 authentication protocol using a Bearer token. The token has two scopes. Token with payment-create scope can only be used to create payments, while token payment-all scope can be used for all API operations.
Specification of the API call for obtaining tokens and examples for specific SDKs can be found in Obtaining the access token.
In order to get an access token you need to have obtained the GoPay Client ID and Client Secret. These credentials are used in the API call to get an access token. This endpoint uses the HTTP Basic authentication, see RFC 7617. The credentials in the form <ClientId>:<ClientSecret> are encoded with base64 and sent in the Authorization header, e.g.:
Authorization: Basic PENsaWVudElkPjo8Q2xpZW50U2VjcmV0Pg==
All other endpoints employ HTTP Bearer authentication with the access token. This token, which expires after 30 minutes, can be used multiple times within its validity period. It should be included in the Authorization header, as shown below:
Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
This section describes the creation and lifecycle of a payment, opening of the payment gateway, payment expiration and payment states.
Individual steps
- Obtaing the API access token
- Using the access token and order data to create a payment
- Opening of the payment gateway using the payment’s
gw_url - Using the ID of the payment to check its state after the customer gets redirected back to the website
- Checking the state of the payment after receiving the HTTP async notification
The first step is obtaining an access token using the API calls. Some SDKs get the token automatically in the background.
The next step is actually creating a payment. The order and customer data are sent in the body of the payment creation API call. This includes the return_url and notification_url which are used to redirect the customer back to your website and to deliver you the HTTP notification respectively. The API call can also be used to limit or specify the available payment methods.
The reponse is a JSON with the payment information, the most important being:
- Payment ID - the unique identifier of the payment. It is used mainly to get the details of the payment and react to status changes
- Payment gateway URL - in the
gw_urlparameter, used for redirecting the customer to the gateway or initiating the inline gateway
Aside from that it contains other details about the payment. See Payments for more info.
Using the gw_url of the payment, the gateway can be initiated in one of 3 versions:
- Redirect The customer is redirected to the
gw_url(using a HTTP redirect, HTML form, etc.). The customer leaves the merchant website and is redirected to the secured environment of the payment gateway ongate.gopay.cz. - Inline In order to inititate the inline gateway, it is required to implement it via JavaScript on the merchant website. The website needs to be secured with HTTPS. The payment gateway opens as an overlay over the website. If at any point a redirect is made (3DS, online banking etc), the customer is then returned to the Redirect variant.
- Mobile version. On mobile devices, the mobile version of the redirect gateway is always invoked, even if you have the inline version implemented in your website. The mobile gateway is optimized for display and control on mobile devices.
Detailed information about the variant and instructions on implementing them can be found in Payment gateway inititation
After initiating the payment gateway, the customer chooses a payment method. Available payment methods can be specified when creating the payment. The customer can see either a list of available payment methods, or can be redirected directly to a specific payment method, see Setting the payment methods.
After the customer tries to make a payment by clicking the confirmation button, the payment state changes to PAYMENT_METHOD_CHOSEN. If the customer sees the payment method details (like the card input form) but has not clicked on the confirmation button, the payment method is not chosen yet.
When a payment method is chosen, the payment authorization process starts. This process is different for each payment method. It can lead into one of the following situations:
- Payment is authorized. The authorization was successful and merchant’s business account balance is increased by the payment amount. The payment state is
PAID(orAUTHORIZEDif a preauthorized payment was used). - Payment is declined. At some point during the authorization the payment was declined by a partner (e.g. customer’s bank, 3DS centre etc.). The payment state is
CANCELED - The payment is pending. We don’t have the result of the authorization yet. This can even be the case when the customer has already returned back to merchant’s website. As soon as we know the payment result, a notification for the payment will be sent.
If the payment is in any of these states, the payment method cannot be changed anymore.
Customer is redirected to merchant’s website automatically after finishing a payment. They can also manually close the payment gateway and be redirected to merchant’s website. The URL they’re redirected to was specified by the merchant when creating the payment. One to two query parameters are appended to the URL:
id- the ID of the payment is sent in this parameter. It can be used to access the state of the paymentparent_id- only if the payment is recurring. It contains the ID of the initating payment.
The website then uses these parameters to inquire the status of the payment and informs the customer about the result.
When the status of the payment changes, a HTTP notification is sent. The URL was passed by the merchant when creating the payment. One to two query parameters are appended to the URL:
id- the ID of the payment is sent in this parameter. It can be used to access the state of the paymentparent_id- only if the payment is recurring. It contains the ID of the initating payment.
A HTTP GET request is sent to this URL. Only when the state of the payment changes from CREATED to PAYMENT_METHOD_CHOSEN the notification is not sent. The notification only carries the ID of the payment, no additional info. The merchant’s website then needs to do a payment status inquiry to get the actual details. The state of the payment can change multiple times (e.g. when a payment gets refunded, it changes from PAID to REFUNDED).
The payment can be in one of these states:
CREATED- payment createdPAYMENT_METHOD_CHOSEN- awaiting the result of the paymentTIMEOUTED- the payment is expiredPAID- the payment was paidCANCELED- the payment was declinedAUTHORIZED- a preauthorized payment was authorizedPARTIALLY_REFUNDED- a part of the payment amount was refundedREFUNDED- the entire payment amount was refunded
During the payment there are two expirations:
- Expiration 1 - starts when the payment is created and lasts until the payment method is chosen (or the payment expires) - always the same for all payments
- Expiration 2 - starts when the payment method is chosen and last until the result of the payment is known (or the payment expires) - can differ for each payment method
The standard payment is a one-time payment, that can be paid using any payment method. Its lifecycle is described in Lifecycle of a payment.
In order to create a standard payment, use the corresponding API call. Only the required body parameters are needed. A customer interaction is always required.
Most other types of payments use the same API call with some additional parameters.
The payment types can be combined. For example, a payment can be both preauthorized and recurring.
More detailed examples can be found in the API reference for payment creation
Minimal payment creation
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}Using the recurring payment you can charge the customer’s card automatically without interaction, the customer needs to authorize the payment only once. There are two kinds of recurring payments:
AUTO- the customer is charged automatically in specified intervals. The payment amount or other payment parameters cannot be changedON_DEMAND- customer can be charged using an API call. You can modify the amount and other payment parameters with each charge.
In the process there are two types of payments:
- Initital payment (or “parent”) - is the same as a standard payment. The customer needs to interact with the payment gateway and authorize the payment.
- Subsequent charges (or “child”) - are either created automatically or usign an API call. A reference to the initial payment is passed. Are done in the background without customer interaction.
Recurring payments are available in the sandbox. In order to use them on production, please contact our Customer Support and specify, what kind of recurring payments you would like to use. Please refer to What information do I need to put on my website in terms with recurring payments? and make sure your website follows all the conditions.
If you do not wish to have the founding recurring payment withdraw from account, create it as a preauthorized payment and do not void or capture the preauthorized payment after payment. After 4 days, the funds will be automatically released and subsequent payments can begin to be made within the active recurrence.
In order to create an automatically recurring payment, use the payment creation API call. In the request body, send the recurrence object. The following parameters need to be sent:
recurrence_cyclesets the cycle, meaning that the charge will be carried out each Nth day, week or month. The possible values are specified in Recurrence cyclerecurrence_periodsets the period (not frequency) of the recurrence, meaning how many days, weeks or months are there between two consequent chargesrecurrence_date_tosets the expiration of the recurring payment. The customer will be automatically charged until this date. The date needs to be in the future and it needs to be further than the last day the customer is going to be charged.
The object sets the recurrence period and not the frequency. For example:
{
"recurrence_cycle": "MONTH",
"recurrence_period": 2,
"recurrence_date_to": "2025-12-31"
}
Using this object, the customer will be charged every 2 months and not twice a month.
If you need to charge the customer yearly, set the
recurrence_cycletoMONTHand therecurrence_periodto12. The customer will be charged each 12 months, so yearly
The subsequent charges have the same amount and other parameters as the initial payment. If a payment is declined, the next attempt will be the following payment.
See Payment creation for the description of the API call and recurrence for the description of the mandatory object.
Creation of an AUTO recurring payment
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"recurrence": {
"recurrence_cycle": "DAY",
"recurrence_period": 7,
"recurrence_date_to": "2099-12-31"
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"recurrence": {
"recurrence_cycle": "DAY",
"recurrence_period": 7,
"recurrence_date_to": "2099-12-31",
"recurrence_state": "REQUESTED"
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}In order to create an on-demand recurring payment, use the payment creation API call. You need to pass the recurrence object in the request body. The following parameters are mandatory:
recurrence_cycle- always set toON_DEMANDrecurrence_date_tosets the expiration of the recurring payment. The customer will be automatically charged until this date. The date needs to be in the future and it needs to be further than the last day the customer is going to be charged.
The recurrence_period parameter is not used. Subsequent charges are done using a dedicated API call. That’s how you specify the amount, order ID and other payment parameters.
The charge is done asynchronously so upon receiving the response to the API call, the payment is usually CREATED. When the payment is completed, a HTTP notification is sent that you can use to check the payment status.
See payment creation, creating a recurrence and recurrence in the API reference section for technical details.
Initial ON_DEMAND payment creation
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 100,
"currency": "CZK",
"order_number": "123456",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"recurrence": {
"recurrence_cycle": "ON_DEMAND",
"recurrence_date_to": "2099-12-31"
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notification-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 100,
"currency": "CZK",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"recurrence": {
"recurrence_cycle": "ON_DEMAND",
"recurrence_date_to": "2099-12-31",
"recurrence_state": "REQUESTED"
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}Subsequent charge request
POST /api/payments/payment/3123456789/create-recurrence HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456780,
"parent_id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"lang": "cs",
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}Recurrence can be canceled by one of the following:
- By the merchant using the Void recurrence API call
- By the merchant using the GoPay administration
- By the customer using a link in the payment confirmation email
- By GoPay (usually when the customer requests it)
- Automatically when the
recurrence_date_tocomes - Automatically when the payment card expires
If you use try to use the API call to cancel a recurrence that has been canceled previously, the API call will result in an error.
By default, we don’t send a HTTP notification when a recurrence is canceled. If you wish to receive HTTP notifications for this case, please contact our techsupport
For technical details of the API call, see voiding a recurring payment
Voiding a recurring payment
POST /api/payments/payment/3123456789/void-recurrence HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"result": "FINISHED"
}In the response to payment inquiry of an initial recurring payment, the recurrence object is also returned. It contains the recurrence_state parameter which desribes the state of the recurrence. The possible values are specified in recurrence state. You can use this to verify whether you can make subsequent charges to this payment.
Recurring payment inquiry. See payment inquiry
GET /api/payments/payment/3123456789 HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "PAID",
"payment_instrument": "PAYMENT_CARD",
"amount": 100,
"currency": "CZK",
"payer": {
"payment_card": {
"card_number": "440507******4448",
"card_expiration": "9912",
"card_brand": "Visa",
"card_issuer_country": "CZE",
"card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
},
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"recurrence": {
"recurrence_cycle": "ON_DEMAND",
"recurrence_date_to": "2099-12-31",
"recurrence_state": "STARTED"
},
"lang": "cs",
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/...",
}Preauthorized payment allows booking of funds on the customer’s account without immediately charging them. We guarantee that it will be possible to capture the amount for 4 days. During this period you can either capture the amount or release it. It is possible to either capture the full amount or just a part of it. You can use this for example if you’re not sure that the purchased goods is available.
Preauthorized payments are available on the sandbox. If you want to use them in production, pleas contact our techsupport. Please specify whether you want to also activate partial captures.
In order to create a preauthorized payment, use the payment creation API call. In this case, it is required to pass the preauthorization parameter set to true.
After the customer authorizes the payment, its state will change to AUTHORIZED and a HTTP notification is sent. At this point, the authorized amount is booked on the customer’s account.
Preauthorized payment creation
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"preauthorization": true,
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notification-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"preauthorization": {
"requested": true,
"state": "REQUESTED"
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}The authorized payment can be captured in two ways:
- Full capture. Use the Capturing a preauthorized payment API call, no body is sent in this request. This API call will charge the preauthorization amount on the customer’s account and transfer it to merchant’s business account.
- Partial capture. Use the Partially capturing a preauthorized payment API call. In the body specify the required amount in the
amountparameter. The amount can’t be higher than the preauthorization amount. If the capture amount is lower than the preauthorization amount, the payment details will be updated so the amount reflects this. The rest of the funds will be released back to cusomer’s account.
The state of the payment then changes to PAID
Preauthorization capture
POST /api/payments/payment/3123456789/capture HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"result": "FINISHED"
}Partial preauthorization capture
POST /api/payments/payment/3123456789/capture HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 5000
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"result": "FINISHED"
}Preauthorized funds can also be released back to the customer using the Voiding a preauthorized payment API call. After releasing the funds, it is impossible to capture them and the state of the payment changes to CANCELED
Voiding a preauthorization
POST /api/payments/payment/3123456789/void-authorization HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"result": "FINISHED"
}It is also possible to do authorization of a zero amount. The customer’s card will be authorized but no amount will be blocked. This can be combined with e.g. on-demand recurring payment - you can provide for example a trial period.
A zero amount cannot be captured (the API call will result in an error) but it can be voided.
The combination of a zero amount preauthorization and a recurring payment is currently not supported by Raiffeisenbank!
Creating a zero amount preauthorization
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 0,
"currency": "CZK",
"order_number": "123456",
"preauthorization": true,
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notification-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 0,
"currency": "CZK",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"preauthorization": {
"requested": true,
"state": "REQUESTED"
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}It is possible to receive a unique card fingerprint with card payments. You can use it to compare whether two payments were carrried out using the same payment card. If the card was used via Apple Pay or Click To Pay, the fingerprint will be different.
card_fingerprint is always generated for cards saved using a card token, see Card token payment.
It is also possible to receive the fingerprint for each card payment, in which case it will be included in the payment-card object in the response to payment inquiry.
By default the card fingerprints are not created. If you want to have this feature activated, please contact our techsupport
When the customer pays with a card, you can request for the card to be saved. In that case, a card token will be generated that you can use for subsequent payments. If you do use it, the customer will not have to input the card details manually.
Card tokens are not available by default. If you want to use them or test them on the sandbox, please contact our techsupport.
Steps for using a card token:
- Create a payment with the
request_card_tokenparameter set totrue - After the customer finishes the payment, inquire the payment details
- Extract the value of
card_idfrom the response - Inquire the payment card
- Extract the value of
card_tokenfrom the response
In order to get a card token, use the payment creation API call, in the payer object send the request_card_token parameter set to true. In the allowed_payment_instruments send PAYMENT_CARD as the only value (see examples).
After the payment is finished, inquire the payment details and the card_id will be present in the payer object. You can then use this identifier to inquire the payment card details, including the token.
Creating a payment with token request
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"payer": {
"allowed_payment_instruments": ["PAYMENT_CARD"],
"request_card_token": "true",
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"allowed_payment_instruments": ["PAYMENT_CARD"],
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": 8179544857
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}Payment inquiry for a payment with token request
GET /api/payments/payment/3123456789 HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "PAID",
"payment_instrument": "PAYMENT_CARD",
"amount": 10000,
"currency": "CZK",
"payer": {
"allowed_payment_instruments": ["PAYMENT_CARD"],
"payment_card": {
"card_number": "440507******4448",
"card_expiration": "9912",
"card_brand": "Visa",
"card_issuer_country": "CZE",
"card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
},
"contact": {
"email": "john.doe@example.com"
},
"card_id": "9876543210"
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"lang": "en",
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/...",
}Using a dedicated API call and the card_id, you can get the details of a saved card. These contain:
- Card details like masked PAN and expiration
card_fingerprintwhich you can use to verify if this card has already been savedcard_tokenwhich you can use for subsequent payments
Before accessing the card details, first check the status parameter to make sure the card is active. If not, the other parameters will not be present.
Card details inquiry of an active card
GET /api/payments/cards/9876543210 HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"card_id": 9876543210,
"card_number": "440507******4448",
"card_expiration": "9912",
"card_brand": "Visa",
"card_issuer_country": "CZE",
"card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
"card_fingerprint": "0c823534ec582c97fa85c0bf7b020ee25a0a5af13974709bb329a709a79c2b3e",
"card_token": "YZ4E8f2jJA8cEDz1s0lO4BMXo6skkvItJddyrLhSyPa01T/cvrl+DwKsEqehFG7SQxJZUsBcgZ6sei4AKxrHHap7BofFr+SH3oHJyta0axiBB7MST3IWqrsq5ZtfukBrgwPBocNDPd/RnQs=",
"status": "ACTIVE"
}Card details inquiry of a deleted card
GET /api/payments/cards/9876543210 HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"card_id": 9876543210,
"status": "DELETED"
}In order to use a card token, use the payment creation API call. In the payer set the allowed_card_token parameter to a formerly acquired card_token. This way, the customer will not have to input the card details themselves. 3DS authentication may still be required.
In the payer object, in the allowed_payment_instruments array send PAYMENT_CARD as the only value (see examples).
Payment using a card token
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"payer": {
"allowed_payment_instruments": ["PAYMENT_CARD"],
"allowed_card_token": {{YOUR-CARD-TOKEN}},
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"allowed_payment_instruments": ["PAYMENT_CARD"],
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}The saved card can be deleted by the merchant using a dedicated API call. It can also be deleted by GoPay (for example if it expires or is not used for a long time). In any case, the card_status changes to deleted and the payment card details will not be available anymore. A HTTP notification is sent to the merchant whenever a card gets updated or deleted.
Deletion of a saved card
DELETE /api/payments/cards/987654321 HTTP/1.1
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 204 No ContentIn order to use card tokens, it is necessary to register a HTTP notification URL. Card HTTP notifications are sent whenever:
- A saved card has been deleted by the merchant or GoPay
- Some card details were updated (for example an old card expires)
The notification is a GET request with card_id query parameter appended, for example:
GET https://example.com/card-notify?card_id=123456
Using the Card ID it is possible to check the status and details of the card using the payment card inquiry API call.
By default PSD2 bank payments go through the following steps:
- The customer is redirected to their bank where they give consent to GoPay for using AISP and PISP
- The customer is redirected back to the payment gateway, where they select the account (if they have more than one) and confirm the payment
- The customer is redirected to their bank where they authorize the payment
- The customer is redirected back to the payment gateway, where the payment is finished
In the remember mode, GoPay keeps the consent from the first step for subsequent payments and provides a bank account token to the merchant. You can then use this token so the customer won’t need to give consent to GoPay again and will be asked directly to authorize the payment. The consent lasts for 90 days.
The remember mode is not active by default. If you want to use it, please contact our techsupport. GoPay will then evaluate this request.
The remember mode is supported for all banks that have PSD2 payments active with GoPay.
Without account data
After going through the consent authorization step, the payment gateway lists all of their accounts. The customer chooses which account to use and goes on to payment authorization.
Use the payment creation API call and in the payer object send the following:
allowed_payment_instruments- only send theBANK_ACCOUNTvalue in the arrayallowed_swifts- send only the SWIFT code of the customer’s bank- PSD2 payments need to be enabled for this bank
With account data
If you already know the customer’s account data and want to get a token of a specific account, you can send the account data in the API call. After going through the consent authorization step, the gateway lists the customer’s accounts. If no account matches the account data sent by the merchant, the payment gets declined. Otherwise the customer goes on to the payment authorization step.
Use the payment creation API call and in the payer object send the following:
allowed_payment_instruments- only send theBANK_ACCOUNTvalue in the arrayallowed_swifts- send only the SWIFT code of the customer’s bank- send the bank account object in which you send the account data either in the Czech format or the international format
- PSD2 payments need to be enabled for this bank
Payment creation without account data
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"payer": {
"allowed_payment_instruments": ["BANK_ACCOUNT"],
"allowed_swifts": ["AIRACZPP"],
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"allowed_payment_instruments": ["BANK_ACCOUNT"],
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}Payment creation with account data in the Czech format
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"payer": {
"allowed_payment_instruments": ["BANK_ACCOUNT"],
"allowed_swifts": ["AIRACZPP"],
"bank_account": {
"account_number": "1234562",
"bank_code": "3030"
},
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"allowed_payment_instruments": ["BANK_ACCOUNT"],
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}Payment creation with account data in the international format
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"payer": {
"allowed_payment_instruments": ["BANK_ACCOUNT"],
"allowed_swifts": ["AIRACZPP"],
"bank_account": {
"iban": "CZ8930300000000001234562"
},
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"allowed_payment_instruments": ["BANK_ACCOUNT"],
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}When the initial payment is PAID, the merchant receive a HTTP notification (see Receiving the HTTP notification ), which contains the payment ID. Using the ID, do a payment inquiry, extract the bank_account object from the payer object in the response - it contains the token.
Payment inquiry for PSD2 remember mode payment
GET /api/payments/payment/3123456789 HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "PAID",
"payment_instrument": "BANK_ACCOUNT",
"amount": 10000,
"currency": "CZK",
"payer": {
"allowed_payment_instruments": ["BANK_ACCOUNT"],
"bank_account": {
"account_number": "1234562",
"bank_code": "3030",
"iban": "CZ8930300000000001234562",
"account_name": "John Doe",
"account_token": "3c8bdc18281a9d5f60ab9675d9b0953805050157bf60fb37e2060a04a58e79bf"
},
"contact": {
"email": "john.doe@example.com",
"country_code": "CZE"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"lang": "en",
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/...",
}Use the payment creation API request and in the payer object send the bank account object with the account token. The customer will not go through the consent authorization step, they will be sent directly to the payment authorization step.
It is also required to send the allowed_payment_instruments array containing only the BANK_ACCOUNT value.
Payment creation with account token
POST /api/payments/payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 1000,
"currency": "CZK",
"order_number": "123456",
"payer": {
"allowed_payment_instruments": ["BANK_ACCOUNT"],
"bank_account": {
"account_token": "{{YOUR-ACCOUNT-TOKEN}}"
},
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 1000,
"currency": "CZK",
"payer": {
"allowed_payment_instruments": ["BANK_ACCOUNT"],
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}By default, the payment gateway offers all payment methods that are enabled by the merchant (Apple Pay only for supported devices). For more information on how to enable payment methods, see How do I manage my payment methods settings?.
When creating the payment via API, it is possible to further specify payment methods in the payer object:
allowed_payment_instruments- array of payment methods that will be available on the payment gatewaydefault_payment_instrument- used to pre-select one specific payment methodallowed_swifts- SWIFT codes of banks that can be used to paydefault_swift- a pre-selected bank
Allowed payment methods
- Case 1: The
allowed_payment_instrumentsarray is omitted entirely. The payment gateway will list all payment methods that are enabled - Case 2: The array contains two or more values. The payment gateway will list these payment methods and the customer can choose one
- Case 3: The array contains exacly on value. The payment gateway will open directly on the detail of this payment method, skipping the listing.
Payment methods that are disabled will be removed from the array.
Pre-selected payment method
You can use the default_payment_instrument parameter to specify one payment method to be preselected. This only works with cases 1 and 2 from above, it has no impact on case 3. If you omit this parameter, the customer will see a listing of available payment methods upon opening the payment gateway. Using this parameter you can redirect the customer directly on a specific payment method. They will still be able to choose a different payment method. The pre-selected payment method must be one of the available payment methods.
allowed_payment_instruments is omitted
"payer": {
"contact": {
"email": "john.doe@example.com"
}
}allowed_payment_instruments contains several items
"payer": {
"allowed_payment_instruments": ["PAYMENT_CARD", "BANK_ACCOUNT", "PAYPAL"]
"contact": {
"email": "john.doe@example.com"
}
}allowed_payment_instruments contains exactly one item
"payer": {
"allowed_payment_instruments": ["PAYMENT_CARD"]
"contact": {
"email": "john.doe@example.com"
}
}Only a default_payment_instrument is sent - it muse be available
"payer": {
"default_payment_instrument": "PAYMENT_CARD",
"contact": {
"email": "john.doe@example.com"
}
}Both allowed_payment_instruments and default_payment_instrument are sent - the latter needs to be an element of the former
"payer": {
"allowed_payment_instruments": ["PAYMENT_CARD", "BANK_ACCOUNT", "PAYPAL"],
"default_payment_instrument": "PAYMENT_CARD",
"contact": {
"email": "john.doe@example.com"
}
}In order to utilize this functionality, BANK_ACCOUNT must be included in the allowed_payment_instruments array.
Online vs. Offline
GoPay provides two types of bank account transfers. An Offline transfer displays the bank account details to the customer on the gateway, including the account number, amount, etc. The customer can pay from any bank, but they must initiate the transfer manually using the provided details (or QR code).
An Online transfer, on the other hand, redirects the customer directly to their online banking site with a pre-filled bank transfer form. This method forces the customer to use a specific bank.
Allowed SWIFTs
You can restrict which banks may be used for payments with the allowed_swifts array.
- Case 1: If the
allowed_swiftsfield is omitted, the customer will have the option to use any bank to complete their payment. - Case 2: If one or more SWIFT codes are included in the
allowed_swiftsarray, only the banks that were specified in theallowed_swiftsarray will be accessible. - Case 3: If only one SWIFT code is included in the
allowed_swiftsarray, andBANK_ACCOUNTis the sole entry in theallowed_payment_instrumentsarray, the customer will be redirected directly to their bank, assuming online transfers are supported by the specified bank.
Pre-selected Swift
By using the default_swift parameter, you can pre-select a bank for your customer. The pre-selected bank will be elevated to the top of the available banks list and will be highlighted for easy identification.
GoPay offers BNPL (Buy Now Pay Later) payments, also known as deferred payments. Currently, there are two such methods available - TWISTO and SKIPPAY - see the PaymentInstrument enumeration. These payments are available in two modes:
- Deferred Payment - The customer pays the supplier the full amount later (in API
DEFERRED_PAYMENT) - Payment in Thirds - The customer pays one-third of the amount during the payment, and the remaining amount is paid to the supplier in two additional installments (in API
PAY_IN_THREE)
When creating a payment, these modes can be influenced. In the Payer object, the following parameters can be set:
- allowed_bnpl_types - The types of BNPL payments that will be available
- default_bnpl_type - The default selected type of BNPL payment
These parameters make sense to pass if you have at least one of these payment methods enabled in your e-shop and you are passing it in the allowed_payment_instruments parameter. The settings will apply to all suppliers. Possible values are listed in the BNPL Types enumeration.
The display or non-display of individual methods and BNPL types is also determined by the payment amount, as each provider sets limits for which the payment method is available:
- Twisto Deferred Payment - no limit
- Twisto Payment in Thirds - From 1,500 CZK upwards
- Skip Pay Deferred Payment - 0 to 50,000 CZK
- Skip Pay Payment in Thirds - 3,000 to 100,000 CZK
The Apple Pay payment method is connected to the Payment Card payment method. To use it, you need to have card payments enabled.
Apple Pay is only available on supported web browsers and devices (typically Apple devices that support Touch ID or Face ID). We advise offering this payment method only to customers who have the capability to use it. You can use JavaScript to confirm that your customer meets these requirements. For more information, visit the Apple developer site.
The first condition to check is window.ApplePaySession, which confirms that the Apple Pay JS API is accessible in the customer’s browser. This check works even if your site does not have TLS security (HTTP). If your website lacks TLS, this is the recommended method.
The second condition to check is window.ApplePaySession.canMakePayments(), which verifies that the current device is capable of making Apple Pay payments. This check requires a HTTPS connection, so it can only be used if your website has TLS security. This check is more reliable, so we recommend using both checks if possible.
The official Apple developer portal also provides information on:
- Using Apple Pay marks and artwork in their Marketing section.
- Customizing the Apple Pay button in their guide on Styling the Apple Pay Button using CSS.
You can find all downloadable logos in our article, Which Logos and Names of the Payment Methods Should I Prefer?
Checking whether Apple Pay is available on the current device
if (window.ApplePaySession) {
// condition is met only if Apple Pay JS is available in the currenct browser
}
if (window.ApplePaySession && window.ApplePaySession.canMakePayments()) {
// condition is met only if Apple Pay is available on the current device
}Creates a hidden styled button. If Apple Pay is available, the button is made visible using JavaScript
<form action="/create-apple-payment" method="post">
<button type="submit" id="apple-pay-button" lang=en style="
display: none;
-webkit-appearance: -apple-pay-button;
-apple-pay-button-type: plain;
-apple-pay-button-style: black;"></button>
</form>
<script>
if(window.ApplePaySession && window.ApplePaySession.canMakePayments()) {
document.querySelector("#apple-pay-button").style.display = "inline-block";
}
</script>In order to initiate the payment gateway, you need the gw_url from the API response to succesful payment creation request.
The redirect version of the payment gateway is initiated simply by redirecting the customer to the gw_url. This action takes the customer to the secure GoPay site where the payment gateway is displayed and the customer can complete the payment. The gw_url address is obtained from the API response to a successful payment creation request. The next step is to use this URL to redirect the customer. This can be achieved in several ways:
- Using a link
- Using an HTTP redirection
- Using JavaScript
Description of using a link:
- An HTML form is sent to the server using POST.
- The server communicates with GoPay to obtain the
gw_url. - The server responds with a new page with the
gw_urlembedded (for example, using PHP or a template system). - The customer clicks the link to be redirected.
Description of using an HTTP redirection:
- An HTML form is sent to the server using POST.
- The server communicates with GoPay to obtain the
gw_url. - The server returns an HTTP Redirection (e.g., 302 Found) and sets the
gw_urlas the Location header. - The customer’s browser automatically redirects the customer.
Description of using JavaScript:
- An
event listeneris attached to the form, listening for thesubmitevent. When triggered, it calls a function which:- Prevents the default action to avoid page reload.
- Serializes the form content as JSON (if necessary).
- Sends an AJAX request with the form data to the server.
- The server communicates with GoPay to obtain the
gw_url. - The server responds to the AJAX request with the
gw_url. - Finally, the customer is redirected using JavaScript (e.g., using
window.location).
We omit exception handling in the examples for the sake of simplicity. In a production environment, the developer should manage this.
We assume that the /pay endpoint handles processing the form and creating the payment. A new page is returned with the gw_url placed as a link.
<!-- The first page, e.g. /checkout -->
<form action="/pay" method="post">
<!-- Contents of the checkout form -->
<button type="submit">Confirm</button>
</form>
<!-- Second page, e.g., /pay. gw_url is placed by the server -->
<a href="https://gw.sandbox.gopay.com/gw/v3/...">
<button>Pay</button>
</a>We assume that the /pay endpoint handles processing the form, creating the payment and responding with an HTTP Redirection to the gw_url.
<!-- The first page, e.g. /checkout -->
<form action="/pay" method="post">
<!-- Contents of the checkout form -->
<button type="submit">Pay</button>
</form>
<!-- Server HTTP Response -->
HTTP/1.1 302 Found
Location: https://gw.sandbox.gopay.com/gw/...We assume that the /create-payment endpoint accepts a JSON with the form data, creates a payment and returns a JSON with the gw_url. This example works on all modern browsers.
<form action="/create-payment" method="post" id="payment-form">
<!-- Contents of the checkout form -->
<button type="submit">Zaplatit</button>
</form>
<script>
document.addEventListener("DOMContentLoaded", () => {
// attaching an event listener to the form
const paymentForm = document.querySelector("#payment-form");
paymentForm.addEventListener("submit", async (event) => {
// prevent page reload
event.preventDefault();
// serialization of the form data to JSON
const formData = new FormData(paymentForm);
const formObject = Object.fromEntries(formData.entries());
// asynchronous payment creation
const response = await fetch(paymentForm.action, {
method: paymentForm.method,
headers: {
"Content-Type": "application/json",
Accept: "application/json"
},
body: JSON.stringify(formObject)
});
// processing the server response and redirection to the gw_url
const result = await response.json();
window.location.href = result.gw_url;
})
})
</script>The inline version of the payment gateway is launched as an overlay over the online shop. The customer is not redirected, and the URL of the shop remains displayed in the URL bar. More information and screenshots can be found in our article, Basic Features of the Inline Payment Gateway. If the customer is redirected to a third-party website (like 3DS or online banking) during the payment process, they will return to the redirect version of the gateway.
Your website must have a TLS certificate (support HTTPS). If HTTPS is not available, the customer will always be directed to the redirect gateway.
The first step is to obtain the gw_url using the API for payment creation. This URL is then used to instantiate the payment gateway:
- Using a form
- Using JavaScript
The JavaScript approach has the advantage of creating the payment and instantiating the gateway in one step, requiring only one click from the customer. The form approach involves two steps.
Description of using a form:
- An HTML form with the order data is sent to the server using POST.
- The server communicates with GoPay to obtain the
gw_url. - The server responds with a new page where the
gw_urlis placed as theactionattribute of another HTML form. This can be done using PHP or a template system, for example. Usehttps://gw.sandbox.gopay.com/gp-gw/js/embed.jsfor sandbox orhttps://gate.gopay.cz/gp-gw/js/embed.jsfor production. - The method should be set to
POST, theidattribute should begopay-payment-button, and ascripttag should be placed inside the form (see the example). - By submitting the form, the inline payment gateway is instantiated.
Description of using JavaScript:
- Inside the HTML head, place the link to our JavaScript (
https://gw.sandbox.gopay.com/gp-gw/js/embed.jsfor sandbox orhttps://gate.gopay.cz/gp-gw/js/embed.jsfor production). - An
event listeneris attached to the form, listening for thesubmitevent. When triggered, it calls a function which:- Prevents the default action to avoid page reload.
- Serializes the form content as JSON (if necessary).
- Sends an AJAX request with the form data to the server.
- The server communicates with GoPay to obtain the
gw_url. - The server responds to the AJAX request with the
gw_url. - The
_gopay.checkout()method is called, which accepts a configuration object as a parameter. - The
gw_urlis passed in thegatewayUrlfield whiletrueis passed as theinlinefield (see the example).
We omit exception handling in the examples for the sake of simplicity. In a production environment, the developer should manage this.
We assume that the /pay handles processing the form and creating the payment. A new page is returned with the gw_url placed in the form
<!-- The first page, e.g. /checkout -->
<form action="/pay" method="post">
<!-- Contents of the checkout form -->
<button type="submit">Confirm</button>
</form>
<!-- The next page, e.g. /pay. The gw_url is placed by the server -->
<form action="https://gw.sandbox.gopay.com/gw/v3/..." method="POST" id="gopay-payment-button">
<button type="submit">Pay</button>
<script type="text/javascript" src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js"></script>
</form>We assume that the /create-payment endpoint accepts the form data as JSON, creates a payment and returns the gw_url in the response body. The example is compatible with modern browsers.
<!-- Inside the html head -->
<script src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js" defer></script>
<!-- Inside the html body -->
<form action="/create-payment" method="post" id="payment-form">
<!-- Contents of the checkout form -->
<button type="submit">Pay</button>
</form>
<script>
document.addEventListener("DOMContentLoaded", () => {
// attaching an event listener to the form
const paymentForm = document.querySelector("#payment-form");
paymentForm.addEventListener("submit", async (event) => {
// prevent page reload
event.preventDefault();
// serialization of the form data to JSON
const formData = new FormData(paymentForm);
const formObject = Object.fromEntries(formData.entries());
// asynchronous payment creation
const response = await fetch(paymentForm.action, {
method: paymentForm.method,
headers: {
"Content-Type": "application/json",
Accept: "application/json"
},
body: JSON.stringify(formObject)
});
// processing the response and instantiating the payment gateway
const result = await response.json();
_gopay.checkout({gatewayUrl: result.gw_url, inline: true});
})
})
</script>At present, we provide our payment gateway exclusively as a web application. If you intend to integrate it into a mobile app, this is an important consideration. This applies to all payment methods, including Apple Pay and Google Pay. Currently, these payment methods cannot be used natively within a mobile app without the payment gateway; customer interaction with the web gateway is always required.
Do not use WebView. WebView does not support the full functionality of a web browser, which can cause issues with the proper operation of the payment gateway. Apple Pay and Google Pay are not supported. This includes technologies like WebView for Android and WKWebView for Apple devices.
Do use technologies that function as fully-fledged web browsers, such as Chrome Custom Tabs for Android and SFSafariViewController for Apple devices.
After completing or canceling the payment, the customer is redirected back to the online shop. The customer is usually redirected to the return_url that was provided in the payment creation API request.
When instantiating the inline payment gateway using JavaScript, it is possible to pass a callback function as the second argument of the _gopay.checkout method. In this case, the customer is not redirected to the return_url but the overlay closes and the customer returns to the original page, where the gateway was launched.
The body of the payment creation API call contains the callback. Inside of this object, the return_url is sent. When the customer is redirected from the payment gateway (automatically when the payment is finished or by manually clicking the “Back to eshop” button) with a GET request and the ID of the payment in a query parameter id.
You can use this parameter to check the payment state using the payment inquiry API call. See Processing the state of the payment for information how to handle the individual payment states.
When initializing the inline payment gateway using JavaScript, it’s possible to provide a callback function as the second argument to the _gopay.checkout method. In this scenario, the customer isn’t redirected to the return_url. Instead, the callback function is invoked directly on the original page from which the payment gateway was initialized. This function receives an object as an argument, containing the id of the payment and the original return_url.
Note: If any redirect (to 3DS, online banking, or similar) occurs during the payment process, the customer will be taken back to the redirect gateway and from there to the
return_url. The callback function will only execute if no redirects occur during the payment process.
The payment id can be extracted from the object passed to the callback function, or you may already have it stored from the payment creation request.
We omit exception handling in the examples for the sake of simplicity. In a production environment, the developer should manage this.
We assume that the payment is created already and the gwUrl variable contains the gw_url of the payment. We also assume that the /status endpoint accepts the id of the payment as a query parameter, inquires the payment using the REST API and forwards the response to the frontend.
// An object gets passed to the callback function which contains the id of the payment
_gopay.checkout({gatewayUrl: gwUrl, inline: true}, async (checkoutResult) => {
const paymentId = checkoutResult.id
// asynchronous request to check the payment status
const statusResponse = await fetch(`/status?id=${paymentId}`);
const statusResult = await statusResponse.json();
// in this example we simply log the result to the console
console.log(`Stav platby: ${statusResult.state}`);
});We assume that the /create-payment endpoint accepts a JSON with the form content, creates a payment and returns a JSON that contains the id and gw_url of the payment. We also assume that the /status endpoint accepts the id of the payment as a query parameter, inquires the payment using the REST API and forwards the response to the frontend.
<!-- V hlavičce html dokumentu -->
<script src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js" defer></script>
<!-- V tělě html dokumentu -->
<form action="/create-payment" method="post" id="payment-form">
<!-- Obsah checkout formuláře -->
<button type="submit">Zaplatit</button>
</form>
<script>
document.addEventListener("DOMContentLoaded", () => {
// attaching an event listener to the form
const paymentForm = document.querySelector("#payment-form");
paymentForm.addEventListener("submit", async (event) => {
// preventing page reload
event.preventDefault();
// serialization of the form data to JSON
const formData = new FormData(paymentForm);
const formObject = Object.fromEntries(formData.entries());
// asynchronous payment creation
const response = await fetch(paymentForm.action, {
method: paymentForm.method,
headers: {
"Content-Type": "application/json",
Accept: "application/json"
},
body: JSON.stringify(formObject)
});
// extracting the id of the payment into a variable
const result = await response.json();
const paymentId = result.id;
// We don't need to extract the ID from the argument object
_gopay.checkout({gatewayUrl: result.gw_url, inline: true}, async (checkoutResult) => {
// asynchronous request to check the payment status
const statusResponse = await fetch(`/status?id=${paymentId}`);
const statusResult = await statusResponse.json();
// in this example we simply log the result to the console
console.log(`Stav platby: ${statusResult.state}`);
});
});
});
</script>When the customer returns to the online shop, you can interpret the state of the payment to understand one of four possible scenarios:
- The payment was successful (
PAIDorAUTHORIZEDstate) - The payment failed (
CANCELEDorTIMEOUTEDstate) - There was no attempt to complete the payment (
CREATEDstate) - We’re still awaiting the payment result (
PAYMENT_METHOD_CHOSENstate)
For more details about these states and their progression, refer to Lifecycle of a Payment.
The AUTHORIZED state is specific to the Preauthorized payment, indicating that the authorization was successful and it’s possible to capture the payment.
If the payment state is CREATED, it means the customer hasn’t attempted to complete the payment. They may want to select a different payment method. In this case, we suggest redirecting them to the checkout page and offering the option to change the payment method.
If the payment state is PAYMENT_METHOD_CHOSEN, it indicates that the customer attempted to complete the payment, but we have not yet received the payment result. This can occur, for example, with offline bank payments, where we wait until the funds have been credited to GoPay’s bank account. As this type of payment might still be completed in the future, we advise against encouraging the customer to initiate a new payment. You will be informed via the HTTP notification when the payment result is available.
This operation serves for obtaining the access token, that is used in all other API calls. The client credentials are sent in the Authorization header in base64 as ClientID:ClientSecret with respect to RFC 7617.
Request headers
Always application/json
Always application/x-www-form-urlencoded
Basic HTTP auth
Request body
Token permission scope
Always client_credentials
Responses
Body
Always bearer
The access token
Not currently in use
Token expiration in seconds
HTTP token request
POST /api/oauth2/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic PENsaWVudElkPjo8Q2xpZW50U2VjcmV0Pg==
scope=payment-all&grant_type=client_credentials
HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type":"bearer",
"access_token":"AAAnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p",
"expires_in":1800,
"refresh_token": "ObrapXqkh3SaWifBQ4PS0kYRIbXGqUDr4t6PECZFE0lFox5uXtWNb/QzeDrk8wsWDVOn+vvCAPCPAnr+B8aon+JpW5hPVwlNj71eupst+k8="
}Initializing GoPay in cURL
// example of obtaining a token with a scope of token rights to create a payment and query the payment status on a test environment
curl -v -N https://gw.sandbox.gopay.com/api/oauth2/token \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "<ClientId>:<ClientSecret>" \
-d "grant_type=client_credentials&scope=payment-create"GoPay initialization in PHP
// We assume the $goid, $clientId and $clientSecret contain your test credentials
$gopay = GoPay\payments([
'goid' => $goid,
'clientId' => $clientId,
'clientSecret' => $clientSecret,
'gatewayUrl' => 'https://gw.sandbox.gopay.com/api'
]);
// Token is requested automatically, no method call necessary
// In the following examples, the $gopay variable created here will be reusedGoPay initialization in Python
import gopay
# We assume the goid, client_id a client_secret contain your test credentials
api = gopay.payments({
"goid": goid,
"client_id": client_id,
"client_secret": client_secret,
"gateway_url": "https://gw.sandbox.gopay.com/api"
})
# Token is requested automatically, no method call necessary
# In the following examples, the api variable created here will be reusedGoPay initialization in .NET (C#)
var gopay = new GPConnector("https://gw.sandbox.gopay.com/api", {{YOUR-CLIENT-ID}}, {{YOUR-CLIENT-SECRET}});
gopay.GetAppToken();GoPay initialization in Java
IGPConnector connector = HttpClientGPConnector.build("https://gw.sandbox.gopay.com/api");
connector.getAppToken({{YOUR-CLIENT-ID}},{{YOUR-CLIENT-SECRET}}); {id}/refund{id}{id}/refundsPayment creation. Using the recurrence and preauthorization parameters, the payment can be specified as recurring or preauthorized respectively.
Request headers
Bearer authentication with the access token
Always application/json
Always application/json
Request body
Total amount in cents
Payment currency
Order identification for the online shop, alphanumeric characters
Information about the recipient
Information about the payer and payment methods
Return and notification URLs
Order description, alphanumeric characters
Set to true for preauthorized payments
Contains information about payment recurrence for recurring payment
Individual items of the payment
Additional parameters for the payment
Language of the gateway UI
Responses
Body
Payment ID
Order ID forwarded from the payment request
Payment state
Total amount in cents
Payment currency
Information about the payer and payment methods
Information about the recipient
Additional parameters for the payment
Language of the gateway UI
Contains information about payment recurrence for recurring payment
Contains information about preauthorization for preauthorized payment
URL for initiating the gateway
Minimal payment creation
POST /api/payments/payment HTTP/1.1
Authorization: Bearer {{YOUR-TOKEN}}
Content-Type: application/json
Accept: application/json
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"gw_url": "https://gw.sandbox.gopay.com/gw/..."
}Full payment creation
POST /api/payments/payment HTTP/1.1
Authorization: Bearer {{YOUR-TOKEN}}
Content-Type: application/json
Accept: application/json
{
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"order_description": "Test order",
"payer": {
"allowed_payment_instruments": [
"PAYMENT_CARD", "BANK_ACCOUNT", "GPAY", "APPLE_PAY"
],
"default_payment_instrument": "PAYMENT_CARD",
"allowed_swifts": [
"GIBACZPX", "CEKOCZPP", "FIOBCZPP", "AGBACZPP", "AIRACZPP"
],
"default_swift": "GIBACZPX",
"contact": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone_number": "+420123456789",
"city": "Test city",
"street": "Test street 10",
"postal_code": "10000",
"country_code": "CZE"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
},
"items": [
{"type": "ITEM", "name": "Test item", "amount": 10000}
],
"additional_params": [
{"name": "Test name", "value": "Test value"}
],
"lang": "CS"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 10000,
"currency": "CZK",
"payer": {
"allowed_payment_instruments": [
"CLICK_TO_PAY",
"APPLE_PAY",
"PAYMENT_CARD",
"GPAY",
"BANK_ACCOUNT"
],
"default_payment_instrument": "PAYMENT_CARD",
"default_swift": "GIBACZPX",
"contact": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone_number": "+420123456789",
"city": "Test city",
"street": "Test street 10",
"postal_code": "10000",
"country_code": "CZE"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"additional_params": [
{"name": "Test name", "value": "Test value"}
],
"lang": "cs",
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}Standard payment creation in cURL (minimum and full variants)
// creation a standard payment with minimum mandatory parameters on a test environment
Request:
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment" \
-H "Authorization: Bearer {{YOUR-TOKEN}}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"callback": {
"return_url": "https://www.example.xy/return",
"notification_url": "https://www.example.xy/notify"
}
}'
Response:
{"id":1234567890,"order_number":"123456","state":"CREATED","amount":10000,"currency":"CZK","payer":{},"target":{"type":"ACCOUNT","goid":{{YOUR-GOID}}},"gw_url":"https://gw.sandbox.gopay.com/gw/v3/xxxxxxxxxxxxxxxxxxxxxxxxx"}
// creation of standard payment with extended payer, items, additional_params objects on a test environment
Request:
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment" \
-H "Authorization: Bearer {{YOUR-TOKEN}}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"payer": {
"allowed_payment_instruments": [
"PAYMENT_CARD",
"BANK_ACCOUNT"
],
"default_payment_instrument": "PAYMENT_CARD",
"allowed_swifts": [
"FIOBCZPP",
"BREXCZPP"
],
"default_swift": "FIOBCZPP",
"contact": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone_number": "+420777456123",
"city": "Test city",
"street": "Test street 10",
"postal_code": "10000",
"country_code": "CZE"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"items": [
{
"type": "DISCOUNT",
"name": "Test item",
"amount": 10000,
"count": 1,
"ean": 1234567890123,
"product_url": "https://www.eshop.xy/kniha/fantasy"
}
],
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"order_description": "Test order",
"lang": "CS",
"callback": {
"return_url": "https://www.example.xy/return",
"notification_url": "https://www.example.xy/notify"
},
"additional_params": [
{
"name": "Additional information",
"value": "123"
}
]
}'
Response:
{"id":1234567890,"order_number":"1234","state":"CREATED","amount":10000,"currency":"CZK","payer":{"allowed_payment_instruments":["PAYMENT_CARD","BANK_ACCOUNT"],"default_payment_instrument":"PAYMENT_CARD","default_swift":"FIOBCZPP","contact":{"first_name":"John","last_name":"Doe","email":"john.doe@example.com","phone_number":"+420777456123","city":"Test city","street":"Test street 10","postal_code":"10000","country_code":"CZE"}},"target":{"type":"ACCOUNT","goid":{{YOUR-GOID}}},"additional_params":[{"name":"additional information","value":"123"}],"lang":"cs","gw_url":"https://gw.sandbox.gopay.com/gw/v3/xxxxxxxxxxxxxxxxxxxxxxxxx"}Minimal and full payment in PHP
use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Payment\PaymentInstrument;
use GoPay\Definition\Payment\BankSwiftCode;
use GoPay\Definition\Language;
// Minimal payment array
$payment = [
'amount' => 10000,
'currency' => Currency::CZECH_CROWNS,
'order_number' => '123456',
'payer' => [
'contact' => [
'email' => 'john.doe@example.com'
]
],
'callback' => [
'return_url' => 'https://example.com/your-return-url',
'notification_url' => 'https://example.com/your-notify-url'
]
];
// Full payment array
$fullPayment = [
'amount' => 10000,
'currency' => Currency::CZECH_CROWNS,
'order_number' => '123456',
'order_description' => 'Test order',
'payer' => [
'allowed_payment_instruments' => [
PaymentInstrument::PAYMENT_CARD,
PaymentInstrument::BANK_ACCOUNT,
PaymentInstrument::GPAY,
PaymentInstrument::APPLE_PAY
],
'default_payment_instrument' => PaymentInstrument::PAYMENT_CARD,
'allowed_swifts' => [
BankSwiftCode::CESKA_SPORITELNA,
BankSwiftCode::CSOB,
BankSwiftCode::FIO_BANKA,
BankSwiftCode::MONETA_MONEY_BANK,
BankSwiftCode::AIRBANK
],
'default_swift' => BankSwiftCode::CESKA_SPORITELNA,
'contact' => [
'first_name' => 'John',
'last_name' => 'Doe',
'email' => 'john.doe@example.com',
'phone_number' => '+420123456789',
'city' => 'Test city',
'street' => 'Test street 10',
'postal_code' => '10000',
'country_code' => 'CZE'
]
],
'callback' => [
'return_url' => 'https://example.com/your-return-url',
'notification_url' => 'https://example.com/your-notify-url'
],
'items' => [
['type' => 'ITEM', 'name' => 'Test item', 'amount' => 10000]
],
'additional_params' => [
['name' => 'Test name', 'value' => 'Test value']
],
'lang' => Language::CZECH
];
// It is not necessary to pass the `target` object, it is added automatically
// Payment creation API call
$response = $gopay->createPayment($payment);
// Check if the API call was successful and extract the response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
// Individual response parameters can be accessed by name
$gatewayUrl = $responseBody['gw_url'];
}Minimal and full payment in Python
from gopay.enums import Currency, BankSwiftCode, PaymentInstrument, Language
# Minimal payment dictionary
payment = {
"amount": 10000,
"currency": "CZK",
"order_number": "123456",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url",
},
}
# Full payment dictionary
full_payment = {
"amount": 10000,
"currency": Currency.CZECH_CROWNS,
"order_number": "123456",
"order_description": "Test order",
"payer": {
"allowed_payment_instruments": [
PaymentInstrument.PAYMENT_CARD,
PaymentInstrument.BANK_ACCOUNT,
PaymentInstrument.GPAY,
PaymentInstrument.APPLE_PAY,
],
"default_payment_instrument": PaymentInstrument.PAYMENT_CARD,
"allowed_swifts": [
BankSwiftCode.CESKA_SPORITELNA,
BankSwiftCode.CSOB,
BankSwiftCode.FIO_BANKA,
BankSwiftCode.MONETA_MONEY_BANK,
BankSwiftCode.AIRBANK,
],
"default_swift": BankSwiftCode.CESKA_SPORITELNA,
"contact": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone_number": "+420123456789",
"city": "Test city",
"street": "Test street 10",
"postal_code": "10000",
"country_code": "CZE",
},
},
"callback": {
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url",
},
"items": [
{"type": "ITEM", "name": "Test item", "amount": 10000}
],
"additional_params": [
{"name": "Test name", "value": "Test value"}
],
"lang": Language.CZECH,
}
# It is not necessary to pass the `target` object, it is added automatically
# API call for payment creation
response = api.create_payment(payment)
# Check if the API call was successful and extract the response body
if response.success:
response_body = response.json
# Individual response parameters can be accessed by name
gateway_url = response_body["gw_url"]Minimal .NET payment. Possible to extend with other parameters.
// Prepare a minimal payment object - can be extended with more parameters
var payment = new BasePayment()
{
Amount = 1000,
Currency = Currency.CZK,
OrderNumber = "123456",
Payer = new Payer
{
Contact = new PayerContact
{
Email = "john.doe@example.com"
}
},
Target = new Target
{
GoId = {{YOUR-GOID}},
Type = Target.TargetType.ACCOUNT
},
Callback = new Callback
{
ReturnUrl = "https://example.com/your-return-url",
NotificationUrl = "https://example.com/your-notify-url"
}
};
// Payment creatioin API call. The result is an instance of the Payment class
try {
var result = connector.CreatePayment(payment);
} catch (GPClientException e) {
System.Console.WriteLine(e);
}{id}/refundPayment refund returns the funds of an already completed payment back to the customer. It can be either partial or full.
Path variables
ID of the payment to be refunded
Request headers
Always application/json
Always application/x-www-form-urlencoded
Bearer authentication with the access token
Request body
Amount to be refunded
Responses
Body
Payment ID
Operation result
Refund request
POST /api/payments/payment/{id}/refund HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {{YOUR-TOKEN}}
amount=10000
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"result": "FINISHED"
}Payment refund in cURL
// example of a partial or full refund of a payment on a test environment
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/refund" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer {{YOUR-TOKEN}}" \
-d 'amount=10000'Payment refund in PHP
// We assume that the $paymentId variable contains the payment ID
// API call for refund. The second parameter is the amount
$response = $gopay->refundPayment($paymentId, 10000);
// Check whether the API call was successful and extract the response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
}Payment refund in Python
# We assume that the payment_id variable contains the payment ID
# API call for refund. The second parameter is the amount
response = api.refund_payment(payment_id, 10000)
# Check whether the API call was successful and extract the response body
if response.success:
response_body = response.json{id}Payment inquiry allows you to check the status of an already created payment. It also contains information about the payment recurrence and preauthorization. The payer object may also contain information about the customer’s payment card or bank account.
Path variables
ID of the inquired payment
Request headers
Always application/json
Bearer authentication with the access token
Responses
Body
Payment ID
Order ID forwarded from the payment request
Payment state
Payment substate
Total amount in cents
Payment currency
The selected payment method
Information about the payer and payment methods
Information about the recipient
Additional parameters for the payment
Language of the gateway UI
Contains information about payment recurrence for recurring payment
Contains information about preauthorization for preauthorized payment
URL for initiating the gateway
Payment inquiry
GET /api/payments/payment/3123456789 HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"order_number": "123456",
"state": "PAID",
"payment_instrument": "PAYMENT_CARD",
"amount": 10000,
"currency": "CZK",
"payer": {
"payment_card": {
"card_number": "440507******4448",
"card_expiration": "9912",
"card_brand": "Visa",
"card_issuer_country": "CZE",
"card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)",
"card_fingerprint": "0c823534ec582c97fa85c0bf7b020ee25a0a5af13974709bb329a709a79c2b3e"
},
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": {{YOUR-GOID}}
},
"lang": "en",
"gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}Payment inquiry in cURL
// example of a payment status query on a test environment
curl -X GET "https://gw.sandbox.gopay.com/api/payments/payment/3123456789" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer {{YOUR-TOKEN}}"Payment inquiry in PHP
// We assume that the $paymentId variable contains the payment ID
// API call for payment inquiry
$response = $gopay->getStatus($paymentId);
// Check whether the API call was successful and extract the response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
// Individual response parameters can be accessed by name
$paymentStatus = $responseBody['state'];
}Payment inquiry in Python
# We assume that the payment_id variable contains the payment ID
# API call for payment inquiry
response = api.get_status(payment_id)
# Check whether the API call was successful and extract the response body
if response.success:
response_body = response.json
# Individual response parameters can be accessed by name
payment_status = response_body["state"]{id}/refundsThe refund history allows you to obtain a refund history statement for a specific payment.
Path variables
ID of the requested payment
Request headers
Always: application/json
Bearer authentication with the access token
Responses
Body
ID of the requested payment
Refund state
Refunded amount in cents
Refund currency
Date of a refund request
Date of a last refund change
GET /api/payments/payment/3123456789/refunds HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"state": "FAILED",
"amount": 50000,
"currency": "CZK",
"date_requested": "2024-04-04",
},
{
"id": 3123456789,
"state": "SUCCESS",
"amount": 20000,
"currency": "CZK",
"date_requested": "2024-04-05",
"date_last_change": "2024-04-05"
}// example of a refund request history query in a test environment
curl -X GET "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/refunds" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer {{YOUR-TOKEN}}"{id}/create-recurrence{id}/void-recurrence{id}/create-recurrenceAPI call for creating a consequent payment based on an already created recurrent payment in ON_DEMAND mode.
Path variables
Parent payment ID
Request headers
Always application/json
Always application/json
Bearer authentication with the access token
Request body
Total amount in cents
Payment currency
Order identification for the online shop, alphanumeric characters
Order description, alphanumeric characters
Individual items of the payment
Additional parameters for the payment
Responses
Body
Payment ID
Parent payment ID
Order ID forwarded from the payment request
Payment state
Total amount in cents
Měna platby
The selected payment method
Information about the payer and payment methods
Information about the recipient
Additional parameters for the payment
Language of the gateway UI
Recurrence creation
POST /api/payments/payment/3123456789/create-recurrence HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 1000,
"currency": "CZK",
"order_number": "123456",
"order_description": "Test recurrence"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456790,
"parent_id": 3123456789,
"order_number": "123456",
"state": "CREATED",
"amount": 1000,
"currency": "CZK",
"payment_instrument": "PAYMENT_CARD",
"payer": {
"contact": {
"email": "john.doe@example.com"
}
},
"target": {
"type": "ACCOUNT",
"goid": 8123456789
},
"lang": "CS"
}Recurrence creation in cURL
// example of creating a subsequent on-demand recurring payment on a test environment
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/create-recurrence" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {{YOUR-TOKEN}}" \
-d '{
"amount": 1000,
"currency": "CZK",
"order_number": "123456",
"order_description": "Test recurrence"
}'Recurrence creation in PHP
// We assume that the $parentId variable contains the parent payment ID
use GoPay\Definition\Payment\Currency;
// Array with the subsequent payment
$payment = [
'amount' => 1000,
'currency' => Currency::CZECH_CROWNS,
'order_number' => '123456',
'order_description' => 'Test recurrence'
];
// API call for subsequent payment creation
$response = $gopay->createRecurrence($parentId, $payment);
// Check whether the API call was successful and extract the response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
}Recurrence creation in Python
# We assume that the parent_id variable contains the parent payment ID
from gopay.enums import Currency
# Dictionary with the subsequent payment
payment = {
"amount": 1000,
"currency": Currency.CZECH_CROWNS,
"order_number": "123456",
"order_description": "Test recurrence",
}
# API call for subsequent payment creation
response = api.create_recurrence(parent_id, payment)
# Check whether the API call was successful and extract the response body
if response.success:
response_body = response.json{id}/void-recurrenceUsed to cancel an ongoing recurrence.
Path variables
Parent payment ID
Request headers
Always application/json
Bearer authentication with the access token
Responses
Body
Payment ID
Operation result
Recurrence void
POST /api/payments/payment/3123456789/void-recurrence HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"result": "FINISHED"
}Recurrence void in cURL
// example of cancelled recurrence on a test environment
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/void-recurrence" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer {{YOUR-TOKEN}}"Recurrence void in PHP
// We assume that the $parentId variable contains the parent payment ID
// API call for voiding a recurrence
$response = $gopay->voidRecurrence($parentId);
// Check whether the API call was successful and extract the response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
}Recurrence void in Python
# We assume that the parent_id variable contains the parent payment ID
# API call for voiding a recurrence
response = api.void_recurrence(parent_id)
# Check whether the API call was successful and extract the response body
if response.success:
response_body = response.json{id}/capture{id}/capture{id}/void-authorization{id}/captureUsed to capture the full amount of a preauthorized payment.
Path variables
ID of the preauthorized payment
Request headers
Always application/json
Bearer authentication with the access token
Responses
Body
Payment ID
Operation result
Preauthorization capture
POST /api/payments/payment/3123456789/capture HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"result": "ACCEPTED"
}Preauthorization capture in cURL
// example of capture authorized payment on a test environment
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/capture" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {{YOUR-TOKEN}}" \
-d '{
"amount": 10000,
"items": [
{
"type": "ITEM",
"name": "Test item",
"amount": 10000,
"count": 1
}
]
}'Preauthorization capture in PHP
// We assume that the $paymentId variable contains the preauthorized payment ID
// API call for preauthorization capture
$response = $gopay->captureAuthorization($paymentId);
// Check whether the API call was successful and extract the response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
}Preauthorization capture in Python
# We assume that the payment_id variable contains the preauthorized payment ID
# API call for preauthorization capture
response = api.capture_authorization(payment_id)
# Check whether the API call was successful and extract the response body
if response.success:
response_body = response.json{id}/captureUsed to capture a part of the amount of a preauthorized payment. The amount cannot be hihger than the preauthorized amount. It is important to set the Content-Type header to application/json.
Path variables
ID of the preauthorized payment
Request headers
Always application/json
Always application/json
Bearer authentication with the access token
Request body
Total amount in cents
Individual items of the payment
Responses
Body
Payment ID
Operation result
Partial preauthorization capture
POST /api/payments/payment/3123456789/capture HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"amount": 5000,
"items": [
{"type": "ITEM", "name": "Test item", "amount": 5000}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"result": "FINISHED"
}Partial preauthorization capture
// example of partial capture authorized payment on a test environment
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/capture" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {{YOUR-TOKEN}}" \
-d '{
"amount": 49900,
"items": [
{
"type": "ITEM",
"name": "Test item",
"amount": 49900,
"count": 1
}
]
}'Partial preauthorization capture in PHP
// We assume that the $paymentId variable contains the preauthorized payment ID
// Array with the details of the captured amount
$payment = [
'amount' => 5000,
'items' => [
['type' => 'ITEM', 'name' => 'Test item', 'amount' => 5000]
]
];
// API call for partial payment capture
$response = $gopay->captureAuthorizationPartial($paymentId, $payment);
// Check whether the API call was successful and extract the response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
}Partial preauthorization capture in Python
# We assume that the payment_id variable contains the preauthorized payment ID
# Dictionary with the details of the captured amount
payment = {
"amount": 5000,
"items": [
{"type": "ITEM", "name": "Test item", "amount": 5000}
]
}
# API call for partial payment capture
response = api.capture_authorization_partial(payment_id, payment)
# Check whether the API call was successful and extract the response body
if response.success:
response_body = response.json{id}/void-authorizationUsed to release preauthorized funds back to the customer’s account.
Path variables
ID of the preauthorized payment
Request headers
Always application/json
Bearer authentication with the access token
Responses
Body
Payment ID
Operations Result
Preauthorization void
POST /api/payments/payment/3123456789/void-authorization HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3123456789,
"result": "FINISHED"
}Preauthorization void in cURL
// example of voiding a preauthorized payment on a test environment
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/void-authorization" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer {{YOUR-TOKEN}}"Preauthorization void in PHP
// We assume that the $paymentId variable contains the preauthorized payment ID
// API call for preauthorization void
$response = $gopay->voidAuthorization($paymentId);
// Check whether the API call was successful and extract the response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
}Preauthorization void in Python
# We assume that the payment_id variable contains the preauthorized payment ID
# API call for preauthorization void
response = api.void_authorization(payment_id)
# Check whether the API call was successful and extract the response body
if response.success:
response_body = response.json{card_id}{card_id}{card_id}Used to get the details of a saved payment card.
Path variables
Card ID
Request headers
Always application/json
Bearer authentication with the access token
Responses
Body
Card ID
Masked tokenized PAN (virtual card)
Card expiration
Card scheme
Country of the card issuer
Card issuer
Card figerprint used to uniquely identify a card
Card token used for card token payments
The status of the saved card
Masked real PAN (physical card)
Link to a picture of the card design
Active card inquiry
GET /api/payments/cards/9876543210 HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"card_id": 9876543210,
"card_number": "440507******4448",
"card_expiration": "9912",
"card_brand": "Visa",
"card_issuer_country": "CZE",
"card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
"card_fingerprint": "0c823534ec582c97fa85c0bf7b020ee25a0a5af13974709bb329a709a79c2b3e",
"card_token": "YZ4E8f2jJA8cEDz1s0lO4BMXo6skkvItJddyrLhSyPa01T/cvrl+DwKsEqehFG7SQxJZUsBcgZ6sei4AKxrHHap7BofFr+SH3oHJyta0axiBB7MST3IWqrsq5ZtfukBrgwPBocNDPd/RnQs=",
"status": "ACTIVE",
"real_masked_pan": "481747******1733",
"card_art_url": "https://gopay.com/api/payments/card-art/Mjc5MTg5ODI0MzIz"
}Deleted card inquiry
GET /api/payments/cards/9876543210 HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"card_id": 9876543210,
"status": "DELETED"
}Card details in cURL
// example with card details query on test environment
curl -X GET "https://gw.sandbox.gopay.com/api/payments/cards/9876543210" \
-H "Accept: application/json" \
-H "Authorization: Bearer {{YOUR-TOKEN}}"Card details in PHP
// We assume that the $cardId variable contains the card ID
// API call for getting card details
$response = $gopay->getCardDetails($cardId);
// Check whether the API call was successful and extract the response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
// Individual response parameters can be accessed by name
$cardStatus = $responseBody['status'];
}Card details in Python
# We assume that the card_id variable contains the card ID
# API call for getting card details
response = api.get_card_details(card_id)
# Check whether the API call was successful and extract the response body
if response.success:
response_body = response.json
# Individual response parameters can be accessed by name
card_status = response_body["status"]{card_id}Used to delete a previously saved card.
Path variables
Card ID
Request headers
Bearer authentication with the access token
Responses
Card deletion
DELETE /api/payments/cards/9876543210 HTTP/1.1
Authorization: Bearer {{YOUR-TOKEN}}
HTTP/1.1 204 No ContentCard deletion in cURL
// example of deleting a card on a test environment
curl -X DELETE "https://gw.sandbox.gopay.com/api/payments/cards/987654321" \
-H "Authorization: Bearer {{YOUR-TOKEN}}"
// confirmation will not be returned, you can check the status by retrieving the card details - see example response:
{"card_id":987654321,"status":"DELETED"}Card deletion in PHP
// Předpokládáme, že v proměnné $cardId máte uložené ID karty
// API call pro dotaz na stav platby
$response = $gopay->deleteCard($cardId);Card deletion in Python
# Předpokládáme, že v proměnné card_id máte uložené ID karty
# API call pro smazání karty
response = api.delete_card(card_id){goid}/payment-instruments/{currency}{goid}/payment-instruments{goid}/payment-instruments/{currency}Returns the list of all enabled payment method for a specific currency, their names and logos. For bank tranfers, names and logos of individual banks are listed.
Path variables
GoID of the shop
Currency to check for payment methods
Request headers
Always application/json
Bearer authentication with the access token
Responses
Body
Description of payment method groups
List of enabled payment methods for a currency
Allowed payment methods inquiry
GET /api/eshops/eshop/{{YOUR-GOID}}/payment-instruments/CZK HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}Allowed payment methods inquiry in cURL
// example of a query for a list of allowed methods for a CZK account to GoID for a test environment
curl -X GET "https://gw.sandbox.gopay.com/api/eshops/eshop/{{YOUR-GOID}}/payment-instruments/CZK" \
-H "Accept: application/json" \
-H "Authorization: Bearer {{YOUR-TOKEN}}"Allowed payment methods inquiry in PHP
// We assume that the $goid variable contains your GoID
use GoPay\Definition\Payment\Currency;
// API call for getting allowed payment methods, second parameter is the currency
$response = $gopay->getPaymentInstruments($goid, Currency::CZECH_CROWNS);
// Check whether the API call was successful and extract the response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
// Get an array of allowed payment methods
$instruments = array_map(
fn ($el) => $el['paymentInstrument'],
$responseBody['enabledPaymentInstruments']
);
}Allowed payment methods inquiry in Python
# We assume that the $goid variable contains your GoID
from gopay.enums import Currency
# API call for getting allowed payment methods, second parameter is the currency
response = api.get_payment_instruments(goid, Currency.CZECH_CROWNS)
# Check whether the API call was successful and extract the response body
if response.success:
response_body = response.json
# Get a list of allowed payment methods
payment_instruments = [
el["paymentInstrument"]
for el in response_body["enabledPaymentInstruments"]
]{goid}/payment-instrumentsReturns the list of all enabled payment method on a shop, their names and logos. For bank tranfers, names and logos of individual banks are listed.
Path variables
GoID of the shop
Request headers
Always application/json
Bearer authentication with the access token
Responses
Body
Description of payment method groups
Object containing enabled payment methods
Represents an individual enabled payment method. The object keys are values from the Payment instrument enum.
All allowed payment methods inquiry
GET /api/eshops/eshop/{{YOUR-GOID}}/payment-instruments HTTP/1.1
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}All allowed payment methods inquiry in cURL
// example query for a list of all allowed payment methods for the selected GoID for the test environment
curl -X GET "https://gw.sandbox.gopay.com/api/eshops/eshop/{{YOUR-GOID}}/payment-instruments" \
-H "Accept: application/json" \
-H "Authorization: Bearer {{YOUR-TOKEN}}"All allowed payment methods inquiry in PHP
// example query for a list of all allowed payment methods for the selected GoID for the test environment
$response = $gopay->getPaymentInstrumentsALL('8123456789');
// checking if the API call was successful and getting the API response body
if ($response->hasSucceed()) {
$responseBody = $response->json;
echo json_encode($responseBody);
}Used to generate an account statement for a GoPay business account. The response body is the file of the specified format.
Request headers
Always application/json
Always application/json
Bearer authentication with the access token
Request body
Start date of the statement
End date of the statement
GoID of the online shop
Currency of the account
Format of the statement
Responses
The reponse body contains the specified file as application/octet-stream
Account statement
POST /api/accounts/account-statement HTTP/1.1
Accept: application/octet-stream
Content-Type: application/json
Authorization: Bearer {{YOUR-TOKEN}}
{
"date_from": "2022-12-01",
"date_to": "2022-12-02",
"goid": {{YOUR-GOID}},
"currency": "CZK",
"format": "CSV_A"
}
HTTP/1.1 200 OK
Content-Type: application/octet-stream
"ID pohybu";"Datum";"Typ";"Protistrana";"ID objednávky/VS";"Částka";"Počáteční stav";"Koncový stav";"Měna";"ID Referenčního pohybu"
...Account statement in cURL
// example of CSV_A statement for CZK account on test environment
curl -X POST "https://gw.sandbox.gopay.com/api/accounts/account-statement" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {{YOUR-TOKEN}}" \
-d '{
"date_from": "2022-12-01",
"date_to": "2022-12-02",
"goid": {{YOUR-GOID}},
"currency": "CZK",
"format": "CSV_A"
}'Account statement in PHP
// We assume that the $goid variable contains your GoID
use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Account\StatementGeneratingFormat;
// Array with the request body
$body = [
'date_from' => '2022-12-01',
'date_to' => '2022-12-02',
'currency' => Currency::CZECH_CROWNS,
'format' => StatementGeneratingFormat::CSV_A,
'goid' => $goid
];
// API call for getting the account statement
$response = $gopay->getAccountStatement($body);
// Check whether the API call was successful
if ($response->hasSucceed()) {
// Extract the content of the response
$data = $response->__toString();
$file = 'statement.csv';
// Create the file
file_put_contents($file, $data);
}Account statement in Python
# We assume that the goid variable contains your GoID
from gopay.enums import Currency, StatementGeneratingFormat
# Dictionary with the request body
request_body = {
"date_from": "2022-12-01",
"date_to": "2022-12-02",
"currency": Currency.CZECH_CROWNS,
"format": StatementGeneratingFormat.CSV_A,
"goid": goid,
}
# API call for getting the account statement
response = api.get_account_statement(request_body)
# Check whether the API call was successful and decode the content
if response.success:
statement = response.raw_body.decode("utf-8")Information about the payment recipient
Always ACCOUNT
Unique identifier of the online shop in GoPay’s system
{
"type": "ACCOUNT",
"goid": 8123456789
}An individual item of the order
Item type
Item name, alphanumeric characters
Total amount in cents (for the specified count)
Count
VAT rate
EAN code of the product
URL address of the product
Minimal item object
{
"type": "ITEM",
"name": "Test item",
"amount": 1000
}Full item object
{
"type": "ITEM",
"name": "Test item",
"amount": 1000,
"count": 1,
"vat_rate": 21,
"ean": 4006381333931,
"product_url": "https://example.com/product"
}Information about the customer
Customer’s first name
Customer’s last name
Cusomer’s email
Customer’s phone number including country code
Address - city
Address - street
Address - ZIP code
County code in respect to ISO 3166-1 alpha-3
Minimal contact object
{
"email": "john.doe@example.com"
}Full contact object
{
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone_number": "+420123456789",
"city": "Test city",
"street": "Test street 10",
"postal_code": "10000",
"country_code": "CZE"
}Describes information about the customer and sets the payment methods. Also used for specific payments like Card token payment and Bank account token payment
Information about the customer
Array of allowed payment methods
["PAYMENT_CARD", "BANK_ACCOUNT", "GPAY", "APPLE_PAY"]A pre-selected payment method
Array of allowed SWIFTs for bank transfers
["GIBACZPX", "CEKOCZPP", "FIOBCZPP", "AGBACZPP", "AIRACZPP"]A pre-selected SWIFT
Allowed types of BNPL-style payment (Buy Now Pay Later) (developer preview)
["DEFERRED_PAYMENT", "PAY_IN_THREE"]Pre-selected type of BNPL-stype payment (Buy Now Pay Later) (developer preview)
Information about customer’s bank account
Information about customer’s payment card
Requests the customer’s payment card to be saved
ID of a card that was saved
Token of a saved card for card token payment
Email of a used GoPay wallet (only relevant to the GOPAY payment method)
Minimal payer object required for creating a payment
{
"contact": {
"email": "john.doe@example.com"
}
}Full possible payer object
{
"allowed_payment_instruments": ["PAYMENT_CARD", "BANK_ACCOUNT", "GPAY", "APPLE_PAY"],
"default_payment_instrument": "PAYMENT_CARD",
"allowed_swifts": ["GIBACZPX", "CEKOCZPP", "FIOBCZPP", "AGBACZPP", "AIRACZPP"]],
"default_swift": "GIBACZPX",
"contact": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone_number": "+420123456789",
"city": "Test city",
"street": "Test street 10",
"postal_code": "10000",
"country_code": "CZE"
}
}Payer object in payment inqury response for a card payment
{
"contact": {
"email": "john.doe@example.com"
},
"payment_card": {
"card_number": "440507******4448",
"card_expiration": "9912",
"card_brand": "Visa",
"card_issuer_country": "CZE",
"card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
}
}Payer object in payment inqury response for a bank account payment
{
"contact": {
"email": "john.doe@example.com"
},
"bank_account": {
"prefix": "000000",
"account_number": "9878039",
"bank_code": "2010",
"iban": "CZ5120100000000009878039",
"bic": "FIOBCZPP",
"account_name": "John Doe"
}
}Used to send URLs to which the HTTP notification will be sent and where the customer will be redirected. The payment ID is appended as a query parameter.
URL used to redirect the customer from the gateway back to the shop
URL used to deliver the HTTP notification
{
"return_url": "https://example.com/your-return-url",
"notification_url": "https://example.com/your-notify-url"
}Information about a payment card - read-only. It is part of the response to payment inquiry. The card_fingerprint is present only if this feature is enabled on your online shop.
Masked PAN
Card expiration
Card scheme
Country of the card issuer
Card issuer
Result of the 3DS authentication
Card figerprint used to uniquely identify a card
{
"card_number": "440507******4448",
"card_expiration": "9912",
"card_brand": "Visa",
"card_issuer_country": "CZE",
"card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
}
Information about the customer’s bank account. It is part of the response to payment inquiry if the payment was made by bank transfer. Also used for Bank account token payment.
Bank account prefix (CZ format)
Bank account number (CZ format)
Bank code (CZ format)
IBAN
SWIFT/BIC
Account holder name
Account token for PSD2 remember mode
{
"prefix": "000000",
"account_number": "9878039",
"bank_code": "2010",
"account_name": "John Doe",
"iban": "CZ5120100000000009878039"
}
Additional payment parameters
Název parametru
Hodnota parametru
{
"name": "Test name",
"value": "Test value"
}Describes payment recurrence. When used with an ON_DEMAND payment, the recurrence_period parameter is omitted. The recurrence_state parameter is returned in the payment inquiry.
Payment recurrence cycle
Payment recurrence period
Exclusive date to which the payment recurrence will be active, YYYY-MM-DD
Payment recurrence state
Recurrence object for an automatic recurrent payment
{
"recurrence_cycle": "MONTH",
"recurrence_period": 1,
"recurrence_date_to": "2025-12-31",
}Recurrence object for an on-demand recurrent payment
{
"recurrence_cycle": "ON_DEMAND",
"recurrence_period": 12,
"recurrence_date_to": "2025-12-31"
}Recurrence object from a payment inquiry
{
"recurrence_cycle": "WEEK",
"recurrence_period": 1,
"recurrence_date_to": "2025-12-31",
"recurrence_state": "STOPPED"
}Describes preauthorization. Only returned in a payment inquiry
Whether preauthorization was requested for this payment
Preauthorization state
{
"requested": true,
"state": "REQUESTED"
}Describes API errors
Whether the error ties to a specific field
What field does the error concern
Localized message based on the Accept-Language header
Technical description
Numeric error code
Error name
Error in a specific field
{
"scope": "F",
"field": "goid",
"message": "Payee not found",
"error_code": "320",
"error_name": "PAYEE_NOT_FOUND"
}Global error
{
"scope": "G",
"description": "System error",
"error_code": "100",
"error_name": "SYSTEM_ERROR"
}Contains descriptions of payment method groups.
Payment method group label
Czech payment method group description
{
"label": {
"cs": "Platební karta"
}
}List of all enabled payment method groups
Name of the payment method group. Keys come from the Group enum.
{
"card-payment": {
"label": {
"cs": "Platební karta"
}
}
}Enabled swift for bank transfers
Payment method icons
Large icon URL
Small icon URL
Whether an online transfer is available for this swift
Payment method label
Czech label
Bank SWIFT
{
"image": {
"large": "https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png",
"normal": "https://gate.gopay.cz/images/checkout/GIBACZPX.png"
},
"isOnline": true,
"label": {
"cs": "Platba 24"
},
"swift": "GIBACZPX"
}Describes an enabled payment method.
Array of enabled SWIFTs for bank transfers
Group of the payment method
Payment method icons
Large icon URL
Small icon URL
Payment method labels
Czech label
API code of the payment method
{
"enabledSwifts": [{
"image": {
"large": "https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png",
"normal": "https://gate.gopay.cz/images/checkout/GIBACZPX.png"
},
"isOnline": true,
"label": {
"cs": "Platba 24"
},
"swift": "GIBACZPX"
}],
"group": "bank-transfer",
"image": {
"large": "https://gate.gopay.cz/images/checkout/payment_card@2x.png",
"normal": "https://gate.gopay.cz/images/checkout/payment_card.png"
},
"label": {
"cs": "Bankovní převod"
},
"paymentInstrument": "BANK_ACCOUNT"
}Enabled swift for bank transfers with currency listings.
Payment method icons
Large icon URL
Small icon URL
Whether an online transfer is available for this swift
Payment method label
Czech label
Bank SWIFT
Currency for which the SWIFT is available. Keys come from the Currency enum.
Whether an online transfer is available for this swift for this currency
{
"image": {
"large": "https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png",
"normal": "https://gate.gopay.cz/images/checkout/GIBACZPX.png"
},
"isOnline": true,
"label": {
"cs": "Platba 24"
},
"swift": "GIBACZPX",
"currencies": {
"CZK": {
"isOnline": "true"
}
}
}Describes an enabled payment method with currency listings.
Array of enabled SWIFTs for bank transfers
Object for each swift. Keys come from the SWIFT enum.
Group of the payment method
Payment method icons
Large icon URL
Small icon URL
Payment method labels
Czech label
Currencies for which the payment method is available
{
"enabledSwifts": {
"GIBACZPX": {
"image": {
"large": "https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png",
"normal": "https://gate.gopay.cz/images/checkout/GIBACZPX.png"
},
"isOnline": true,
"label": {
"cs": "Platba 24"
},
"swift": "GIBACZPX",
"currencies": {
"CZK": {
"isOnline": "true"
}
}
}
},
"group": "bank-transfer",
"image": {
"large": "https://gate.gopay.cz/images/checkout/bank_account@2x.png",
"normal": "https://gate.gopay.cz/images/checkout/bank_account.png"
},
"label": {
"cs": "Bankovní platba"
},
"currencies": [
"CZK"
]
}List of available currencies
Czech koruna
Euro
Polish złoty
US dolar
Pound sterling
Hungarian foring
Romanian leu
Bulgarian lev
List of available payment instruments.
Payment card
Bank account transfer
Google Pay
Apple Pay
PayPal
mPlatba (mobile payment)
Premium SMS
PaySafeCard coupon
Bitcoin wallet
Click To Pay VISA/MasterCard
Twisto (developer preview)
Skip Pay (developer preview)
List of SWIFTs for payment method selection.
QR Platba
Česká Spořitelna
Komerční Banka
ČSOB
Raiffeisenbank
UniCredit Bank
Moneta Money Bank
FIO Banka
mBank
AirBank
ING Bank
Oberbank
VÚB Praha
Hello bank!
CREDITAS
Max banka
J&T Banka
Tatra Banka
Všeobecná Úverová Banka
UniCredit Bank SK
Slovenská Sporiteľňa
ČSOB SK
Poštová Banka
OTP Banka Slovensko
Prima Banka Slovensko
Citibank Europe
Fio banka SK
mBank SK
ING Bank SK
J&T Banka SK
Oberbank SK
Privatbanka
BKS Bank
Raiffeisenbanka SK
Komerční banka SK
List of possible payment statuses
Created payment
Successful payment
Declined payment
Pending payment
Expired payment
Preauthorized payment
Refunded payment
Partially refunded payment
List of payment substates
Waiting for an online bank transfer to be completed
Waiting for an offline transfer to be finished
Bank transfer confirmed by advice
Bank tranfer confirmed by statement
Bank transfer not completed
Approved with zero amount
Declined by issuer - limit reached
Declined by issuer - problem at issuer’s side
Declined by issuer - payment card error
Declined by issuer - card blocked
Declined by issuer - insufficient funds
Declined by issuer - card expired
Declined by issuer - invalid CVV
Declined in the 3DS server
Declined in the 3DS server
Declined in the 3DS server
Declined in the 3DS server
Declined in the 3DS server
Declined in the 3DS server
Declined in the 3DS server
Declined by issuer - payment card error
Declined by issuer - payment card error
Declined by issuer - account error
Declined by issuer - account error
Declined by issuer - technical issues
Declined by issuer - wrong card number
Declined by issuer - payment not allowed
Unknown configuration
Declined by issuer - limit reached
Could not reach authorization centre
Payment not completed
Payment not completed
Payment not completed.
Payment not completed. Reason was shown to customer.
Payment not completed. Sum of credited amounts exceeded total amount.
Platba nebyla provedena. Uživatel není oprávněn k provedení operace.
Payment not completed. Customer is not authorized to perform transaction.
Payment not completed yet.
Payment not completed. Duplicate payment.
Technical error on issuer’s side.
Unable to deliver SMS.
Unsupported payment card region.
Cardholder canceled the payment.
Declined by issuer - card blocked
Duplicate transaction reversal
Duplicate transaction
Bank account payment declined
Payment canceled by customer
SMS was sent but not delivered yet.
Payment is being processed in the Bitcoin network.
Payment was not paid in full.
Payment made after expiration.
Customer has not given PSD2 consent.
PSD2 payment declined
PSD2 requested account not found
State of a saved payment card
Saved card is active
Saved card is deleted
Order item type
Product or service
Shipping
Discount
Token permission scope
Only allows creating payments
Allows all operations
Language of payment gateway UI
Czech
Slovak
English
German
Russian
French
Hungarian
Polish
Romanian
Bulgarian
Croatian
Italian
Spanish
Ukrainian
Estonian
Lithuanian
Latvian
Slovenian
Portuguese
Operation result
Operation accepted for asynchronous processing
Operations finished successfully
Operation failed
Recurrence payment cycle
Repeat every X days
Repeat every X weeks
Repeat every X months
On-demand recurrence
State of payment recurrence
Requested, waiting for initial payment authorization
Recurrence active
Recurrence stopped
List of possible refund statuses
Successful refund
Declined refund
Requested refund
Payment preauthorization state
Preauthoriazation requested, waiting for payment authorization
Authorized, amount was blocked
Amount was captured
Preauthorization canceled, funds released
Statement format. For details, see Account movements statements settings
Result of 3DS authentication
Card doesn’t support 3DS
Full 3DS authentication
Partial 3DS authentication
3DS authentication not performed
Payment method groups
Card payments
Bank transfer payments
Electronic wallets
Other methods
Error scope
Error in a specific field
Non-field error
Numeric error code, marks reason of the error
System error
Mandatory
Wrong format
Aleady exists
Unable to modify
Unable to delete
Ambiguous
Invalid request
Unauthorized access
Unsupported method of permission assignment
Wrong credentials
PIN access disabled
Unable to create payment
Unable to perform payment
Wrong paymen state
Payment not found
Shop inactive
Recipient cannot receive payment
Unable to refund payment
Unable to refund payment
Wrong amount
Insufficient funds
Payment recurrence failed
Payment recurrence unsupported
Opakování platby zastaveno
Time limit for recurrent payment expired
Recurring payments are not enabled
Payment capture failed
Payment was already captured
Preauthorization void failed
Preauthorization voided
Sum of individual item amounts does not equal total payment amount
PSD2 account token invalid
Account not found
Card token not valid
Card token wrong payment instrument
Card token not enabled
Merchant COF Card not found
Represents the types of BNPL (Buy Now Pay Later) payment types.
Customer pays the full amount later
The payment gets split into three parts
Current API
Always use the current API, the specification is available in this documentation. In case of using a library, use the current version from our GitHub. If there is a missing functionality in the SDK, contact integrace@gopay.cz.
TLS
E-commerce sites must use a connection secured via HTTPS, with the TLS version being 1.2 or higher.
Referer Header
Customers must be redirected to the payment gateway directly from the domain of the e-commerce site. That is, the Referer header must carry the registered domain of the e-shop.
If this is not possible and the customer is redirected from a solution domain, each e-shop must have a unique domain that will be passed.
Preferably using subdomains - e.g., first-eshop.platform.com, second-eshop.platform.com, etc.
Paths after the slash are not passed with the default Referrer-Policy, which is strict-origin-when-cross-origin. When transitioning to the gateway from the address platform.com/first-eshop, only platform.com would be passed.
Correct Credential Names
In the administration interface, always display the credential names used by GoPay - i.e., Client ID, Client Secret, and GoID. Do not use other names.
Credential Verification
As soon as the merchant attempts to save the credentials, verify their correctness:
Client ID and Client Secret - verify by creating a token, see Obtaining the access token.
- If the token creation fails, inform the user that these credentials are invalid.
GoID - subsequently verify by querying the payment methods, see Available payment methods
- If the API call fails, inform the user that the GoID is invalid.
Test Mode (Optional)
In the administration, allow the selection of a test mode. If the user opts for this, all API communications from the e-shop will be directed to the sandbox URL.
Verify sandbox credentials in the same way as live credentials, but against the sandbox URL.
Query for available payment methods
When displaying the checkout, call the endpoint to obtain the allowed payment methods for the given e-shop and currency, see Available payment methods. Make the query only once.
Names and logos of payment methods
Display the names of payment methods in the language of the e-shop - in the API call above, use the lang query parameter. For example, a call to /api/eshops/eshop/{GOID}/payment-instruments?lang=en will return the names of the methods in English.
Links to the logos of the payment methods are also part of the API call, and please use these logos.
Presentation of payment methods
In the checkout, display all available payment methods and let the customer choose from them. Do not offer only one option (e.g., payment via GoPay).
For bank transfers, you can either display each bank separately or just one bank transfer option (names and logos of individual banks and the payment method are in the API response as mentioned above).
Apple Pay
Display the Apple Pay payment option in the cart only if it is available to the customer. This can be verified using JavaScript, see Apple Pay integration.
If the JavaScript check fails, hide the payment method in the cart.
Payment Instruments
When creating a payment, submit the chosen payment method. This can be done in two versions.
- In the
allowed_payment_instrumentsarray - if you submit only one payment method in this array, it will be the only one available at the gateway, and the customer will not be able to change it. - In the
default_payment_instrumentfield - the chosen payment method will be displayed to the customer, but the customer will be able to change it to another available one.
We recommend the second option, which allows the customer to change the payment method.
More information and examples are available in the section Choosing payment methods.
If you display individual banks in the checkout, implement the same for SWIFTs, see Choosing banks.
Customer Contact Details
Submit all collected customer information in the contact object. This, among other things, can lead to a lower occurrence of 3DS verification. More information in the section Contact.
Language Submission
Submit the language of the e-shop in the lang parameter in the payment creation request, so that the payment gateway is also displayed in the same language. Available languages are listed in the section Lang. If the language is not available, do not submit the parameter.
Payment Status Queries
Whenever a notification about a change in payment status is received (see Receiving the HTTP notification), make an API call to inquire about the payment status. If necessary, update the status in your order system.
When returning to the e-shop through the redirect URL (see Returning to merchant website), also inquire about the payment status and update it. Also display the payment status to the customer with corresponding information (see below).
Processing Payment Status
Upon return from the gateway, display the corresponding information to the customer and, if necessary, offer to create a new payment.
| Status | Description | New Payment |
|---|---|---|
| PAYMENT_METHOD_CHOSEN | The customer attempted a payment, and the result is not yet known. Inform the customer that the payment result is pending. You will be notified about the payment status via HTTP notification. | NO |
| PAID | The payment was successfully made. Inform the customer and proceed with the order processing. | NO |
| CANCELED | The payment was declined. Inform the customer. | YES |
| TIMEOUTED | The time limit for completing the payment has expired. Inform the customer that the payment was unsuccessful. The same logic as CANCELED can be used. | YES |
| CREATED | The customer did not attempt to make the payment and returned to the e-shop. Inform the customer that the payment was unsuccessful. The same logic as CANCELED can be used. | YES |
| AUTHORIZED | Only if you offer pre-authorized payments. The payment was authorized and is waiting to be captured by the merchant. Inform the customer of the successful authorization. | NO |
More information about payment statuses is available in the section Payment states and expiration.
Creating a New Payment
If the payment was unsuccessful upon the customer’s return, allow for a new payment to be made. Allow the customer to change the payment method and then create a new payment. This applies to statuses where New Payment is marked as YES in the table above.