GoPay REST API

GoPay REST API

REST API documentation for the GoPay payment gateway.
Documentation

GoPay REST API is avaliable in test mode at https://gw.sandbox.gopay.com/api. Production enviroment is located at https://gate.gopay.cz/api. All comunication with API is encoded in UTF-8. You can find integration details in our help center. For the test purposes you can use making test paymets guide (includes e.g. test payments cards).

API
PHP SDK
Python SDK
.NET SDK
Java SDK
API ENDPOINTS

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

AVAILABLE METHODS

/oauth2/token
/payments/payment
/payments/payment/{id}
/payments/payment/{id}/refund
/payments/payment/{id}/create-recurrence
/payments/payment/{id}/void-recurrence
/payments/payment/{id}/void-authorization
/payments/payment/{id}/capture
GitHub: https://github.com/gopaycommunity/gopay-php-api
Requirements: PHP >= 7.4
Composer download: https://getcomposer.org
Installation: composer require gopay/payments-sdk-php
https://github.com/gopaycommunity/gopay-python-api
Requirements: Python >= 2.6
Installation: pip install gopay
https://github.com/gopaycommunity/gopay-dotnet-api
Requirements : .NET 4.0+
NuGet
PM> Install-Package GOPAY.NET
Dependencies
Newtonsoft.Json
Restsharp
Restsharp.Newtonsoft.Json
Namespace
using GoPay.Common;
using GoPay.Model;
using GoPay.Payment;
using GoPay.Model.Payments;
using GoPay.EETProp;
using GoPay.Account;
https://github.com/gopaycommunity/gopay-java-api
Requirements : JAVA >= 7.0
Installation :
git clone https://github.com/gopaycommunity/gopay-java-api.git cd gopay-java-api
mvn package

All artifacts are located in the maven central repository.
http://mvnrepository.com/artifact/cz.gopay

If Apache HTTP Client does not suit you, the api supports two frameworks:

Resteasy
Apache CXF
More info about frameworks integration can be found on our github
Authentication

GoPay uses REST API for authorization of the access to API principal OAuth2.0, specifically method of client authentication, see RFC 6479

POST /api/oauth2/token
Access token
POST /api/oauth2/token

The basic element of all communication via REST API is an access token that is created by using the access data in the form of <ClientID>:<ClientSecret>, encoded in base64 and passed in the Authorization header. A token is set as an authorization parameter in HTTP request header through Authorization: Bearer <Access-Token>. This token is set for every requirement for API. Token expires after 30 minutes. After expiry of the token, it is necessary to create a new access token.

ⓘ If you do not have ClientID and ClientSecret, please, make your registration.

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 authentication

Example:
Basic MTA2MTM5OTE2MzpzdERUbVZYRg==

Request body

application/x-www-form-urlencoded
Object
scope

Access token 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

Access token

Example:
AAAnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p
refresh_token
string

Refresh token - currently not used

Example:
xzZnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p
expires_in
integer

Token validity time (in seconds)

Example:
1800
HTTP
cURL
PHP
Python
.NET
Java
Response
POST /api/oauth2/token HTTP/1.1 

Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MTA2MTM5OTE2MzpzdERUbVZYRg==

scope=payment-create
&grant_type=client_credentials
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 "1061399163:stDTmVXF" \
-d "grant_type=client_credentials&scope=payment-create"
<?php
$gopay = GoPay\payments([
    'goid' => '8123456789',
    'clientId' => '1061399163',
    'clientSecret' => 'stDTmVXF',
    'gatewayUrl' => 'https://gw.sandbox.gopay.com/',
    'scope' => GoPay\Definition\TokenScope::ALL,
    'language' => GoPay\Definition\Language::CZECH,
    'timeout' => 30
]);
// token is retrieved automatically, no need to call a specific method
import gopay

api = gopay.payments({
    'goid': '8302931681',
    'clientId': '1061399163',
    'clientSecret': 'stDTmVXF',
    'isProductionMode': False,
    'scope': gopay.TokenScope.ALL,
    'language': gopay.Language.CZECH,
    'timeout': 30
})
# token is retrieved automatically, no need to call a specific method
var connector = new GPConnector(<API_URL>,<USER_ID>, <USER_SECRET>);
connector.GetAppToken();   
IGPConnector connector = HttpClientGPConnector.build(<API_URL>);
connector.getAppToken(<CLIENT_ID>,<CLIENT_CREDENTIALS>); 
// API_URL for sandbox - https://gw.sandbox.gopay.com/api
// API_URL for production mode - https://gate.gopay.cz/api
{
    "token_type":"bearer",
    "access_token":"AAAnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p",
    "expires_in":1800
}
Payments

Before initiating the payment gateway, it is necessary to establish the payment. In effect of calling, we repeat parameters of the payment including the parameter gw_url, which you can initiate to inline or redirect payment gateway.

The payee of the payment is identified by goid in the target object. You can get it, when you integrate the payment gateway for identification of specific point of sale, e.g. demo.goshop.com.

If you do not have GoID, please, make your registration.

Within the payment, the paying party is described by an object payer, which identifies the payer and determines the set of permitted payment method, including the default method.

POST /api/payments/payment
GET /api/payments/payment/{id}
POST /api/payments/payment/{id}/refund
Standard payment creation
POST /api/payments/payment

The payment is determined for paying of an order by credit card, bank transfer, GoPay account and other payment methods. For further information about all steps needed to make base payment check our help center.

When using the preauthorization and recurrence parameters, the payment will be preauthorized, or recurrent respectively. eet parameter is only mandatory if you’re using EET in the B variant.

ⓘ We strongly recommend to include the contact object in the payer object with all customer data. This might lead to a better success rate of payments.

Request headers

Authorization
string required

String “Bearer” followed by the access token

Example:
Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
Content-Type
string required

Always application/json

Example:
application/json
Accept
string required

Always application/json

Example:
application/json

Request body

Object
payer

Payment method settings and payer information

target
Target required

Payee information

items
Array of Item

Details of the payment items

amount
integer required

Payment amount in cents

Example:
139950
currency
Currency required

Payment currency

Example:
CZK
order_number
string required

Merchant’s order id, alphanumeric

Max length: 128
Example:
OBJ20200825
order_description
string

Order description, alphanumeric

Max length: 256
Example:
Obuv
lang

Payment gateway language

Example:
CS
callback

Callback URL for processing of the payment result / Notification URL for processing of change of payment status

additional_params

Additional payment parameters

Max items: 4
preauthorization
boolean

true if the payment should be preauthorized

Example:
true
recurrence

Contains object describing recurrence, if the payment should be recurrent

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006529
order_number
string

Order ID

Example:
OBJ20200825
state

Payment status

Example:
CREATED
amount
integer

Amount in cents

Example:
139950
currency

Payment currency

Example:
CZK
payer

Information about the payer and payment methods

target

Payee information

additional_params

Additional parameters

lang

Payment gateway language

Example:
CS
recurrence

Descibes recurrence if the payment is recurrent

preauthorization

Describes preauthorization if the payment is preauthorized

gw_url
string

URL for initiation of the payment gate

Example:
https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF
HTTP
cURL
PHP
Python
.NET
Java
Response
POST /api/payments/payment HTTP/1.1 

Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
Content-Type: application/json
Accept: application/json

{
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
            "BANK_ACCOUNT"
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "allowed_swifts": [
            "FIOBCZPP",
            "BREXCZPP"
        ],
        "default_swift": "FIOBCZPP",
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Obuv",
            "amount": 119990,
            "count": 1,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.cz/boty/lodicky"
        }
    ],
    "amount": 119990,
    "currency": "CZK",
    "order_number": "OBJ20200825",
    "order_description": "Obuv",
    "lang": "CS",
    "callback": {
        "return_url": "https://www.example.com/return",
        "notification_url": "https://www.example.com/notify"
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"  \
 -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": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Obuv",
            "amount": 119990,
            "count": 1,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.cz/boty/lodicky"
        }
    ],
    "amount": 119990,
    "currency": "CZK",
    "order_number": "OBJ20200825",
    "order_description": "Obuv",
    "lang": "CS",
    "callback": {
        "return_url": "https://www.example.com/return",
        "notification_url": "https://www.example.com/notify"
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}'
<?php
use GoPay\Definition\Language;
use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Payment\PaymentInstrument;
use GoPay\Definition\Payment\BankSwiftCode;
use GoPay\Definition\Payment\VatRate;
use GoPay\Definition\Payment\PaymentItemType;

$response = $gopay->createPayment([
    'payer' => [
            'default_payment_instrument' => PaymentInstrument::BANK_ACCOUNT,
            'allowed_payment_instruments' => [PaymentInstrument::BANK_ACCOUNT],
            'default_swift' => BankSwiftCode::FIO_BANKA,
            'allowed_swifts' => [BankSwiftCode::FIO_BANKA, BankSwiftCode::MBANK],
            'contact' => ['first_name' => 'Zbynek',
                    'last_name' => 'Zak',
                    'email' => 'test@test.cz',
                    'phone_number' => '+420777456123',
                    'city' => 'C.Budejovice',
                    'street' => 'Plana 67',
                    'postal_code' => '373 01',
                    'country_code' => 'CZE'
            ]
    ],
    'amount' => 139951,
    'currency' => Currency::CZECH_CROWNS,
    'order_number' => '001',
    'order_description' => 'obuv',
    'items' => [[
            'type' => 'ITEM',
            'name' => 'obuv',
            'product_url' => 'https://www.eshop.cz/boty/lodicky',
            'ean' => 1234567890123,
            'amount' => 119990,
            'count' => 1,
            'vat_rate' => VatRate::RATE_4
    ],
            [
            'type' => PaymentItemType::ITEM,
            'name' => 'oprava podpatku',
            'product_url' => 'https://www.eshop.cz/boty/opravy',
            'ean' => 1234567890189,
            'amount' => 19961,
            'count' => 1,
            'vat_rate' => VatRate::RATE_3
            ]],
    'eet' => [
            'celk_trzba' => 139951,
            'zakl_dan1' => 99160,
            'dan1' => 20830,
            'zakl_dan2' => 17358,
            'dan2' => 2603,
            'mena' => Currency::CZECH_CROWNS
    ],
    'additional_params' => [['name' => 'invoicenumber',
            'value' => '2015001003'
    ]],
    'callback' => [
            'return_url' => 'https://www.eshop.cz/return',
            'notification_url' => 'https://www.eshop.cz/notify'
    ],
    'lang' => Language::CZECH
]);
from gopay.enums import PaymentInstrument, BankSwiftCode, Currency

response = api.create_payment({
    'payer': {
        'default_payment_instrument': PaymentInstrument.BANK_ACCOUNT,
        'allowed_payment_instruments': [PaymentInstrument.BANK_ACCOUNT],
        'default_swift': BankSwiftCode.FIO_BANKA,
        'allowed_swifts': [BankSwiftCode.FIO_BANKA, BankSwiftCode.MBANK],
        'contact': {
            'first_name': 'Zbynek',
            'last_name': 'Zak',
            'email': 'test@test.cz',
            'phone_number': '+420777456123',
            'city': 'C.Budejovice',
            'street': 'Plana 67',
            'postal_code': '373 01',
            'country_code': 'CZE',
        },
    },
    'amount': 139951,
    'currency': Currency.CZECH_CROWNS,
    'order_number': '001',
    'order_description': 'pojisteni01',
    'items': [
        {'name': 'item01', 'amount': 119990},
        {'name': 'item02', 'amount': 19961},
    ],
    'additional_params': [
        {'name': 'invoicenumber', 'value': '2015001003'}
    ],
    'callback': {
        'return_url': 'http://www.your-url.tld/return',
        'notification_url': 'http://www.your-url.tld/notify'
    }
})
var payment = new BasePayment()
    {
        Currency = <Currency>,
        Lang = "ENG",
        OrderNumber = "789456167879",
        Amount = 139951,
        Target = new Target()
        {
            GoId = <GOID>,
            Type = Target.TargetType.ACCOUNT
        },
        Callback = new Callback()
        {
            NotificationUrl = <NOTIFICATION_URL>,
            ReturnUrl = <RETURN_URL>
        },
        Payer = new Payer()
        {
            Contact = new PayerContact()
            {
                Email = "test@test.cz"
            },
            DefaultPaymentInstrument = PaymentInstrument.PAYMENT_CARD
        }
    };

try {
     var result = connector.CreatePayment(payment);
} catch (GPClientException e) {
//
}
BasePayment payment = PaymentFactory.createBasePaymentBuilder()
    .order(<ORDER_NUMBER>, <AMOUNT>, Currency.EUR, <DESCRIPTION>)
    .addItem(<ITEM_NAME>, <AMOUNT>, <FEE>, <COUNT>)
    .addAdditionalParameter(<Key>, <VALUE>)
    .withCallback(<RETURN_URL>, <NOTIFY_URL>)
    .payer(<Payer>)
    .inLang(Lang.EN)
    .toEshop(<GO_ID>)
    .build();
try {
    Payment result = connector.createPayment(payment);
} catch (GPClientException e) {
     for (ErrorElement err : e.getError().getErrorMessages()) {
        int code = err.getErrorCode();
        String message = err.getMessage();
        String field = err.getField();
    }
}
{
    "id": 3000006529,
    "order_number": "OBJ20200825",
    "state": "CREATED",
    "amount": 139950,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
            "BANK_ACCOUNT"
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "allowed_swifts": [
            "FIOBCZPP",
            "BREXCZPP"
        ],
        "default_swift": "FIOBCZPP",
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ],
    "lang": "CS",
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}
Payment status
GET /api/payments/payment/{id}

The payment status funcionality allows the point of sale to determine, whether the payment was successfully paid or not. By default, the payment status is queried after receiving of a notification about the payment status change.

If EET was used for the payment, the response contains EET Code. If the payment is preauthorized or recurrent, the response contains preauthorization or recurrence respectively. The payer object can contains info about bank account or payment card if the payment was paid using one of those methods. It can also contain information regarding the identification payment.

More information about payment state you can find in our help center.

Path variables

id
string required

Payment ID of requested payment

Request headers

Accept
string required

Always application/json

Example:
application/json
Authorization
string required

String “Bearer” followed by the access token

Example:
Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006529
order_number
string

Order ID

Example:
OBJ20200825
state

Payment status

Example:
PAID
sub_state

Payment substate

Example:
_3001
amount
integer

Payment amount in cents

Example:
139950
currency

Payment currency

Example:
CZK
payment_instrument

Payment method used

Example:
BANK_ACCOUNT
payer

Information about payer and payment methods

target

Payee information

additional_params

Additional payment parameters

lang

Payment gateway language

Example:
CS
recurrence

Recurrence info if the payment is recurrent

preauthorization

Preauthorization info if the payment is preauthorized

eet_code
Object
fik
string

Fiskální identifikační kód (FIK)

Example:
28da0811-e050-46c7-a62c-aa456d1f07ef-ff
bkp
string

Bezpečnostní kód poplatníka (BKP)

Example:
5d874afc-251f8661-ff0e0b13-c7cd8793-6bf0386a
pkp
string

Podpisový kód poplatníka (PKP)

Example:
Ca8sTbURReQjjgcy/znXBKjPOnZof3AxWK5WySpyMrUXF0o7cz1BP6a.....
gw_url
string

Payment gateway URL

Example:
https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF
HTTP
cURL
PHP
Python
.NET
Java
Response
GET /api/payments/payment/3000006529 HTTP/1.1 

Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
curl -X GET "/api/payments/payment/3000006529"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/x-www-form-urlencoded"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"
<?php
$response = $gopay->getStatus(3000006529);
response = api.get_status(3000006529)
try {
  var payment = connector.PaymentStatus(<PAYMENT_ID>);
} catch (GPClientException e) {
//
}
try {
    Payment payment = connector.paymentStatus(<PAYMENT_ID>);
} catch (GPClientException e) {
     for (ErrorElement err : e.getError().getErrorMessages()) {
        int code = err.getErrorCode();
        String message = err.getMessage();
        String field = err.getField();
    }            
}
{
    "id": 3000006529,
    "order_number": "OBJ20200825",
    "state": "PAID",
    "amount": 139950,
    "currency": "CZK",
    "payment_instrument": "PAYMENT_CARD",
   "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
            "BANK_ACCOUNT"
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "allowed_swifts": [
            "FIOBCZPP",
            "BREXCZPP"
        ],
        "default_swift": "FIOBCZPP",
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        },
        "payment_card": {
            "card_number": "444444******4448",
            "card_expiration": "1909",
            "card_brand": "VISA",
            "card_issuer_country": "CZE",
            "card_issuer_bank": "AIR BANK, A.S.",
            "3ds_result": "Y/Y"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ],
    "lang": "CS",
    "gw_url": " https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}
Payment refund
POST /api/payments/payment/{id}/refund

Refund of the payment is a functionality which allows recovering funds for already made payment to the customer.

Based on the amount parameter, the refund can be either full or partial.

You can find additional information about refunds in help center.

Path variables

id
string required

Payment ID to refund

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

String “Bearer” followed by the access token

Example:
Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

Request body

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

Amount to be refunded in cents

Example:
50000

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006620
result

Result of the operation

Example:
FINISHED
HTTP
cURL
PHP
Python
.NET
Java
Response
POST /api/payments/payment/3000006620/refund HTTP/1.1 

Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

amount=50000
curl -X POST "/api/payments/payment/3000006620/refund"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/x-www-form-urlencoded"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"  \
 -d 'amount=50000'
<?php
$response = $gopay->refundPayment(3000006620, 50000);
response = api.refund_payment(3000006620, 50000)
try {
    var result = connector.RefundPayment(<PAYMENT_ID>, <AMOUNT>);
} catch (GPClientException e) {
//
}
try {
    PaymentResult result = connector.refundPayment(<PAYMENT_ID>, <AMOUNT>);
} catch (GPClientException e) {
     for (ErrorElement err : e.getError().getErrorMessages()) {
        int code = err.getErrorCode();
        String message = err.getMessage();
        String field = err.getField();
    }              
}
{
    "id": 3000006620,
    "result": "FINISHED"
}
Recurring payments
POST /api/payments/payment/{id}/create-recurrence
POST /api/payments/payment/{id}/void-recurrence
Recurrent payment creation

Recurring payment is a functionality that allows accepting the payment via payment cards from the customer on a regular basis. After the successful initiation of the initiation payment, payments are made automatically, e.g. on daily basis DAY or on demand ON_DEMAND.

In the case of the ON_DEMAND payment, the subsequent payment is made by API call for recurrence payment.

ⓘ Another information about recurring payments you can find in our Help Center.

In order to create a recurring payment, use standard payment creation, extended with the recurrence object.

HTTP
cURL
PHP
Python
.NET
Java
Response
POST /api/payments/payment HTTP/1.1 

Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
Content-Type: application/json
Accept: application/json

{
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
            "APPLE_PAY"
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "contact": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "test@test.com",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Subscription",
            "amount": 1190,
            "count": 1,
            "product_url": "https://www.eshop.com/shoes/stiletto"
        }
    ],
    "recurrence": {
        "recurrence_cycle": "MONTH",
        "recurrence_period": 1,
        "recurrence_date_to": "2025-12-31",
    },
    "amount": 1190,
    "currency": "EUR",
    "order_number": "ORD20200825",
    "order_description": "Subscription",
    "lang": "EN",
    "callback": {
        "return_url": "https://www.example.com/return",
        "notification_url": "https://www.example.com/notify"
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"  \
 -H "Content-Type: application/json"  \
 -H "Accept: application/json"  \
 -d '{
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
            "APPLE_PAY"
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Obuv",
            "amount": 119990,
            "count": 2,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.cz/boty/lodicky"
        }
    ],
    "recurrence": {
        "recurrence_cycle": "MONTH",
        "recurrence_period": 1,
        "recurrence_date_to": "2025-12-31",
    },
    "amount": 139950,
    "currency": "CZK",
    "order_number": "OBJ20200825",
    "order_description": "Obuv",
    "lang": "CS",
    "callback": {
        "return_url": "https://www.example.com/return",
        "notification_url": "https://www.example.com/notify"
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}'
<?php
use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Payment\PaymentInstrument;
use GoPay\Definition\Payment\BankSwiftCode;
use GoPay\Definition\Payment\Recurrence;

$response = $gopay->createPayment([
    'payer' => [
        'contact' => [
            'first_name' => 'Zbynek',
            'last_name' => 'Zak',
            'email' => 'test@test.cz',
            'phone_number' => '+420777456123',
            'city' => 'C.Budejovice',
            'street' => 'Plana 67',
            'postal_code' => '373 01',
            'country_code' => 'CZE',
        ],
    ],
    'amount' => 1000,
    'currency' => Currency::CZECH_CROWNS,
    'order_number' => '001',
    'order_description' => 'objednavka01',
    'items' => [
                [
                 'type' => 'ITEM', 
                 'name' => 'obuv',
                 'product_url' => 'https://www.eshop.cz/boty/lodicky', 
                 'ean' => 1234567890123,
                 'amount' => 700,
                 'count' => 1,
                 'vat_rate' => VatRate::RATE_4
                ], 
                [
                 'type' => 'ITEM', 
                 'name' => 'oprava podpatku',
                 'product_url' => 'https://www.eshop.cz/boty/opravy', 
                 'ean' => 1234567890189,
                 'amount' => 300,
                 'count' => 1,
                 'vat_rate' => VatRate::RATE_3
                ],
    ],
    'recurrence' => [
        'recurrence_cycle' => Recurrence::DAILY,
        'recurrence_period' => "7",
        'recurrence_date_to' => '2025-12-31'
    ],
    'additional_params' => [
        array('name' => 'invoicenumber', 'value' => '2015001003')
    ],
    'callback' => [
        'return_url' => 'http://www.your-url.tld/return',
        'notification_url' => 'http://www.your-url.tld/notify'
    ]
]);
from gopay.enums import PaymentInstrument, BankSwiftCode, Currency, Recurrence

response = api.create_payment({
    'payer': {
        'contact': {
            'first_name': 'Zbynek',
            'last_name': 'Zak',
            'email': 'test@test.cz',
            'phone_number': '+420777456123',
            'city': 'C.Budejovice',
            'street': 'Plana 67',
            'postal_code': '373 01',
            'country_code': 'CZE',
        },
    },
    'amount': 150,
    'currency': Currency.CZECH_CROWNS,
    'order_number': '001',
    'order_description': 'pojisteni01',
    'items': [
        {'name': 'item01', 'amount': 50},
        {'name': 'item02', 'amount': 100},
    ],
    'recurrence': {
        'recurrence_cycle': Recurrence.DAILY,
        'recurrence_period': "7",
        'recurrence_date_to': '2015-12-31'
    },
    'additional_params': [
        {'name': 'invoicenumber', 'value': '2015001003'}
    ],
    'callback': {
        'return_url': 'http://www.your-url.tld/return',
        'notification_url': 'http://www.your-url.tld/notify'
    }
})
var recurrence = new Recurrence() 
{
Cycle = RecurrenceCycle.DAY,
DateTo = new DateTime(2020, 12, 12),
Period = 5
};
var payment = new BasePayment();
payment.Recurrence = recurrence;

try {
  connector.CreatePayment(payment);
} catch {GPClientException e) {
//
}
BasePayment payment = PaymentFactory.createBasePaymentBuilder()
    .order(<ORDER_NUMBER>, <AMOUNT>, Currency.EUR, <DESCRIPTION>)
    .addItem(<ITEM_NAME>, <AMOUNT>, <FEE>, <COUNT>)
    .addAdditionalParameter(<Key>, <VALUE>)
    .withCallback(<RETURN_URL>, <NOTIFY_URL>)
    .payer(<Payer>)
    .inLang(Lang.EN)
    .toEshop(<GO_ID>)
    .build();

Calendar calendar = Calendar.getInstance();
calendar.set(Calendar.YEAR, 2016);
calendar.set(Calendar.MONTH, 2);
calendar.set(Calendar.DAY_OF_MONTH, 1);
Recurrence r = Recurrence.build(calendar.getTime())
    .withTimeInterval(RecurrenceCycle.WEEK, 1)
    .inState(Recurrence.RecurrenceState.STARTED);

payment.setRecurrence(r);

try {
    connector.createPayment(payment);
} catch {GPClientException e) {
     for (ErrorElement err : e.getError().getErrorMessages()) {
        int code = err.getErrorCode();
        String message = err.getMessage();
        String field = err.getField();
    }
}
{
  "id":3000006542,
  "order_number":"001",
  "state":"CREATED",
  "amount":1000,"currency":"CZK",
  "payer":{
           "contact":{"first_name":"Zbynek",
                      "last_name":"Zak",
                      "email":" test@test.cz",
                      "phone_number":"+420777456123",
                      "city":"C.Budejovice",
                      "street":"Plana 67",
                      "postal_code":"37301",
                      "country_code":"CZE"
                    }
          },
    "target":{"type":"ACCOUNT","goid":8123456789},
    "recurrence":{"recurrence_cycle":"DAY",
                  "recurrence_period":7,
                  "recurrence_date_to":"2025-12-31",
                  "recurrence_state":"REQUESTED"
                },
    "additional_params":[{"name":"invoicenumber",
                          "value":"2015001003"
                        }],
    "lang":"cs",
    "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF "
}
Recurring on demand
POST /api/payments/payment/{id}/create-recurrence

The functionality allows you to recur the payment based on previously established recurring payment ON_DEMAND mode. Recurring in this mode establishes the subsequent payment. The point of sale is informed through the notification about the change in the payment status.

More information about reccuring payments you can find in help center.

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

String “Bearer” followed by the access token

Example:
Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

Request body

Object
amount
integer required

Payment amount in cents

Example:
29900
currency
Currency required

Payment currency

Example:
EUR
order_number
string required

Merchant’s order id, alphanumeric

Max length: 128
Example:
OBJ20200825
order_description
string

Order description, alphanumeric

Max length: 256
Example:
Subscription
items
Array of Item required

Details of the payment items

additional_params

Additional payment parameters

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006621
parent_id
integer

Parent payment ID

Example:
3000006542
order_number
string

Order ID

Example:
ORD20200825
state

Payment status

Example:
CREATED
amount
integer

Payment amount

Example:
29900
currency

Payment currency

Example:
EUR
payment_instrument

Paymemnt method

Example:
PAYMENT_CARD
payer

Information about the payer and payment methods

target

Payee information

additional_params

Additional parameters

lang

Payment gateway language

Example:
EN
HTTP
cURL
PHP
Python
.NET
Java
Response
POST /api/payments/payment/3000006542/create-recurrence HTTP/1.1 

Accept: application/json
Content-Type: application/json
Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

{
    "amount": 119900,
    "currency": "EUR",
    "order_number": "OBJ20200825",
    "order_description": "Subscription",
    "items": [
        {
            "type": "ITEM",
            "name": "Subscription",
            "amount": 119900,
            "count": 1,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.com/subscribe"
        }
    ],
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}
curl -X POST "/api/payments/payment/3000006542/create-recurrence"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/json"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"  \
 -d '{
    "amount": 119900,
    "currency": "EUR",
    "order_number": "OBJ20200825",
    "order_description": "Subscription",
    "items": [
        {
            "type": "ITEM",
            "name": "Subscription",
            "amount": 119900,
            "count": 1,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.com/subscribe"
        }
    ],
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}'
<?php
$response = $gopay->createRecurrence(
    3000006542,
    [
        'amount' => '500',
        'currency' => 'EUR',
        'order_number' => '002',
        'order_description' => 'subscription02',
        'items' => [
            ['name' => 'item01', 'amount' => '500']
        ],
        'additional_params' => [
            ['name' => 'invoicenumber', 'value' => '2021001004']
        ]
    ]
);
response = api.create_recurrence(
    3000006542,
    {
        'amount': '500',
        'currency': 'CZK',
        'order_number': '002',
        'order_description': 'pojisteni02',
        'items': {
            {'name': 'item01', 'amount': '500'}
        },
        'additional_params': {
            {'name': 'invoicenumber', 'value': '2015001004'}
        }
    }
)
var nextPayment = new NextPayment()
  {
    Amount = <Amount>,
    Currency = <Currency>,
    OrderNumber = <OrderNumber>,
    OrderDescription = <OrderDescription>
  };
try
  {
    connector.CreateRecurrentPayment(<IdOfPaidOnDemandPayment>, nextPayment)
  }
    catch (GPClientExcepetion exception)
  {
    //
  }
try {
  NextPaymentBuilder builder = PaymentFactory.createNextPaymentBuilder();
  ...
  PaymentResult recurrentPayment = connector.createRecurrentPayment(<ID>, builder.build());
} catch (GPClientException ex) {
  //
}
{
 "id":3000006621,
 "parent_id":3000006542,
 "order_number":"002",
 "state":"CREATED",
 "amount":1000,
 "currency":"EUR",
 "payment_instrument":"PAYMENT_CARD",
 "payer": {
           "contact":{"first_name":"John",
                      "last_name":"Doe",
                      "email":" test@test.com",
                      "phone_number":"+420777456123",
                      "city":"C.Budejovice",
                      "street":"Plana 67",
                      "postal_code":"37301",
                      "country_code":"CZE"
            }
  },
 "target":{"type":"ACCOUNT",
           "goid":8123456789
          },
 "additional_params":[{"name":"invoicenumber","value":"2015001004"}],
 "lang":"cs",
 "gw_url":"https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}
Cancellation of recurring payment
POST /api/payments/payment/{id}/void-recurrence

The functionality allows you to cancel recurrence of previously created payment. The user has the same opportunity as logged into GoPay​ account.

More information about recurring payments you can find in help center.

ⓘ We recommend at least 3 tries to make recurrence on parent payment. If they are all unsuccessful you can cancel the recurrence.

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/x-www-form-urlencoded

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

String “Bearer” followed by the access token

Example:
Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006542
result

Result of the operation

Example:
FINISHED
HTTP
cURL
PHP
Python
.NET
Java
Response
POST /api/payments/payment/3000006542/void-recurrence HTTP/1.1 

Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
curl -X POST "/api/payments/payment/3000006542/void-recurrence"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/x-www-form-urlencoded"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"
<?php
$response = $gopay->voidRecurrence(3000006542);
response = api.void_recurrence(3000006529)
try {
    var voidRecurrency = connector.VoidRecurrency(<ID>);
} catch (GPClientException ex) {
//
}
try {
    PaymentResult voidRecurrency = connector.voidRecurrency(<ID>);
} catch (GPClientException ex) {
      for (ErrorElement err : e.getError().getErrorMessages()) {
        int code = err.getErrorCode();
        String message = err.getMessage();
        String field = err.getField();
    }           
}
{
    "id": 3000006542,
    "result": "ACCEPTED"
}
Preauthorized payments

Pre-authorization allows you to block funds in the customer’s account for 4 days when paying by card. Blocked resources can then be partially captured or captured in full using API calls.

To release blocked funds, it is necessary to cancel the pre-authorization of the payment.

POST /api/payments/payment/{id}/capture
POST /api/payments/payment/{id}/capture
POST /api/payments/payment/{id}/void-authorization
Preauthorized payment creation

Creating a preauthorized payment is basically the same as the API by calling create standard payment, where you need to add the preauthorization parameter with the valuetrue.

HTTP
cURL
PHP
Python
.NET
Java
Response
POST /api/payments/payment HTTP/1.1 

Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
Content-Type: application/json
Accept: application/json

{
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD"
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "contact": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "test@test.com",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Shoes",
            "amount": 119990,
            "count": 1,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.com/shoes/shoe"
        }
    ],
    "preauthorization": true,
    "amount": 119990,
    "currency": "EUR",
    "order_number": "OBJ20200825",
    "order_description": "Shoes",
    "lang": "CS",
    "callback": {
        "return_url": "https://www.example.com/return",
        "notification_url": "https://www.example.com/notify"
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"  \
 -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": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Obuv",
            "amount": 119990,
            "count": 1,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.cz/boty/lodicky"
        }
    ],
    "preauthorization": "true",
    "amount": 119990,
    "currency": "CZK",
    "order_number": "OBJ20200825",
    "order_description": "Obuv",
    "lang": "CS",
    "callback": {
        "return_url": "https://www.example.com/return",
        "notification_url": "https://www.example.com/notify"
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}'
<?php
use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Payment\PaymentInstrument;
use GoPay\Definition\Payment\BankSwiftCode;

$response = $gopay->createPayment([
    'payer' => [
        'contact' => [
            'first_name' => 'Zbynek',
            'last_name' => 'Zak',
            'email' => 'test@test.cz',
            'phone_number' => '+420777456123',
            'city' => 'C.Budejovice',
            'street' => 'Plana 67',
            'postal_code' => '373 01',
            'country_code' => 'CZE',
        ],
    ],
    'amount' => 1000,
    'currency' => Currency::CZECH_CROWNS,
    'order_number' => '001',
    'order_description' => 'objednavka01',
   'items' => [
                [
                 'type' => 'ITEM', 
                 'name' => 'obuv',
                 'product_url' => 'https://www.eshop.cz/boty/lodicky', 
                 'ean' => 1234567890123,
                 'amount' => 700,
                 'count' => 1,
                 'vat_rate' => VatRate::RATE_4
                ], 
                [
                 'type' => 'ITEM', 
                 'name' => 'oprava podpatku',
                 'product_url' => 'https://www.eshop.cz/boty/opravy', 
                 'ean' => 1234567890189,
                 'amount' => 300,
                 'count' => 1,
                 'vat_rate' => VatRate::RATE_3
                ],
    ],
    'preauthorization' => true,
    'additional_params' => [
        array('name' => 'invoicenumber', 'value' => '2015001003')
    ],
    'callback' => [
        'return_url' => 'http://www.your-url.tld/return',
        'notification_url' => 'http://www.your-url.tld/notify'
    ]
]);
from gopay.enums import PaymentInstrument, BankSwiftCode, Currency

response = api.create_payment({
    'payer': {
        'contact': {
            'first_name': 'Zbynek',
            'last_name': 'Zak',
            'email': 'test@test.cz',
            'phone_number': '+420777456123',
            'city': 'C.Budejovice',
            'street': 'Plana 67',
            'postal_code': '373 01',
            'country_code': 'CZE',
        },
    },
    'amount': 150,
    'currency': Currency.CZECH_CROWNS,
    'order_number': '001',
    'order_description': 'pojisteni01',
    'items': [
        {'name': 'item01', 'amount': 50},
        {'name': 'item02', 'amount': 100},
    ],
    'preauthorization': True,
    'additional_params': [
        {'name': 'invoicenumber', 'value': '2015001003'}
    ],
    'callback': {
        'return_url': 'http://www.your-url.tld/return',
        'notification_url': 'http://www.your-url.tld/notify'
    }
})
var payment = new BasePayment() 
    {
        PreAuthorize = true,
        ...
    };

try {
    connector.CreatePayment(payment);
} catch (GPClientException ex) {
//
}
BasePayment payment = PaymentFactory.createBasePaymentBuilder()
    .order(<ORDER_NUMBER>, <AMOUNT>, <CURRENCY>, <DESCRIPTION>)
    .addItem(<ITEM_NAME>, <AMOUNT>, <FEE>, <COUNT>)
    .addAdditionalParameter(<Key>, <VALUE>)
    .withCallback(<RETURN_URL>, <NOTIFY_URL>)
    .payer(<Payer>)
    .inLang(Lang.EN)
    .toEshop(<GO_ID>)
    .preauthorize()
    .build();
try {
    Payment result = connector.createPayment(payment);
} catch (GPClientException e) {
     for (ErrorElement err : e.getError().getErrorMessages()) {
        int code = err.getErrorCode();
        String message = err.getMessage();
        String field = err.getField();
    }
}
{
  "id":3000006542,
  "order_number":"001",
  "state":"CREATED",
  "amount":1000,"currency":"CZK",
  "payer":{
           "contact":{"first_name":"Zbynek",
                      "last_name":"Zak",
                      "email":" test@test.cz ",
                      "phone_number":"+420777456123",
                      "city":"C.Budejovice",
                      "street":"Plana 67",
                      "postal_code":"37301",
                      "country_code":"CZE"
                    }
          },
  "target":{"type":"ACCOUNT",
            "goid":8123456789
          },
  "preauthorization":{"requested":true,
                      "state":"REQUESTED"
                    },
  "additional_params":[{"name":"invoicenumber",
                        "value":"2015001003"
                      }],
  "lang":"cs",
  "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF "
}
Capturing a preauthorized payment
POST /api/payments/payment/{id}/capture

The functionality enables the capture of preauthorized funds previously created by preauthorized payment.

For a detailed description of the steps required to make a pre-authorized payment, please visit our Help Center.

Path variables

id
string required

Pre-Authorized payment ID

Request headers

Accept
string required

Always application/json

Example:
application/json
Content-Type
string required

Always application/x-www-from-urlencoded

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

String “Bearer” followed by the access token

Example:
Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006542
result

Result of the operation

Example:
FINISHED
HTTP
cURL
PHP
Python
.NET
Java
Response
POST /api/payments/payment/3000006542/capture HTTP/1.1 

Accept: application/json
Content-Type: application/x-www-from-urlencoded
Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
curl -X POST "/api/payments/payment/3000006542/capture"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/x-www-from-urlencoded"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"
<?php
$response = $gopay->captureAuthorization(3000006542);
response = api.capture_authorization(3000006542)
try {
    var capture = connector.CapturePayment(<ID>);
} catch (GPClientException ex) {
//
}    
try {
    PaymentResult capture = connector.capturePayment(<ID>);
} catch (GPClientException ex) {
    //
}
{
    "id": 3000006542,
    "result": "FINISHED"
}
Partially capturing a preauthorized payment
POST /api/payments/payment/{id}/capture

The functionality enables partial charging of pre-authorized funds previously created by preauthorized payment. The rest of blocked amount is unblocked back to customer’s payment card.

Required amount of capture must not has to be bigger then the original amount of pre-authorized payment.

Additional information about pre-authorized payments you can find in the Help Center.

ⓘ To activate partial charge of pre-authorized payments functionality, please, contact technical support GoPay.

Path variables

id
string required

Pre-Authorized 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

String “Bearer” followed by the access token

Example:
Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

Request body

Object
amount
integer

Payment amount in cents

Example:
30000
items
Array of Item

Details of the payment items

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006542
result

Result of the operation

Example:
FINISHED
HTTP
cURL
PHP
Python
Response
POST /api/payments/payment/3000006542/capture HTTP/1.1 

Accept: application/json
Content-Type: application/json
Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

{
    "amount": 119990,
    "items": [
        {
            "type": "ITEM",
            "name": "Obuv",
            "amount": 119990,
            "count": 1,
            "vat_rate": "15",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.cz/boty/lodicky"
        }
    ]
}
curl -X POST "/api/payments/payment/3000006542/capture"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/json"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"  \
 -d '{
    "amount": 119990,
    "items": [
        {
            "type": "ITEM",
            "name": "Obuv",
            "amount": 119990,
            "count": 1,
            "vat_rate": "15",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.cz/boty/lodicky"
        }
    ]
}'
...
response = api.capture_authorization_partial(3000006542,
    {
        "amount": 1500,
        'items': [
            {'name': 'item01', 'amount': 500},
            {'name': 'item02', 'amount': 1000},
        ],
    })
{
    "id": 3000006542,
    "result": "FINISHED"
}
Cancelling a preauthorized payment
POST /api/payments/payment/{id}/void-authorization

Releases the pre-authorization funds of the previously created preauthorized payment.

Additional information about pre-authorized payments you can find in the Help Center.

Path variables

id
string required

Pre-authorized payment ID

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

String “Bearer” followed by the access token

Example:
Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

Responses

200 OK
Body
Object
id
integer

Payment ID

Example:
3000006542
result

Result of the operation

Example:
FINISHED
HTTP
cURL
PHP
Python
.NET
Java
Response
POST /api/payments/payment/3000006542/void-authorization HTTP/1.1 

Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
curl -X POST "/api/payments/payment/3000006542/void-authorization"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/x-www-form-urlencoded"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"
<?php
$response = $gopay->voidAuthorization(3000006542);
response = api.void_authorization(3000006542)
try {
    var result = connector.VoidAuthorization(<ID>);
} catch (GPClientException ex) {
//
}
try {
    PaymentResult voidAuthorization = connector.voidAuthorization(<ID>);
} catch (GPClientException ex) {
     for (ErrorElement err : e.getError().getErrorMessages()) {
        int code = err.getErrorCode();
        String message = err.getMessage();
        String field = err.getField();
    }           
}
{
    "id": 3000006542,
    "result": "FINISHED"
}
Indentification service

Identification payment by payment card makes it possible to ensure that the customer will make payments on the e-shop with a payment card to which he has active access and can authorize payments with that payment card. Functionality also ensures the uniqueness of a given payment card within a specific e-shop (GoID).

ⓘ To activate the identification payment function, it is necessary to [contact](mailto: integration@gopay.cz) GoPay technical support.

Initiating payment

The request for creation of verification payment is based on standard payment creation. The verification payment uses added parameter verify_pin. When the payment is made the value of verify_pin parameter is available at transaction list in customer’s internet banking connected with the payment card. The e-shop can require fill in the value of verification PIN to authorize the payment card’s owner.

When the payment is created as pre-authorized you need to make charge or cancellation of pre-authorized payment.

HTTP
cURL
PHP
Python
Response
POST /api/payments/payment HTTP/1.1 

Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
Content-Type: application/json
Accept: application/json

{
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
        ],
        "default_payment_instrument": "PAYMENT_CARD"
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        },
        "verify_pin": "1234"
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Obuv",
            "amount": 119990,
            "count": 1,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.cz/boty/lodicky"
        }
    ],
    "amount": 119990,
    "currency": "CZK",
    "order_number": "OBJ20200825",
    "order_description": "Obuv",
    "lang": "CS",
    "callback": {
        "return_url": "https://www.example.com/return",
        "notification_url": "https://www.example.com/notify"
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"  \
 -H "Content-Type: application/json"  \
 -H "Accept: application/json"  \
 -d '{
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        },
        "verify_pin": "1234"
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Obuv",
            "amount": 119990,
            "count": 1,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.cz/boty/lodicky"
        }
    ],
    "amount": 119990,
    "currency": "CZK",
    "order_number": "OBJ20200825",
    "order_description": "Obuv",
    "lang": "CS",
    "callback": {
        "return_url": "https://www.example.com/return",
        "notification_url": "https://www.example.com/notify"
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}'
<?php
use GoPay\Definition\Language;
use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Payment\PaymentInstrument;
use GoPay\Definition\Payment\BankSwiftCode;
use GoPay\Definition\Payment\VatRate;
use GoPay\Definition\Payment\PaymentItemType;

$response = $gopay->createPayment([
    'payer' => [
            'default_payment_instrument' => PaymentInstrument::PAYMENT_CARD,
            'allowed_payment_instruments' => [PaymentInstrument::PAYMENT_CARD],
            'contact' => ['first_name' => 'Zbynek',
                    'last_name' => 'Zak',
                    'email' => 'test@test.cz',
                    'phone_number' => '+420777456123',
                    'city' => 'C.Budejovice',
                    'street' => 'Plana 67',
                    'postal_code' => '373 01',
                    'country_code' => 'CZE'
            ],
            'verify_pin' => '1234'
    ],
    'amount' => 139951,
    'currency' => Currency::CZECH_CROWNS,
    'order_number' => '001',
    'order_description' => 'obuv',
    'items' => [[
            'type' => 'ITEM',
            'name' => 'obuv',
            'product_url' => 'https://www.eshop.cz/boty/lodicky',
            'ean' => 1234567890123,
            'amount' => 119990,
            'count' => 1,
            'vat_rate' => VatRate::RATE_4
    ],
            [
            'type' => PaymentItemType::ITEM,
            'name' => 'oprava podpatku',
            'product_url' => 'https://www.eshop.cz/boty/opravy',
            'ean' => 1234567890189,
            'amount' => 19961,
            'count' => 1,
            'vat_rate' => VatRate::RATE_3
            ]],
    'eet' => [
            'celk_trzba' => 139951,
            'zakl_dan1' => 99160,
            'dan1' => 20830,
            'zakl_dan2' => 17358,
            'dan2' => 2603,
            'mena' => Currency::CZECH_CROWNS
    ],
    'additional_params' => [['name' => 'invoicenumber',
            'value' => '2015001003'
    ]],
    'callback' => [
            'return_url' => 'https://www.eshop.cz/return',
            'notification_url' => 'https://www.eshop.cz/notify'
    ],
    'lang' => Language::CZECH
]);
from gopay.enums import PaymentInstrument, BankSwiftCode, Currency

response = api.create_payment({
    'payer': {
        'default_payment_instrument': PaymentInstrument.PAYMENT_CARD,
        'allowed_payment_instruments': [PaymentInstrument.PAYMENT_CARD],
        'contact': {
            'first_name': 'Zbynek',
            'last_name': 'Zak',
            'email': 'test@test.cz',
            'phone_number': '+420777456123',
            'city': 'C.Budejovice',
            'street': 'Plana 67',
            'postal_code': '373 01',
            'country_code': 'CZE',
        },
        'verify_pin': "1234"
    },
    'amount': 139951,
    'currency': Currency.CZECH_CROWNS,
    'order_number': '001',
    'order_description': 'pojisteni01',
    'items': [
        {'name': 'item01', 'amount': 119990},
        {'name': 'item02', 'amount': 19961},
    ],
    'additional_params': [
        {'name': 'invoicenumber', 'value': '2015001003'}
    ],
    'callback': {
        'return_url': 'http://www.your-url.tld/return',
        'notification_url': 'http://www.your-url.tld/notify'
    }
})
{
    "id": 3000006529,
    "order_number": "OBJ20200825",
    "state": "CREATED",
    "amount": 139950,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ],
    "lang": "CS",
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}
Initiating payment status

The request is performed by the standard call for check payment status. In the payer object, there is also a payment_card object, describing the used payment card, and in it card_token is passed, containing a unique identifier of the used card within the given eshop (for one goid).

Response
{
    "id": 3000006529,
    "order_number": "OBJ20200825",
    "state": "PAID",
    "amount": 139950,
    "currency": "CZK",
    "payment_instrument": "PAYMENT_CARD",
   "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
            "BANK_ACCOUNT"
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "allowed_swifts": [
            "FIOBCZPP",
            "BREXCZPP"
        ],
        "default_swift": "FIOBCZPP",
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        },
        "payment_card": {
            "card_number": "444444******4448",
            "card_expiration": "1909",
            "card_brand": "VISA",
            "card_issuer_country": "CZE",
            "card_issuer_bank": "AIR BANK, A.S.",
            "3ds_result": "Y/Y",
            "card_token": "6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcb"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ],
    "lang": "CS",
    "gw_url": " https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}
Verification payment

The request to create a subsequent payment using verification is based on the requirement create standard payment, which is extended by the parameter allowed_card_token. The payment can only be paid with the card with which the initiating payment was paid and whose token was returned in the payment status request from the previous step.

HTTP
cURL
PHP
Python
Response
POST /api/payments/payment HTTP/1.1 

Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
Content-Type: application/json
Accept: application/json

{
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
        ],
        "default_payment_instrument": "PAYMENT_CARD"
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        },
        "allowed_card_token": "6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcb"
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Obuv",
            "amount": 119990,
            "count": 1,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.cz/boty/lodicky"
        }
    ],
    "amount": 119990,
    "currency": "CZK",
    "order_number": "OBJ20200825",
    "order_description": "Obuv",
    "lang": "CS",
    "callback": {
        "return_url": "https://www.example.com/return",
        "notification_url": "https://www.example.com/notify"
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"  \
 -H "Content-Type: application/json"  \
 -H "Accept: application/json"  \
 -d '{
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        },
        "allowed_card_token": "6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcb"
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Obuv",
            "amount": 119990,
            "count": 1,
            "vat_rate": "21",
            "ean": 1234567890123,
            "product_url": "https://www.eshop.cz/boty/lodicky"
        }
    ],
    "amount": 119990,
    "currency": "CZK",
    "order_number": "OBJ20200825",
    "order_description": "Obuv",
    "lang": "CS",
    "callback": {
        "return_url": "https://www.example.com/return",
        "notification_url": "https://www.example.com/notify"
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ]
}'
<?php
use GoPay\Definition\Language;
use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Payment\PaymentInstrument;
use GoPay\Definition\Payment\BankSwiftCode;
use GoPay\Definition\Payment\VatRate;
use GoPay\Definition\Payment\PaymentItemType;

$response = $gopay->createPayment([
    'payer' => [
            'default_payment_instrument' => PaymentInstrument::PAYMENT_CARD,
            'allowed_payment_instruments' => [PaymentInstrument::PAYMENT_CARD],
            'contact' => ['first_name' => 'Zbynek',
                    'last_name' => 'Zak',
                    'email' => 'test@test.cz',
                    'phone_number' => '+420777456123',
                    'city' => 'C.Budejovice',
                    'street' => 'Plana 67',
                    'postal_code' => '373 01',
                    'country_code' => 'CZE'
            ],
            'allowed_card_token' => '6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcb'
    ],
    'amount' => 139951,
    'currency' => Currency::CZECH_CROWNS,
    'order_number' => '001',
    'order_description' => 'obuv',
    'items' => [[
            'type' => 'ITEM',
            'name' => 'obuv',
            'product_url' => 'https://www.eshop.cz/boty/lodicky',
            'ean' => 1234567890123,
            'amount' => 119990,
            'count' => 1,
            'vat_rate' => VatRate::RATE_4
    ],
            [
            'type' => PaymentItemType::ITEM,
            'name' => 'oprava podpatku',
            'product_url' => 'https://www.eshop.cz/boty/opravy',
            'ean' => 1234567890189,
            'amount' => 19961,
            'count' => 1,
            'vat_rate' => VatRate::RATE_3
            ]],
    'eet' => [
            'celk_trzba' => 139951,
            'zakl_dan1' => 99160,
            'dan1' => 20830,
            'zakl_dan2' => 17358,
            'dan2' => 2603,
            'mena' => Currency::CZECH_CROWNS
    ],
    'additional_params' => [['name' => 'invoicenumber',
            'value' => '2015001003'
    ]],
    'callback' => [
            'return_url' => 'https://www.eshop.cz/return',
            'notification_url' => 'https://www.eshop.cz/notify'
    ],
    'lang' => Language::CZECH
]);
from gopay.enums import PaymentInstrument, BankSwiftCode, Currency

response = api.create_payment({
    'payer': {
        'default_payment_instrument': PaymentInstrument.PAYMENT_CARD,
        'allowed_payment_instruments': [PaymentInstrument.PAYMENT_CARD],
        'contact': {
            'first_name': 'Zbynek',
            'last_name': 'Zak',
            'email': 'test@test.cz',
            'phone_number': '+420777456123',
            'city': 'C.Budejovice',
            'street': 'Plana 67',
            'postal_code': '373 01',
            'country_code': 'CZE',
        },
        'allowed_card_token': '6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcb'
    },
    'amount': 139951,
    'currency': Currency.CZECH_CROWNS,
    'order_number': '001',
    'order_description': 'pojisteni01',
    'items': [
        {'name': 'item01', 'amount': 119990},
        {'name': 'item02', 'amount': 19961},
    ],
    'additional_params': [
        {'name': 'invoicenumber', 'value': '2015001003'}
    ],
    'callback': {
        'return_url': 'http://www.your-url.tld/return',
        'notification_url': 'http://www.your-url.tld/notify'
    }
})
{
    "id": 3000006529,
    "order_number": "OBJ20200825",
    "state": "CREATED",
    "amount": 139950,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "contact": {
            "first_name": "Zbyněk",
            "last_name": "Žák",
            "email": "test@test.cz",
            "phone_number": "+420777456123",
            "city": "České Budějovice",
            "street": "Planá 67",
            "postal_code": "37301",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "additional_params": [
        {
            "name": "invoicenumber",
            "value": "2015001003"
        }
    ],
    "lang": "CS",
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}
Payment methods

You can make additional operations with payment methods, e.g. get a list of allowed payment methods that you can offer to your customers in e-shop’s shopping cart.

ⓘ You can find recommended payment method selection in our Help Center.

GET /api/eshops/eshop/{goid}/payment-instruments/{currency}
Allowed payment methods
GET /api/eshops/eshop/{goid}/payment-instruments/{currency}

The method returns the JSON structure of all allowed payment methods on the eshop profile. In the URL of the request it is necessary to pass the GoID of the requested e-shop and the currency code.

Path variables

goid
string required
currency
string required

Request headers

Accept
string required

Always application/json

Example:
application/json
Authorization
string required

String “Bearer” followed by the access token

Example:
Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

Responses

200 OK
Body
Object
groups

Descriptions of groups of payment methods

enabledPaymentInstruments

List of allowed payment methods for the given currency on the e-shop, their labels and logos

HTTP
cURL
PHP
Python
Response
GET /api/eshops/eshop/8123456789/payment-instruments/CZK HTTP/1.1 

Accept: application/json
Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
curl -X GET "/api/eshops/eshop/8123456789/payment-instruments/CZK"  \
 -H "Accept: application/json"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"
...
...
{
"groups":{
    "card-payment":{
        "label":{
            "cs":"Platební karta"}
        },
    "bank-transfer":{
        "label":{
            "cs":"Rychlý bankovní převod"}
        },
    "wallet":{
        "label":{
            "cs":"Elektronické peněženky"}
        },
    "others":{
        "label":{
            "cs":"Ostatní"}
        }
    },
"enabledPaymentInstruments":[{
    "paymentInstrument":"PAYMENT_CARD",
        "label":{
            "cs":"Platební karta"
        },
        "image":{
            "normal":"https://gate.gopay.cz/images/checkout/payment_card.png",
            "large":"https://gate.gopay.cz/images/checkout/payment_card@2x.png"},
        "group":"card-payment",
        "enabledSwifts":null
        },
    {"paymentInstrument":"BANK_ACCOUNT",
        "label":{
            "cs":"Rychlý bankovní převod"},
        "image":{
            "normal":"https://gate.gopay.cz/images/checkout/bank_account.png",
            "large":"https://gate.gopay.cz/images/checkout/bank_account@2x.png"},
        "group":"bank-transfer",
        "enabledSwifts":[{
            "swift":"GIBACZPX",
                "label":{"cs":"Platba 24"},
                "image":{
                    "normal":"https://gate.gopay.cz/images/checkout/GIBACZPX.png",
                    "large":"https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png"},
                "isOnline":true},
    ...]},
]}
Payment gateway

To invoke the payment gateway, it is possible to use the HTML form, which will use Javascript to initialize the payment gateway.

You can find a detailed description of all the steps required to call up the payment gateway in our Help Center.

Inline

Inline payment gateway is initiated directly above the point of sale, there is no redirection.

URL (action) form set according to gw_url from creation of the payment.

ⓘ The inline payment gateway in points of sale is available only with SSL certificate support (run on HTTPS). In points of sale that don´t have SSL certificate support is automatically performed redirect option described bellow.

HTML

Formulář pro vyvolání Inline platební brány

<form action="https://gw.sandbox.gopay.com/gw/v3/dfgvmwTKK5hrJx2aGG8ZnFyBJhAvF" method="post" id="gopay-payment-button">
  <button name="pay" type="submit">Zaplatit</button>
  <script type="text/javascript" src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js"></script>
</form>
Redirect

The payment gateway can also be operated in the option with Redirect. You can use the form below or redirect to the URL (gw_url) obtained during creation of the payment.

HTML

Formulář pro přesměrování na Redirect platební bránu

<form action="https://gw.sandbox.gopay.com/gw/v3/dfgvmwTKK5hrJx2aGG8ZnFyBJhAvF" method="post">
  <button name="pay" type="submit">Zaplatit</button>
</form>
Merchant account

GoPay merchant account is a basic tool to view and check all your payments within the GoPay payment system. REST API functions allow you to e.g. generate movement statement from GoPay merchant account.

POST /api/accounts/account-statement
Account statement
POST /api/accounts/account-statement

The funcionality generates statements from GoPay business account. It returns content of account statement file. More information about file types specification you can find in Help Center.

Request headers

Accept
string required

Always application/json

Example:
application/json
Content-Type
string required

Always application/json

Example:
application/json
Authorization
string required

String “Bearer” followed by the access token

Example:
Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

Request body

Object
date_from
string date

Statement start date

Example:
2021-07-08
date_to
string date

Statement end date

Example:
2021-08-08
goid
integer

Unique identifier of an e-shop in the payment gateway system

Example:
8123456789
currency

Specifies the currency, format corresponds to ISO 4217

Example:
CZK
format

Specifies format type of generated statement

Example:
CSV_A

Responses

200 OK

As the body of the response, the contents of the listing are returned as application / octet-stream

application/octet-stream
HTTP
cURL
POST /api/accounts/account-statement HTTP/1.1 

Accept: application/json
Content-Type: application/json
Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969

{
    "date_from": "2020-07-08",
    "date_to": "2020-08-08",
    "goid": 8123456789,
    "currency": "CZK",
    "format": "CSV_A"
}
curl -X POST "/api/accounts/account-statement"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/json"  \
 -H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"  \
 -d '{
    "date_from": "2020-07-08",
    "date_to": "2020-08-08",
    "goid": 8123456789,
    "currency": "CZK",
    "format": "CSV_A"
}'
Objects
Target

Identification of the payee

Object
type
string

always ACCOUNT

Example:
ACCOUNT
goid
integer

Unique identifier of an e-shop in the payment gateway system

Example:
8123456789
Item

Payment item

Object
type
Type required

Type of row, for registration of sales

Example:
ITEM
name
string required

Product name

Max length: 256
Example:
Obuv
amount
integer required

Total price of items in cents

Example:
119990
count
integer

Number of items

Min: 1
Example:
2
vat_rate
integer

VAT rate

Min: 0
Max: 100
ean
integer

EAN code of the product

Example:
1234567890123
product_url
string

URL address of the product

Max length: 512
Example:
https://www.eshop.cz/boty/lodicky
Contact

Customer´s information

Object
first_name
string

First name

Max length: 256
Example:
John
last_name
string

Last name

Max length: 256
Example:
Doe
email
string

Valid e-mail

Max length: 128
Example:
test@test.cz
phone_number
string

Phone number with country code

Max length: 128
Example:
+420777456123
city
string

City

Max length: 128
Example:
České Budějovice
street
string

Street

Max length: 128
Example:
Planá 67
postal_code
string

Postal code

Max length: 16
Example:
37301
country_code
string

Country code ISO 3166-1 alpha-3

Example:
CZE
Types: Payer
Payer

An object describing customer information and setting payment methods for a given payment. The payment_card andbank_account objects are returned in the payment status check if the client has paid for this method. The verify_pin andallowed_card_token parameters are used only for identification payment. The email parameter directly in thepayer object is returned only for the GOPAY payment method and it is the e-mail of the used wallet.

Object
allowed_payment_instruments

Array of allowed payment methods

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

Preferred payment method

Example:
BANK_ACCOUNT
allowed_swifts
Array of Swift

Array of allowed bank codes

Example:
["FIOBCZPP","BREXCZPP"]
default_swift

Preferred bank if default_payment_instrument is set to BANK_ACCOUNT, set by SWIFT code

Example:
FIOBCZPP
contact

Customer´s data

bank_account
Bank account read-only

Bank account´s information

payment_card
Payment card read-only

Payment card´s information

verify_pin
string

PIN for identification payment purposes

Example:
1234
allowed_card_token
string

Token for identification payment purposes

Example:
6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcb
email
string

Email of used GoPay wallet (only for GOPAY payment method)

Example:
test@test.cz
Callback

Definition of callback and notification URL

Object
return_url
string

URL address for return to e-shop (with protocol)

Max length: 512
Example:
https://www.example.com/return
notification_url
string

URL address for sending asynchronous notification in the case of changes in the payment status (with protocol)

Max length: 512
Example:
https://www.example.com/notify
Payment card

An object that describes credit card information. Read-only, returned in payment status query if customer paid by card. The card_token and3ds_result parameters are passed only for the status check identification payments

Object
card_number
string

Masked payment card´s number

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

Expiration date

Example:
1909
card_brand
string

Payment card´s type

Example:
VISA
card_issuer_country
string

Country code of issuing bank

Example:
CZE
card_issuer_bank
string

Issuing bank

Example:
AIR BANK, A.S.
card_token
string

Token for identification payment purposes

Example:
6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcb
3ds_result

3D Secure authorization’s result for identification payment purposes

Example:
Y/Y
Types: Payer
Bank account

Payer’s bank account details. Read-only, returned in payment status check if client paid by account. IBAN and SWIFT are transferred only for payments outside the Czechia and Slovakia.

Object
iban
string

International bank account number

Example:
SK4202006700000007654322
bic
string

Business identification code (SWIFT)

Example:
SUBASKPP
prefix
string

Bank account prefix

Example:
670100
account_number
string

Bank account number

Example:
7654322
bank_code
string

Bank account code

Example:
0200
account_name
string

Bank account name

Example:
JOHN DOE
Types: Payer
Additional param

Additional parameters of the payment

Object
name
string

Parameter name

Example:
invoicenumber
value
string

Value of optional parameter

Example:
2015001003
Recurrence

An object describing a recurring payment. The recurrence_period parameter is not passed for recurring ON_DEMAND payment. The recurrence_state parameter is returned in the payment status check.

Object
recurrence_cycle

Time period of recurring

Example:
MONTH
recurrence_period
integer

Recurring period of recurring payment

Example:
12
recurrence_date_to
string date

The period of validity recurring payment

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

Describes state of recurring payment

Example:
STARTED
Preauthorization

Objekt popisující předautorizaci platby

Object
requested
boolean

Whether the pre-authorization was established

Example:
true

Payment pre-authorization status

Example:
REQUESTED
Group code

Names of payment method groups

Object
label
Object

Payment method

cs
string

Payment method name in Czech

Example:
Platební karta
Types: Groups
Groups

Names of payment method groups

Object
card-payment

Payment card payments

bank-transfer

Bank transfers

wallet

E-wallet payments

others

Other payment methods

Enabled swift

Popisuje povolené swifty pro bankovní převody.

Object
image
Object

Bank logos

large
string

Large icon URL

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

Normal icon URL

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

State that symbolise if bank supports online bank transfers

Example:
true
label
Object

Object that contains localised name of bank

cs
string

Czech description

Example:
Platba 24
swift
string

SWIFT code

Example:
GIBACZPX
Enabled payment instrument

Name of every object coresponds to payment method codes

Object
enabledSwifts
Array of Enabled swift nullable

A series of objects describing each allowed SWIFTs (for bank transfers only)

group

Which group does the payment method belong to

Example:
card-payment
image
Object

Payment methods icons

large
string

Large icon URL

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

Normal icon URL

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

Payment method name

cs
string

Czech label

Example:
Platební karta
paymentInstrument

Designation of the payment method within the API

Example:
PAYMENT_CARD
Enumerations

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

United States dollar

GBP

Pound sterling

HUF

Hungarian forint

RON

Romanian lei

BGN

Bulgarian lev

HRK

Croatian kuna

Payment instrument

List of available payment methods

string
Enumeration:
PAYMENT_CARD

Payment card

BANK_ACCOUNT

Bank account

GPAY

Google Pay

APPLE_PAY

Apple Pay

GOPAY

GoPay wallet

PAYPAL

PayPal wallet

MPAYMENT

mPlatba (mobile payment)

PRSMS

Premium SMS

PAYSAFECARD

PaySafeCard coupon

BITCOIN

Bitcoin wallet

Swift

List of available SWIFT/BIC codes.

string
Enumeration:
GIBACZPX

Česká Spořitelna

KOMBCZPP

Komerční Banka

RZBCCZPP

Raiffeisenbank

FIOBCZPP

FIO Banka

BACXCZPP

UniCredit Bank

BREXCZPP

mBank

CEKOCZPP

ČSOB

CEKOCZPP-ERA

Poštovní Spořitelna

AGBACZPP

Moneta Money Bank

AIRACZPP

AirBank

EQBKCZPP

EQUA Bank

INGBCZPP

ING Bank

EXPNCZPP

Expobank

OBKLCZ2X

OberBank AG

VBOECZ2X

Sberbank CZ

SUBACZPP

Všeobecná Úvěrová Banka - pobočka Praha

BPPFCZP1

Hello! Bank

TATRSKBX

Tatra Banka

SUBASKBX

Všeobecná Úverová Banka

UNCRSKBX

UniCredit Bank SK

GIBASKBX

Slovenská Sporiteľňa

POBNSKBA

Poštová Banka

OTPVSKBX

OTP Banka

KOMASK2X

Prima Banka

CITISKBA

Citibank Europe

FIOZSKBA

FIO Banka SK

INGBSKBX

ING Wholesale Banking SK

BREXSKBX

mBank SK

JTBPSKBA

J&T Banka SK

OBKLSKBA

OberBank AG SK

BSLOSK22

Privatbanka

BFKKSKBB

BKS Bank AG SK

GBGCPLPK

Getin Bank

NESBPLPW

Nest Bank

VOWAPLP9

Volkswagen Bank

CITIPLPX

Citi handlowy

WBKPPLPP

Santander

BIGBPLPW

Millenium Bank

EBOSPLPW

Bank Ochrony Srodowiska

PKOPPLPW

Pekao Bank

PPABPLPK

BNP Paribas

BPKOPLPW

OWSZECHNA KASA OSZCZEDNOSCI BANK POLSK

AGRIPLPR

Credit Agricole Banka Polska

GBGCPLPK-NOB

Noble Bank

POLUPLPR

BPS/Bank Nowy BFG

BREXPLPW

mBank PL

INGBPLPW

ING Bank PL

ALBPPLPW

Alior

IEEAPLPA

IdeaBank

POCZPLP4

Pocztowy24

IVSEPLPP

Plus Bank

TOBAPLPW

Toyota Bank

Types: Payer
State

List of possible payment states

string
Enumeration:
CREATED

Payment created

PAID

Payment has already been paid

CANCELED

Payment declined

PAYMENT_METHOD_CHOSEN

Payment method confirmed

TIMEOUTED

The payment has expired

AUTHORIZED

Payment pre-authorized

REFUNDED

Payment refunded

PARTIALLY_REFUNDED

Payment partially refunded

Substate

List of payment bases

string
Enumeration:
_101

We are waiting for an online payment.

_102

We are waiting for an offline payment.

_3001

Bank payment confirmed by advice.

_3002

Bank payment confirmed by statement.

_3003

Bank payment was not confirmed.

_5001

Approved with zero amount

_5002

Rejection of the payment in the authorization center of the customer’s bank due to reaching the limits on the payment card.

_5003

Refusal of payment in the authorization center of the customer’s bank due to problems on the part of the payment card issuer.

_5004

Rejection of the payment in the authorization center of the customer’s bank due to a problem on the part of the payment card issuer.

_5005

Rejection of the payment in the authorization center of the customer’s bank due to a blocked payment card.

_5006

Refusal of payment in the authorization center of the customer’s bank due to lack of funds on the payment card.

_5007

Rejection of the payment in the authorization center of the customer’s bank due to the expired payment card.

_5008

Rejection of payment in the authorization center of the customer’s bank due to rejection of the CVV/CVC code.

_5009

Rejection of payment in the customer’s 3D Secure bank system.

_5015

Rejection of payment in the customer’s 3D Secure bank system.

_5017

Rejection of payment in the customer’s 3D Secure bank system.

_5018

Rejection of payment in the customer’s 3D Secure bank system.

_5019

Rejection of payment in the customer’s 3D Secure bank system.

_6502

Rejection of payment in the customer’s 3D Secure bank system.

_6504

Rejection of payment in the customer’s 3D Secure bank system.

_5010

Rejection of the payment in the authorization center of the customer’s bank due to problems on the payment card.

_5014

Rejection of the payment in the authorization center of the customer’s bank due to problems on the payment card.

_5011

Rejection of the payment in the authorization center of the customer’s bank due to problems on the payment card.

_5036

Rejection of the payment in the authorization center of the customer’s bank due to problems on the payment card.

_5012

Rejection of the payment in the authorization center of the customer’s bank due to problems on the payment card.

_5013

Rejection of the payment in the authorization center of the customer’s bank due to problems on the payment card.

_5016

Rejection of the payment in the authorization center of the customer’s bank due to problems on the payment card.

_5020

Unknown configuration

_5021

Rejection of the payment in the authorization center of the customer’s bank due to reaching the set limits on the payment card.

_5022

There was a technical problem associated with the customer’s bank authorization center.

_5023

Payment was not made.

_5038

Payment was not made.

_5024

Payment was not made. Payment details were not entered within the time limit on the payment gateway.

_5025

Payment was not made. The specific reason for rejection is communicated directly to the customer.

_5026

Payment was not made. The sum of the credited amounts exceeded the amount paid.

_5027

Payment was not made. The user is not authorized to perform the operation.

_5028

Payment was not made. The amount to be paid exceeded the authorized amount.

_5029

Payment has not been made yet.

_5030

The payment was not made due to a re-entry.

_5031

There was a technical problem with the payment on the part of the bank.

_5033

SMS could not be delivered.

_5035

The payment card is issued in a region where card payments are not supported.

_5037

The credit card holder canceled the payment.

_5039

The payment was declined at the customer’s bank authorization center due to a blocked credit card.

_5040

Duplicate reversal transactions

_5041

Duplicate transactions

_5042

Bank payment declined.

_5043

Payment canceled by user.

_5044

SMS has been sent. It has not yet been delivered.

_5045

Payment received. Payment will be credited after processing on Bitcoin.

_5046

The payment was not paid in full.

_5047

Payment was made overdue.

_5048

Customer has not given consent for PSD2 payment.

Methods: Payment status
Type

Types of payment possible items

string
Enumeration:
ITEM

Product/service

DELIVERY

Delivery

DISCOUNT

Discount

Types: Item
Scope

Scope of token rights

string
Enumeration:
payment-create

Allows you to create payments only

payment-all

Allows you to perform all operations

Methods: Access token
Lang

Payment gateway interface language

string
Enumeration:
CS

Czech

SK

Slovak

EN

English

DE

German

RU

Russian

PL

Polish

HU

Hungarian

RO

Romanian

BG

Bulgarian

HR

Croatian

IT

Italian

FR

French

ES

Spanish

Result

Description of the result of the operation

string
Enumeration:
ACCEPTED

Request accepted

FINISHED

Operation performed

FAILED

The operation ended in error

Recurrence cycle

Recurring payment cycle

string
Enumeration:
DAY

Daily recurrence period

WEEK

Weekly recurrence period

MONTH

Monthly recurrence period

ON_DEMAND

Recurring payment on demand

Types: Recurrence
Recurrence state

Describes the recurrence status of the payment

string
Enumeration:
REQUESTED

Recurring payment created, waiting for authorization of initial payment

STARTED

Payment recurrence active

STOPPED

Payment recurring canceled

Types: Recurrence
Preauthorization state

Describes the status of payment pre-authorization.

string
Enumeration:
REQUESTED

Pre-authorization created

AUTHORIZED

Pre-authorized

CAPTURED

Pre-authorion captured

CANCELED

Pre-authorization canceled

Format

Format of the generated statement

string
Enumeration:
CSV_A

CSV type A

CSV_B

CSV type B

CSV_C

CSV type C

CSV_D

CSV type D

XLS_A

XLS type A

XLS_B

XLS type B

XLS_C

XLS type C

ABO_A

ABO edit format (.gpc)

ABO_B

ABO internal format (.gpc)

Receipt state

Description of the status of the EET receipt

string
Enumeration:
CREATED

Created

DELIVERY_FAILED

Delivery failed

DELIVERED

Delivered

EET mode

EET variants

string
Enumeration:
AUTO

Option A - calculation on the GoPay side

EET

Option B - calculation on the merchant’s side

3DS result

Result of 3D Secure authorization

string
Enumeration:
N/

The payment card does not support 3D Secure authentication

Y/Y

Full 3D Secure authentication

Y/A

Partial 3D Secure authentication

X/X

3D Secure authentication was not performed

Types: Payment card
Group

Code list of payment method groups.

string
Enumeration:
card-payment

Card payments

bank-transfer

Bank transfers

wallet

E-wallets

others

Other methods

Errors
HTTP Result codes
integer
Enumeration:
200

The call was successful

403

Unauthorized access

404

Non-existent service

409

Validation errors

500

The call ended in error

Error

Object describing the error

Object

Error range

Example:
F
field
string

Which parameter is affected by the error, unless it is a global error

Example:
email
message
string

Localized message. Localization based on Accept-Language in the header. It is set to en-US by default.

Example:
"E-mail already exists."
description
string

Technical description of the error

error_code

Numeric designation of the error type

Example:
112
error_name
string

Code designation of the error type

Example:
NOT_UNIQUE
Error scope

Description of the extent of the error

string
Enumeration:
F

The error concerns a specific parameter

G

Global error

Types: Error
Error code

Error codes describing the reason for the error

integer
Enumeration:
100

System Error

110

Compulsory

111

Wrong format

112

Already exists

113

Cannot be changed

114

Cannot delete

115

Ambiguous

116

Invalid request

200

Unauthorized access

201

The method of assigning rights is not supported

202

Wrong access data

203

PIN access has been disabled

301

Unable to create payment

302

Payment cannot be made

303

Payment in wrong condition

304

Payment not found

305

E-shop has been deactivated

321

The payee cannot accept the payment

330

Payment cannot be refunded

331

Payment cannot be refunded

332

Wrong amount

333

Lack of money in the account

340

Recurring payment failed

341

Recurring payment is not supported

342

Payment recurrence stopped

343

Time limit for recurring payments exceeded

350

Payment hold failed

351

Payment has already been canceled

352

Revocation revocation failed

353

Pre-authorization canceled

360

The sum of the amounts of the order items does not match the payment amount

394

Account not found

Types: Error