GoPay technical documentation

GoPay technical documentation

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.

GoPay REST API

The documentation contains two parts - integration guide and API reference. You can also use one of our SDKs:

PHP

Python

.NET (C#)

Java

git clone https://github.com/gopaycommunity/gopay-java-api.git
cd gopay-java-api
mvn package
API

API Endpoints

Sandbox enviroment - https://gw.sandbox.gopay.com/api
Production enviroment - https://gate.gopay.cz/api
Authentication

The 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
Lifecycle of a payment

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
Creating a payment

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_url parameter, 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.

Initiating the gateway

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 on gate.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

Selecting the payment method

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.

Finishing the payment

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 (or AUTHORIZED if 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.

Returning to merchant website

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 payment
  • parent_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.

Receiving the HTTP notification

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 payment
  • parent_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).

Payment states and expiration

The payment can be in one of these states:

  • CREATED - payment created
  • PAYMENT_METHOD_CHOSEN - awaiting the result of the payment
  • TIMEOUTED - the payment is expired
  • PAID - the payment was paid
  • CANCELED - the payment was declined
  • AUTHORIZED - a preauthorized payment was authorized
  • PARTIALLY_REFUNDED - a part of the payment amount was refunded
  • REFUNDED - 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
Payments

This section describes the types of payments provided. Standard payments are available for all payment methods. Other kinds of payments are only available for payment cards (including Apple Pay and Google Pay).

Standard payment

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.

Standard payment creation

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

HTTP

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/..."
}
Recurring payment

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 changed
  • ON_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.

Automatically recurring payment

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_cycle sets the cycle, meaning that the charge will be carried out each Nth day, week or month. The possible values are specified in Recurrence cycle
  • recurrence_period sets the period (not frequency) of the recurrence, meaning how many days, weeks or months are there between two consequent charges
  • recurrence_date_to sets 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_cycle to MONTH and the recurrence_period to 12. 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.

HTTP

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/..."
}
On-demand recurring payment

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 to ON_DEMAND
  • recurrence_date_to sets 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 payment
Subsequent payment

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/..."
}
Voiding a recurring payment

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_to comes
  • 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

HTTP

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"
}
Recurring payment inquiry

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.

HTTP

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

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.

Preauthorized payment creation

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.

Request

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/..."
}
Preauthorized payment capture

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 amount parameter. 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

Capture
Partial capture

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"
}
Voiding a preauthorization

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

HTTP

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"
}
Zero amount authorization

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!

HTTP

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/..."
}
Card fingerprint

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

Card token payment

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_token parameter set to true
  • After the customer finishes the payment, inquire the payment details
  • Extract the value of card_id from the response
  • Inquire the payment card
  • Extract the value of card_token from the response
Card token creation

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.

Payment creation
Payment inquiry

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/...",
}
Acquiring card details

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_fingerprint which you can use to verify if this card has already been saved
  • card_token which 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.

Active card
Deleted card

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"
}
Payment with a card token

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).

HTTP

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/..."
}
Deleting a card

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.

HTTP

Deletion of a saved card

DELETE /api/payments/cards/987654321 HTTP/1.1

Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 204 No Content
Payment card notifications

In 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.

Bank account token payment

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.

Payment with account token request

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 the BANK_ACCOUNT value in the array
  • allowed_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 the BANK_ACCOUNT value in the array
  • allowed_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
Without account data
Czech format
International format

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/..."
}
Acquiring the account token

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.

HTTP

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/...",
}
Payment with an account token

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.

HTTP

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/..."
}
Payment gateway
Setting the payment methods

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 gateway
  • default_payment_instrument - used to pre-select one specific payment method
  • allowed_swifts - SWIFT codes of banks that can be used to pay
  • default_swift - a pre-selected bank
Choosing payment methods

Allowed payment methods

  • Case 1: The allowed_payment_instruments array 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 methods 1
Allowed methods 2
Allowed methods 3
Pre-selected method 1
Pre-selected method 2

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"
    }
}
Choosing banks

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. This only affects online transfers.

  • Case 1: If the allowed_swifts field is omitted, the customer will have the option to use any bank, including offline transfers, to complete their payment.
  • Case 2: If one or more SWIFT codes are included in the allowed_swifts array, offline transfers will not be available. Only the banks with online transfers enabled that were specified in the allowed_swifts array will be accessible.
  • Case 3: If only one SWIFT code is included in the allowed_swifts array, and BANK_ACCOUNT is the sole entry in the allowed_payment_instruments array, 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. This works for both offline and online transfers. The pre-selected bank will be elevated to the top of the available banks list and will be highlighted for easy identification.

Apple Pay integration

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:

You can find all downloadable logos in our article, Which Logos and Names of the Payment Methods Should I Prefer?

Apple Pay availability
Apple Pay button

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>
Payment gateway initiation

In order to initiate the payment gateway, you need the gw_url from the API response to succesful payment creation request.

Redirect

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:

  1. Using a link
  2. Using an HTTP redirection
  3. 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_url embedded (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_url as the Location header.
  • The customer’s browser automatically redirects the customer.

Description of using JavaScript:

  • An event listener is attached to the form, listening for the submit event. 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.

Link
HTTP Redirection
JavaScript

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>
Inline

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:

  1. Using a form
  2. 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_url is placed as the action attribute of another HTML form. This can be done using PHP or a template system, for example. Use https://gw.sandbox.gopay.com/gp-gw/js/embed.js for sandbox or https://gate.gopay.cz/gp-gw/js/embed.js for production.
  • The method should be set to POST, the id attribute should be gopay-payment-button, and a script tag 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.js for sandbox or https://gate.gopay.cz/gp-gw/js/embed.js for production).
  • An event listener is attached to the form, listening for the submit event. 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_url is passed in the gatewayUrl field while true is passed as the inline field (see the example).

We omit exception handling in the examples for the sake of simplicity. In a production environment, the developer should manage this.

Form
JavaScript

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>
Android and iOS

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.

Return to merchant website

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.

Return using a redirect

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.

Return using a callback function

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.

Callback only
Callback with payment creation

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>
Processing the state of the payment

When the customer returns to the online shop, you can interpret the state of the payment to understand one of four possible scenarios:

  1. The payment was successful (PAID or AUTHORIZED state)
  2. The payment failed (CANCELED or TIMEOUTED state)
  3. There was no attempt to complete the payment (CREATED state)
  4. We’re still awaiting the payment result (PAYMENT_METHOD_CHOSEN state)

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.

API Reference
API Operations
Authentication
POST /api/oauth2/token
Obtaining the access token
POST /api/oauth2/token

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

Accept
string required

Always application/json

Example:
application/json
Content-Type
string required

Always application/x-www-form-urlencoded

Example:
application/x-www-form-urlencoded
Authorization
string required

Basic HTTP auth

Example:
Basic MTA2MTM5OTE2MzpzdERUbVZYRg==

Request body

application/x-www-form-urlencoded
Object
scope

Token permission scope

Example:
payment-create
grant_type
string

Always client_credentials

Example:
client_credentials

Responses

200 OK
Body
Object
token_type
string

Always bearer

Example:
bearer
access_token
string

The access token

Example:
AAAnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p
refresh_token
string

Not currently in use

Example:
xzZnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p
expires_in
integer

Token expiration in seconds

Example:
1800
HTTP
cURL
PHP
Python
.NET
Java

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 reused

GoPay 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 reused

GoPay 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}}); 
Payments
POST /api/payments/payment
POST /api/payments/payment/{id}/refund
GET /api/payments/payment/{id}
GET /api/payments/payment/{id}/refunds
Payment creation
POST /api/payments/payment

Payment creation. Using the recurrence and preauthorization parameters, the payment can be specified as recurring or preauthorized respectively.

Request headers

Authorization
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}
Content-Type
string required

Always application/json

Example:
application/json
Accept
string required

Always application/json

Example:
application/json

Request body

Object
amount
integer required

Total amount in cents

Example:
1000
currency
Currency required

Payment currency

Example:
CZK
order_number
string required

Order identification for the online shop, alphanumeric characters

Max length: 128
Example:
123456
target
Target required

Information about the recipient

payer
Payer required

Information about the payer and payment methods

callback
Callback required

Return and notification URLs

order_description
string

Order description, alphanumeric characters

Max length: 256
Example:
Test order
preauthorization
boolean

Set to true for preauthorized payments

Example:
false
recurrence

Contains information about payment recurrence for recurring payment

items
Array of Item

Individual items of the payment

additional_params

Additional parameters for the payment

Max items: 4
lang

Language of the gateway UI

Example:
CS

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006529
order_number
string

Order ID forwarded from the payment request

Example:
OBJ20200825
state

Payment state

Example:
CREATED
amount
integer

Total amount in cents

Example:
139950
currency

Payment currency

Example:
CZK
payer

Information about the payer and payment methods

target

Information about the recipient

additional_params

Additional parameters for the payment

lang

Language of the gateway UI

Example:
CS
recurrence

Contains information about payment recurrence for recurring payment

preauthorization

Contains information about preauthorization for preauthorized payment

gw_url
string

URL for initiating the gateway

Example:
https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF
HTTP - minimal
HTTP - full
cURL
PHP
Python
.NET

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);
}
Payment refund
POST /api/payments/payment/{id}/refund

Payment refund returns the funds of an already completed payment back to the customer. It can be either partial or full.

Path variables

id
string required

ID of the payment to be refunded

Request headers

Accept
string required

Always application/json

Example:
application/json
Content-Type
string required

Always application/x-www-form-urlencoded

Example:
application/x-www-form-urlencoded
Authorization
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Request body

application/x-www-form-urlencoded
Object
amount
integer

Amount to be refunded

Example:
10000

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3123456789
result

Operation result

Example:
FINISHED
HTTP
cURL
PHP
Python

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
Payment inquiry
GET /api/payments/payment/{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
string required

ID of the inquired payment

Request headers

Accept
string required

Always application/json

Example:
application/json
Authorization
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3123456789
order_number
string

Order ID forwarded from the payment request

Example:
123456
state

Payment state

Example:
PAID
sub_state

Payment substate

Example:
_3001
amount
integer

Total amount in cents

Example:
1000
currency

Payment currency

Example:
CZK
payment_instrument

The selected payment method

Example:
PAYMENT_CARD
payer

Information about the payer and payment methods

target

Information about the recipient

additional_params

Additional parameters for the payment

lang

Language of the gateway UI

Example:
CS
recurrence

Contains information about payment recurrence for recurring payment

preauthorization

Contains information about preauthorization for preauthorized payment

gw_url
string

URL for initiating the gateway

Example:
https://gw.sandbox.gopay.com/gw/v3/...
HTTP
cURL
PHP
Python

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"]
History of refunds
GET /api/payments/payment/{id}/refunds

The refund history allows you to obtain a refund history statement for a specific payment.

Path variables

id
string required

ID of the requested payment

Request headers

Accept
string required

Always: application/json

Example:
application/json
Authorisation
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
id
integer

ID of the requested payment

Example:
3123456789

Refund state

Example:
SUCCESS
amount
integer

Refunded amount in cents

Example:
1000
currency

Refund currency

Example:
CZK
date_requested
string date

Date of a refund request

Example:
2024-04-04
date_last_change
string date

Date of a last refund change

Example:
2024-04-04
HTTP
cURL
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}}"
Recurring payments
POST /api/payments/payment/{id}/create-recurrence
POST /api/payments/payment/{id}/void-recurrence
Creating a recurrence
POST /api/payments/payment/{id}/create-recurrence

API call for creating a consequent payment based on an already created recurrent payment in ON_DEMAND mode.

Path variables

id
string required

Parent payment ID

Request headers

Accept
string required

Always application/json

Example:
application/json
Content-Type
string required

Always application/json

Example:
application/json
Authorization
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Request body

Object
amount
integer required

Total amount in cents

Example:
1000
currency
Currency required

Payment currency

Example:
CZK
order_number
string required

Order identification for the online shop, alphanumeric characters

Max length: 128
Example:
123456
order_description
string

Order description, alphanumeric characters

Max length: 256
Example:
Test recurrence
items
Array of Item

Individual items of the payment

additional_params

Additional parameters for the payment

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3123456790
parent_id
integer

Parent payment ID

Example:
3123456789
order_number
string

Order ID forwarded from the payment request

Example:
123456
state

Payment state

Example:
CREATED
amount
integer

Total amount in cents

Example:
1000
currency

Měna platby

Example:
CZK
payment_instrument

The selected payment method

Example:
PAYMENT_CARD
payer

Information about the payer and payment methods

target

Information about the recipient

additional_params

Additional parameters for the payment

lang

Language of the gateway UI

Example:
CS
HTTP
cURL
PHP
Python

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
Voiding a recurring payment
POST /api/payments/payment/{id}/void-recurrence

Used to cancel an ongoing recurrence.

Path variables

id
string required

Parent payment ID

Request headers

Accept
string required

Always application/json

Example:
application/json
Authorization
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3123456789
result

Operation result

Example:
FINISHED
HTTP Request
cURL
PHP
Python

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
Preauthorized payments
POST /api/payments/payment/{id}/capture
POST /api/payments/payment/{id}/capture
POST /api/payments/payment/{id}/void-authorization
Capturing a preauthorized payment
POST /api/payments/payment/{id}/capture

Used to capture the full amount of a preauthorized payment.

Path variables

id
string required

ID of the preauthorized payment

Request headers

Accept
string required

Always application/json

Example:
application/json
Authorization
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3123456789
result

Operation result

Example:
FINISHED
HTTP
cURL
PHP
Python

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
Partially capturing a preauthorized payment
POST /api/payments/payment/{id}/capture

Used 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
string required

ID of the preauthorized payment

Request headers

Accept
string required

Always application/json

Example:
application/json
Content-Type
string required

Always application/json

Example:
application/json
Authorization
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Request body

Object
amount
integer

Total amount in cents

Example:
30000
items
Array of Item

Individual items of the payment

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006542
result

Operation result

Example:
FINISHED
HTTP
cURL
PHP
Python

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
Voiding a preauthorized payment
POST /api/payments/payment/{id}/void-authorization

Used to release preauthorized funds back to the customer’s account.

Path variables

id
string required

ID of the preauthorized payment

Request headers

Accept
string required

Always application/json

Example:
application/json
Authorization
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006542
result

Operations Result

Example:
FINISHED
HTTP
cURL
PHP
Python

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
Payment cards
GET /api/payments/cards/{card_id}
DELETE /api/payments/cards/{card_id}
Payment card inquiry
GET /api/payments/cards/{card_id}

Used to get the details of a saved payment card.

Path variables

card_id
number required

Card ID

Request headers

Accept
string optional

Always application/json

Example:
application/json
Authorization
string optional

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
card_id
integer

Card ID

Example:
8039094151
card_number
string

Masked tokenized PAN (virtual card)

Example:
444444******4448
card_expiration
string

Card expiration

Example:
1909
card_brand
string

Card scheme

Example:
VISA
card_issuer_country
string

Country of the card issuer

Example:
CZE
card_issuer_bank
string

Card issuer

Example:
AIR BANK, A.S.
card_fingerprint
string

Card figerprint used to uniquely identify a card

Example:
0c823534ec582c97fa85c0bf7b020ee25a0a5af13974709bb329a709a79c2b3e
card_token
string

Card token used for card token payments

Example:
{{YOUR-CARD-TOKEN}}
status

The status of the saved card

Example:
active
real_masked_pan
string

Masked real PAN (physical card)

Example:
481747******1733
card_art_url
string

Link to a picture of the card design

Example:
https://gopay.com/api/payments/card-art/Mjc5MTg5ODI0MzIz
HTTP - active card
HTTP - deleted card
cURL
PHP
Python

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"]
Payment card deletion
DELETE /api/payments/cards/{card_id}

Used to delete a previously saved card.

Path variables

card_id
string required

Card ID

Request headers

Authorization
string optional

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Responses

204 No Content
HTTP
cURL
PHP
Python

Card deletion

DELETE /api/payments/cards/9876543210 HTTP/1.1 

Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 204 No Content

Card 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)
Payment methods
GET /api/eshops/eshop/{goid}/payment-instruments/{currency}
GET /api/eshops/eshop/{goid}/payment-instruments
Available payment methods for a currency
GET /api/eshops/eshop/{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
string required

GoID of the shop

currency
Currency required

Currency to check for payment methods

Request headers

Accept
string required

Always application/json

Example:
application/json
Authorization
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
groups

Description of payment method groups

enabledPaymentInstruments

List of enabled payment methods for a currency

HTTP
cURL
PHP
Python

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"]
    ]
All available payment methods
GET /api/eshops/eshop/{goid}/payment-instruments

Returns 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
string required

GoID of the shop

Request headers

Accept
string optional

Always application/json

Example:
application/json
Authorization
string optional

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
groups

Description of payment method groups

enabledPaymentInstruments
Any of

Object containing enabled payment methods

Object
<Payment Instrument>

Represents an individual enabled payment method. The object keys are values from the Payment instrument enum.

HTTP
cURL
PHP

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);
    }
Business account
POST /api/accounts/account-statement
Account statement
POST /api/accounts/account-statement

Used to generate an account statement for a GoPay business account. The response body is the file of the specified format.

Request headers

Accept
string required

Always application/json

Example:
application/json
Content-Type
string required

Always application/json

Example:
application/json
Authorization
string required

Bearer authentication with the access token

Example:
Bearer {{YOUR-TOKEN}}

Request body

Object
date_from
string date

Start date of the statement

Example:
2016-07-08
date_to
string date

End date of the statement

Example:
2016-08-08
goid
integer

GoID of the online shop

Example:
8123456789
currency

Currency of the account

Example:
CZK
format

Format of the statement

Example:
CSV_A

Responses

200 OK

The reponse body contains the specified file as application/octet-stream

application/octet-stream
HTTP
cURL
PHP
Python

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")
Objects
Target

Information about the payment recipient

Object
type
string

Always ACCOUNT

Example:
ACCOUNT
goid
integer

Unique identifier of the online shop in GoPay’s system

Example:
8123456789
Target
{
    "type": "ACCOUNT",
    "goid": 8123456789
}
Item

An individual item of the order

Object
type
Type required

Item type

Example:
ITEM
name
string required

Item name, alphanumeric characters

Max length: 256
Example:
Test item
amount
integer required

Total amount in cents (for the specified count)

Example:
1000
count
integer

Count

Min: 1
Example:
1
vat_rate
integer

VAT rate

Min: 0
Max: 100
Example:
21
ean
integer

EAN code of the product

Example:
4006381333931
product_url
string

URL address of the product

Max length: 512
Example:
https://example.com/product
Item - min
Item - full

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"
}
Contact

Information about the customer

Object
first_name
string

Customer’s first name

Max length: 256
Example:
John
last_name
string

Customer’s last name

Max length: 256
Example:
Doe
email
string required

Cusomer’s email

Max length: 128
Example:
john.doe@example.com
phone_number
string

Customer’s phone number including country code

Max length: 128
Example:
+420123456789
city
string

Address - city

Max length: 128
Example:
Test city
street
string

Address - street

Max length: 128
Example:
Test street 10
postal_code
string

Address - ZIP code

Max length: 16
Example:
10000
country_code
string

County code in respect to ISO 3166-1 alpha-3

Example:
CZE
Types: Payer
Contact - min
Contact - full

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"
}
Payer

Describes information about the customer and sets the payment methods. Also used for specific payments like Card token payment and Bank account token payment

allowed_bnpl_types and default_bnpl_type properties are not available yet and are present as a developer reference.

Object
contact
Contact required

Information about the customer

allowed_payment_instruments

Array of allowed payment methods

Example:
["PAYMENT_CARD", "BANK_ACCOUNT", "GPAY", "APPLE_PAY"]
default_payment_instrument

A pre-selected payment method

Example:
PAYMENT_CARD
allowed_swifts
Array of Swift

Array of allowed SWIFTs for bank transfers

Example:
["GIBACZPX", "CEKOCZPP", "FIOBCZPP", "AGBACZPP", "AIRACZPP"]
default_swift

A pre-selected SWIFT

Example:
GIBACZPX
allowed_bnpl_types
Array of BNPL types

Allowed types of BNPL-style payment (Buy Now Pay Later) (developer preview)

Example:
["THIRDS", "LATER"]
default_bnpl_type

Pre-selected type of BNPL-stype payment (Buy Now Pay Later) (developer preview)

Example:
LATER
bank_account

Information about customer’s bank account

payment_card
Payment card read-only

Information about customer’s payment card

request_card_token
boolean

Requests the customer’s payment card to be saved

Example:
false
card_id
integer read-only

ID of a card that was saved

allowed_card_token
string

Token of a saved card for card token payment

Example:
{{YOUR-TOKEN}}
email
string

Email of a used GoPay wallet (only relevant to the GOPAY payment method)

Example:
john.doe@example.com
Minimal - request
Standard - request
Payment card - response
Bank account - response

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"
    }
}
Callback

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.

Object
return_url
string required

URL used to redirect the customer from the gateway back to the shop

Max length: 512
Example:
https://example.com/your-return-url
notification_url
string required

URL used to deliver the HTTP notification

Max length: 512
Example:
https://example.com/your-notify-url
Callback
{
    "return_url": "https://example.com/your-return-url",
    "notification_url": "https://example.com/your-notify-url"
}
Payment card

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.

Object
card_number
string

Masked PAN

Example:
444444******4448
card_expiration
string

Card expiration

Example:
1230
card_brand
string

Card scheme

Example:
VISA
card_issuer_country
string

Country of the card issuer

Example:
CZE
card_issuer_bank
string

Card issuer

Example:
AIR BANK, A.S.
3ds_result

Result of the 3DS authentication

Example:
Y/Y
card_fingerprint
string

Card figerprint used to uniquely identify a card

Example:
7fa592f3e4b1af1945730b1c0e014d83b5102184fa6b3be15ef57c83d44c94c5
Types: 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)"
}
Bank account

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.

Object
prefix
string

Bank account prefix (CZ format)

Example:
000000
account_number
string

Bank account number (CZ format)

Example:
9878039
bank_code
string

Bank code (CZ format)

Example:
2010
iban
string

IBAN

Example:
CZ5120100000000009878039
bic
string read-only

SWIFT/BIC

Example:
FIOBCZPP
account_name
string read-only

Account holder name

Example:
John Doe
account_token
string

Account token for PSD2 remember mode

Example:
{{YOUR-ACCOUNT-TOKEN}}
Types: Payer
Bank account
{
    "prefix": "000000",
    "account_number": "9878039",
    "bank_code": "2010",
    "account_name": "John Doe",
    "iban": "CZ5120100000000009878039"
}
Additional param

Additional payment parameters

Object
name
string

Název parametru

Example:
Test name
value
string

Hodnota parametru

Example:
Test value
Additional param
{
    "name": "Test name",
    "value": "Test value"
}
Recurrence

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.

Object
recurrence_cycle

Payment recurrence cycle

Example:
MONTH
recurrence_period
integer

Payment recurrence period

Example:
12
recurrence_date_to
string date

Exclusive date to which the payment recurrence will be active, YYYY-MM-DD

Example:
2025-12-31
recurrence_state
Recurrence state read-only

Payment recurrence state

Example:
STARTED
AUTO - request
ON_DEMAND - request
Response

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"
}
Preauthorization

Describes preauthorization. Only returned in a payment inquiry

Object
requested
boolean

Whether preauthorization was requested for this payment

Example:
true

Preauthorization state

Example:
REQUESTED
Preauthorization
{
    "requested": true,
    "state": "REQUESTED"
}
Error

Describes API errors

Object

Whether the error ties to a specific field

Example:
F
field
string

What field does the error concern

Example:
goid
message
string

Localized message based on the Accept-Language header

Example:
Payee not found
description
string

Technical description

error_code
integer

Numeric error code

Example:
320
error_name
string

Error name

Example:
PAYEE_NOT_FOUND
Field error
Global error

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"
}
Group Code

Contains descriptions of payment method groups.

Object
label
Object

Payment method group label

cs
string

Czech payment method group description

Example:
Platební karta
Types: Groups
Example 1
{
  "label": {
    "cs": "Platební karta"
  }
}
Groups

List of all enabled payment method groups

Any of
Object
<Group>

Name of the payment method group. Keys come from the Group enum.

Example 1
{
  "card-payment": {
    "label": {
      "cs": "Platební karta"
    }
  }
}
Enabled swift

Enabled swift for bank transfers

Object
image
Object

Payment method icons

large
string

Large icon URL

Example:
https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png
normal
string

Small icon URL

Example:
https://gate.gopay.cz/images/checkout/GIBACZPX.png
isOnline
boolean

Whether an online transfer is available for this swift

Example:
true
label
Object

Payment method label

cs
string

Czech label

Example:
Platba 24
swift
string

Bank SWIFT

Example:
GIBACZPX
Example 1
{
  "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"
}
Enabled payment instrument

Describes an enabled payment method.

Object
enabledSwifts
Array of Enabled swift nullable

Array of enabled SWIFTs for bank transfers

group

Group of the payment method

Example:
card-payment
image
Object

Payment method icons

large
string

Large icon URL

Example:
https://gate.gopay.cz/images/checkout/payment_card@2x.png
normal
string

Small icon URL

Example:
https://gate.gopay.cz/images/checkout/payment_card.png
label
Object

Payment method labels

cs
string

Czech label

Example:
Platební karta
paymentInstrument

API code of the payment method

Example:
PAYMENT_CARD
Example 1
{
  "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 (all)

Enabled swift for bank transfers with currency listings.

Object
image
Object

Payment method icons

large
string

Large icon URL

Example:
https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png
normal
string

Small icon URL

Example:
https://gate.gopay.cz/images/checkout/GIBACZPX.png
isOnline
boolean

Whether an online transfer is available for this swift

Example:
true
label
Object

Payment method label

cs
string

Czech label

Example:
Platba 24
swift
string

Bank SWIFT

Example:
GIBACZPX
currencies
Any of
Object
<Currency>
Object

Currency for which the SWIFT is available. Keys come from the Currency enum.

isOnline
boolean

Whether an online transfer is available for this swift for this currency

Example:
true
Example 1
{
  "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"
    }
  }
}
Enabled payment instrument (all)

Describes an enabled payment method with currency listings.

Object
enabledSwifts
Any of nullable

Array of enabled SWIFTs for bank transfers

Object

Object for each swift. Keys come from the SWIFT enum.

group

Group of the payment method

Example:
bank-transfer
image
Object

Payment method icons

large
string

Large icon URL

Example:
https://gate.gopay.cz/images/checkout/bank_account@2x.png
normal
string

Small icon URL

Example:
https://gate.gopay.cz/images/checkout/bank_account.png
label
Object

Payment method labels

cs
string

Czech label

Example:
Bankovní platba
currencies
Array of Currency

Currencies for which the payment method is available

Example 1
{
  "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"
  ]
}
Enums

Seznam číselníků (enums) používaných v API

Currency

List of available currencies

string
Enumeration:
CZK

Czech koruna

EUR

Euro

PLN

Polish złoty

USD

US dolar

GBP

Pound sterling

HUF

Hungarian foring

RON

Romanian leu

BGN

Bulgarian lev

Payment instrument

List of available payment instruments. TWISTO and SKIPPAY are not available yet. They are present as a developer reference for now.

string
Enumeration:
PAYMENT_CARD

Payment card

BANK_ACCOUNT

Bank account transfer

GPAY

Google Pay

APPLE_PAY

Apple Pay

PAYPAL

PayPal

MPAYMENT

mPlatba (mobile payment)

PRSMS

Premium SMS

PAYSAFECARD

PaySafeCard coupon

BITCOIN

Bitcoin wallet

CLICK_TO_PAY

Click To Pay VISA/MasterCard

TWISTO

Twisto (developer preview)

SKIPPAY

Skip Pay (developer preview)

Swift

List of SWIFTs for payment method selection.

string
Enumeration:
GIBACZPX

Česká Spořitelna

KOMBCZPP

Komerční Banka

CEKOCZPP

ČSOB

RZBCCZPP

Raiffeisenbank

BACXCZPP

UniCredit Bank

AGBACZPP

Moneta Money Bank

FIOBCZPP

FIO Banka

BREXCZPP

mBank

AIRACZPP

AirBank

INGBCZPP

ING Bank

OBKLCZ2X

Oberbank

SUBACZPP

VÚB Praha

BPPFCZP1

Hello bank!

CTASCZ22

CREDITAS

EXPNCZPP

Max banka

JTBPCZPP

J&T Banka

TATRSKBX

Tatra Banka

SUBASKBX

Všeobecná Úverová Banka

UNCRSKBX

UniCredit Bank SK

GIBASKBX

Slovenská Sporiteľňa

CEKOSKBX

ČSOB SK

POBNSKBA

Poštová Banka

OTPVSKBX

OTP Banka Slovensko

KOMASK2X

Prima Banka Slovensko

CITISKBA

Citibank Europe

FIOZSKBA

Fio banka SK

BREXSKBX

mBank SK

INGBSKBX

ING Bank SK

JTBPSKBA

J&T Banka SK

OBKLSKBA

Oberbank SK

BSLOSK22

Privatbanka

BFKKSKBB

BKS Bank

TATRSKBXXXX

Raiffeisenbanka SK

KOMBSKBA

Komerční banka SK

Types: Payer
State

List of possible payment statuses

string
Enumeration:
CREATED

Created payment

PAID

Successful payment

CANCELED

Declined payment

PAYMENT_METHOD_CHOSEN

Pending payment

TIMEOUTED

Expired payment

AUTHORIZED

Preauthorized payment

REFUNDED

Refunded payment

PARTIALLY_REFUNDED

Partially refunded payment

Substate

List of payment substates

string
Enumeration:
_101

Waiting for an online bank transfer to be completed

_102

Waiting for an offline transfer to be finished

_3001

Bank transfer confirmed by advice

_3002

Bank tranfer confirmed by statement

_3003

Bank transfer not completed

_5001

Approved with zero amount

_5002

Declined by issuer - limit reached

_5003

Declined by issuer - problem at issuer’s side

_5004

Declined by issuer - payment card error

_5005

Declined by issuer - card blocked

_5006

Declined by issuer - insufficient funds

_5007

Declined by issuer - card expired

_5008

Declined by issuer - invalid CVV

_5009

Declined in the 3DS server

_5015

Declined in the 3DS server

_5017

Declined in the 3DS server

_5018

Declined in the 3DS server

_5019

Declined in the 3DS server

_6502

Declined in the 3DS server

_6504

Declined in the 3DS server

_5010

Declined by issuer - payment card error

_5014

Declined by issuer - payment card error

_5011

Declined by issuer - account error

_5036

Declined by issuer - account error

_5012

Declined by issuer - technical issues

_5013

Declined by issuer - wrong card number

_5016

Declined by issuer - payment not allowed

_5020

Unknown configuration

_5021

Declined by issuer - limit reached

_5022

Could not reach authorization centre

_5023

Payment not completed

_5038

Payment not completed

_5024

Payment not completed.

_5025

Payment not completed. Reason was shown to customer.

_5026

Payment not completed. Sum of credited amounts exceeded total amount.

_5027

Platba nebyla provedena. Uživatel není oprávněn k provedení operace.

_5028

Payment not completed. Customer is not authorized to perform transaction.

_5029

Payment not completed yet.

_5030

Payment not completed. Duplicate payment.

_5031

Technical error on issuer’s side.

_5033

Unable to deliver SMS.

_5035

Unsupported payment card region.

_5037

Cardholder canceled the payment.

_5039

Declined by issuer - card blocked

_5040

Duplicate transaction reversal

_5041

Duplicate transaction

_5042

Bank account payment declined

_5043

Payment canceled by customer

_5044

SMS was sent but not delivered yet.

_5045

Payment is being processed in the Bitcoin network.

_5046

Payment was not paid in full.

_5047

Payment made after expiration.

_5048

Customer has not given PSD2 consent.

_5049

PSD2 payment declined

_5050

PSD2 requested account not found

Methods: Payment inquiry
Card status

State of a saved payment card

string
Enumeration:
active

Saved card is active

deleted

Saved card is deleted

Type

Order item type

string
Enumeration:
ITEM

Product or service

DELIVERY

Shipping

DISCOUNT

Discount

Types: Item
Scope

Token permission scope

string
Enumeration:
payment-create

Only allows creating payments

payment-all

Allows all operations

Lang

Language of payment gateway UI

string
Enumeration:
CS

Czech

SK

Slovak

EN

English

DE

German

RU

Russian

FR

French

HU

Hungarian

PL

Polish

RO

Romanian

BG

Bulgarian

HR

Croatian

IT

Italian

ES

Spanish

UK

Ukrainian

ET

Estonian

LT

Lithuanian

LV

Latvian

SL

Slovenian

PT

Portuguese

Result

Operation result

string
Enumeration:
ACCEPTED

Operation accepted for asynchronous processing

FINISHED

Operations finished successfully

FAILED

Operation failed