MENU
curl php python iOS java android .NET

GoPay REST API documentation

API ENDPOINTS

Test 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

PHP SDK

Python SDK

iOS SDK

JAVA SDK

More info about frameworks integration can be found on our github

ANDROID API

  • https://github.com/gopaycommunity/gopay-android-api
  • Requirements : Android studio/Gradle
  • Installation :
    git clone https://github.com/gopaycommunity/gopay-android-api.git
    cd gopay-android-api
    gradle clean build

  • Artifacts are located in the maven jcenter repository

  • model classes, connector
    compile 'cz.gopay:androidapi:1.0.1'

  • webview (in a case you would like to use our module gopay-ui register its activity into your android application manifest)
    compile 'cz.gopay:androidui:1.0.1'

.NET API

  • 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;

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.

OAuth

GoPay uses REST API for authorization of the access to API principal OAuth2.0, in specific method of client authentication, see http://tools.ietf.org/html/rfc6749#section-4.4

Access 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 <Client ID>:<Client Secret>. 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.

Request

POST /api/oauth2/token

Request

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 "<Client ID>:<Client Secret>" \
-d "grant_type=client_credentials&scope=payment-create"

<?php
$gopay = GoPay\payments([
    'goid' => '...',
    'clientId' => '...',
    'clientSecret' => '...',
    'isProductionMode' => false,
    'scope' => GoPay\Definition\TokenScope::ALL,
    'language' => GoPay\Definition\Language::ENGLISH,
    'timeout' => 30
]);
// token is retrieved automatically, you don't have to call some method `getToken`

import gopay

api = gopay.payments({
    'goid': '8302931681',
    'clientId': '1061399163',
    'clientSecret': 'stDTmVXF',
    'isProductionMode': False,
    'scope': gopay.TokenScope.ALL,
    'language': gopay.Language.ENGLISH,
    'timeout': 30
})
# token is retrieved automatically, you don't have to call some method `get_token`

#import <GPAPI.h>
[[GPAPI sharedAPI] setClientID:@"..." clientSecret:@"..." productionMode:NO];
// token is retrieved automatically, you don't have to call some method `getToken`
// For example you can call this in - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions v AppDelegate

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

IGPConnector connector = GPAndroidConnector.build(<API_URL>);
connector.getAppToken(<CLIENT_ID>,<CLIENT_CREDENTIALS>);

var connector = new GPConnector(<API_URL>,<USER_ID>, <USER_SECRET>);
connector.GetAppToken();   

Header of the request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization HTTP basic authentication which is set as <Client ID>:<Client Secret> YES

Body of the request

Parameter’s name Parameter’s description Required
scope Defines a category of functionalities that can operate a given action YES
grant_type client_credentials YES

Response

<?php
// information about caching access tokens:
// https://github.com/gopaycommunity/payments-sdk-php#cache-access-token

# information about caching access tokens:
# https://github.com/gopaycommunity/payments-sdk-php#cache-access-token

{
    "token_type":"bearer",
    "access_token":"AAAnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p",
    "expires_in":1800
}

Response

Parameter’s name Parameter’s description Required
token_type bearer YES
access_token Access token YES
expires_in Token expiry time in seconds YES

Establishment of payment

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 object target. You can get it, when you integrate the payment gateway for identification of specific point of sale, e.g. www.goshop.cz.

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.

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

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer xzZnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p" \
-d '{
    "payer": {
                "default_payment_instrument":"BANK_ACCOUNT",
                "allowed_payment_instruments":["BANK_ACCOUNT"],
                "default_swift":"FIOBCZPP",
                "allowed_swifts":["FIOBCZPP","BREXCZPP"],
                "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"
                          }
              },
    "target": {
                "type":"ACCOUNT",
                "goid":"8123456789"
              },
    "amount":"1000",
    "currency":"CZK",
    "order_number":"001",
    "order_description":"pojisteni01",
    "items":[{"name":"item01","amount":"500"},
             {"name":"item02","amount":"500"}
            ],
    "additional_params":[{"name":"invoicenumber",
                          "value":"2015001003"
                        }],
    "callback":{
                "return_url":"http://www.eshop.cz/return",
                "notification_url":"http://www.eshop.cz/notify"
              },
    "lang":"en"
}'

<?php
use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Payment\PaymentInstrument;
use GoPay\Definition\Payment\BankSwiftCode;

$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' => 1000,
    'currency' => Currency::CZECH_CROWNS,
    'order_number' => '001',
    'order_description' => 'pojisteni01',
    'items' => [
        ['name' => 'item01', 'amount' => 500],
        ['name' => 'item02', 'amount' => 500],
    ],
    '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': {
        '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': 150,
    'currency': Currency.CZECH_CROWNS,
    'order_number': '001',
    'order_description': 'pojisteni01',
    'items': [
        {'name': 'item01', 'amount': 50},
        {'name': 'item02', 'amount': 100},
    ],
    'additional_params': [
        {'name': 'invoicenumber', 'value': '2015001003'}
    ],
    'callback': {
        'return_url': 'http://www.your-url.tld/return',
        'notification_url': 'http://www.your-url.tld/notify'
    }
})

GPPaymentRequest *payment = [[GPPaymentRequest alloc] init];
payment.amount = 20;
payment.currency = @"CZK";
payment.order_number = @"001";
payment.order_description = @"test";

GPPayer *payer = [[GPPayer alloc] init];
payer.allowed_payment_instruments = @[];
payer.default_payment_instrument = @"PAYMENT_CARD";
payer.contact.first_name = @"Zbynek";
payer.contact.last_name = @"Zak";
payer.contact.email = @"test@test.cz";
payer.contact.phone_number = @"+420777456123";
payer.contact.city = @"C.Budejovice";
payer.contact.street = @"Plana 67";
payer.contact.postal_code = @"370 01";
payer.contact.country_code = @"CZE";

payment.payer = payer;

GPTarget *target = [[GPTarget alloc] init];
target.type = PAY_TARGET_ACCOUNT;
target.goid = @"8035442195";

payment.target = target;

[GPAPI sharedAPI] createPayment:payment withHandleSuccess:^(GPPayment *payment) {

} failure:^(NSError *error) {

}];

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();
    }
}

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

}

var payment = new BasePayment()
    {
        Currency = <Currency>,
        Lang = "ENG",
        OrderNumber = "789456167879",
        Amount = 7500,
        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) {
//
}

Request

POST /api/payments/payment

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
payer The object describing the payer of the payment NO Object
target The object describing the target of the payment (payee) YES Object
amount Amount in cents YES long > 0
currency Specifies the currency of payment, currency format corresponds to ISO 4217 YES string
order_number Identification of the order within the point of sale YES string, alphanumeric characters only (128 characters)
order_description Description of goods / service NO string, alphanumeric characters only (256 characters)
items Itemized in detail each item of the order YES Object
callback Callback URL for processing of the payment result / Notification URL for processing of change of payment status YES Object
additional_params Additional payment parameters No According to object
lang Parameters defines language of the payment NO string, can gain values see lang

Response

<?php
if ($response->hasSucceed()) {
    $url = $response->json['gw_url'];
    echo $response;
}

if response.has_succeed():
    url = response.json['gw_url']
    print(response)
{
  "id":3000006529,
  "order_number":"001",
  "state":"CREATED",
  "amount":1000,"currency":"CZK",
  "payer":{
           "default_payment_instrument":"BANK_ACCOUNT",
           "allowed_payment_instruments":["BANK_ACCOUNT"],
           "default_swift":"FIOBCZPP",
           "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
          },
  "additional_params":[{"name":"invoicenumber",
                        "value":"2015001003"
                      }],
  "lang":"en",
  "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}  

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
order_number Identification of order string, alphanumeric characters only (128 characters)
state Payment status string, can gain values see state
amount Amount in cents long > 0
currency Specifies the currency of payment string, can gain values see currency
payer Object describing the payer of the payment Object
target Object describing the target of the payment (payee) Object
additional_params Additional parameters of payments Object array
lang Parameter defines payment language string, can gain values see lang
gw_url URL for initiation of the payment gate string

Pre-authorized payment

Via the credit card, you can block the payment for 4 days using the pre-authorization. Blocked funds can be received by API calling of charge of the pre-authorized payment. Pre-authorized payment can be created by setting of a parameter preauthorization to true .

Additional information about pre-authorized payments you can find in our help center.

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer xzZnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p" \
-d '{
    "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"
                          }
              },
    "target": {"type":"ACCOUNT",
               "goid":"8123456789"
              },
    "amount":"1000",
    "currency":"CZK",
    "order_number":"001",
    "order_description":"pojisteni01",
    "items":[{"name":"item01","amount":"500"},
             {"name":"item02","amount":"500"}],
    "preauthorization":"true",
    "additional_params":[{"name":"invoicenumber",
                          "value":"2015001003"
                        }],
    "callback":{
                "return_url":"http://www.eshop.cz/return",
                "notification_url":"http://www.eshop.cz/notify"
               }
}'

<?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' => 'pojisteni01',
    'items' => [
        ['name' => 'item01', 'amount' => 50],
        ['name' => 'item02', 'amount' => 100],
    ],
    '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'
    }
})

PPaymentRequest *payment = [[GPPaymentRequest alloc] init];
payment.amount = 20;
payment.currency = @"CZK";
payment.order_number = @"001";
payment.order_description = @"test";

GPPayer *payer = [[GPPayer alloc] init];
payer.allowed_payment_instruments = @[];
payer.default_payment_instrument = @"PAYMENT_CARD";
payer.contact.first_name = @"Zbynek";
payer.contact.last_name = @"Zak";
payer.contact.email = @"test@gtest.cz";
payer.contact.phone_number = @"+420777456123";
payer.contact.city = @"C.Budejovice";
payer.contact.street = @"Plana 67";
payer.contact.postal_code = @"370 01";
payer.contact.country_code = @"CZE";

payment.payer = payer;

GPTarget *target = [[GPTarget alloc] init];
target.type = PAY_TARGET_ACCOUNT;
target.goid = @"8035442195";

payment.target = target;

payment.preauthorization = true

[GPAPI sharedAPI] createPayment:payment withHandleSuccess:^(GPPayment *payment) {

} failure:^(NSError *error) {
}];

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();
    }
}

Payment payment = PaymentFactory.createPaymentBuilder().preauthorize()...
try {
    connector.createPayment(payment);
} catch (GPClientException ex) {
    //
}

var payment = new BasePayment() 
    {
        PreAuthorize = true,
        ...
    };

try {
    connector.CreatePayment(payment);
} catch (GPClientException ex) {
//
}

Request

POST /api/payments/payment

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
payer Object describing the payer of the payment NO Object
target Object describing the target of the payment (payee) YES Object
amount Amount in cents YES long > 0
currency Specifies the currency of the payment, currency format corresponding to ISO 4217 YES string, can gain values see currency
order_number Order identification within the point of sale YES string, alphanumeric characters only (128 characters)
order_description Description of goods / service NO string, alphanumeric characters only (256 characters)
items Itemized in detail each item of the order YES Object array
preauthorization Activation of pre-authorized payment YES bool
additional_params Additional parameters of the payment NO Object array
callback Callback URL and notification URL for change in the payment status YES Object

Response

<?php
if ($response->hasSucceed()) {
    $url = $response->json['gw_url'];
    echo $response;
}

if response.has_succeed():
    url = response.json['gw_url']
    print(response)
{
  "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":"en",
  "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF "
}

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
order_number order ID string, alphanumeric characters only (128 characters)
state Payment status string, can gain values see state
amount Amount in cents long > 0
payer Object describing the payer of the payment Object
target Object describing the target of the payment (payee) Object
preauthorization Object describing the pre-authorization Object
additional_params Additional parameters of the payment Object array
lang Payment language string, can gain values see lang
gw_url URL to initiate the payment gateway string

Recurring payment

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

Another information about recurring payments you can find in our help center.

In the case of the on-demand payment, the subsequent payment is made by API calling recurrence payment.

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer xzZnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p" \
-d '{
      "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"
                  }
      },
      "target":{"type":"ACCOUNT",
                 "goid":"8123456789"
               },
      "amount":"1000",
      "currency":"CZK",
      "order_number":"001",
      "order_description":"pojisteni01",
      "items":[{"name":"item01","amount":"500"},
               {"name":"item02","amount":"500"}
              ],
      "recurrence":{"recurrence_cycle":"DAY",
                    "recurrence_period":"7",
                    "recurrence_date_to":"2015-12-31"},
      "additional_params":[{"name":"invoicenumber",
                            "value":"2015001003"
                          }],
      "callback":{
                  "return_url":"http://www.eshop.cz/return",
                  "notification_url":"http://www.eshop.cz/notify"
                 }
}'

<?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' => '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' => [
        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'
    }
})

GPPaymentRequest *payment = [[GPPaymentRequest alloc] init];
payment.amount = 20;
payment.currency = @"CZK";
payment.order_number = @"001";
payment.order_description = @"test";

GPPayer *payer = [[GPPayer alloc] init];
payer.allowed_payment_instruments = @[];
payer.default_payment_instrument = @"PAYMENT_CARD";
payer.contact.first_name = @"Zbynek";
payer.contact.last_name = @"Zak";
payer.contact.email = @"test@test.cz";
payer.contact.phone_number = @"+420777456123";
payer.contact.city = @"C.Budejovice";
payer.contact.street = @"Plana 67";
payer.contact.postal_code = @"370 01";
payer.contact.country_code = @"CZE";

payment.payer = payer;

GPTarget *target = [[GPTarget alloc] init];
target.type = PAY_TARGET_ACCOUNT;
target.goid = @"8035442195";

payment.target = target;

payment.recurrence = [[PaymentRecurrence alloc] init];
payment.recurrence.recurrence_cycle = RECCURENCE_CYCLE_DAY;
payment.recurrence.recurrence_period = 7;
payment.recurrence.recurrence_date_to = @"2015-12-31";

[GPAPI sharedAPI] createPayment:payment withHandleSuccess:^(GPPayment *payment) {

} failure:^(NSError *error) {

}];

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();
    }
}

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) {
  //
}

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) {
//
}

Request

POST /api/payments/payment

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
payer Object describing the payer of the payment NO Object
target Object describing the target of the payment (payee) YES Object
amount Amount in cents YES long > 0
currency Specifies the currency payment, currency format corresponds to ISO 4217 YES string, can gain values see currency
order_number Order identification within the point of sale YES string, alphanumeric characters only (128 characters)
order_description Description of goods/service NO string, alphanumeric characters only (256 characters)
items Itemized in detail each item of the order YES Object array
recurrence Object describing the recurring payment YES Object
additional_params Additional parameters of the payment NO Object array
callback Callback URL and Notification URL for change in the payment status YES Object

Response

<?php
if ($response->hasSucceed()) {
    $url = $response->json['gw_url'];
    echo $response;
}

if response.has_succeed():
    url = response.json['gw_url']
    print(response)
{
  "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":"2015-12-31",
                  "recurrence_state":"REQUESTED"
                },
    "additional_params":[{"name":"invoicenumber",
                          "value":"2015001003"
                        }],
    "lang":"en",
    "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF "
}

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
order_number Order ID string, alphanumeric characters only (128 characters)
state Payment status string, can gain values see state
amount Amount in cents long > 0
payer Object describing the payer of the payment Object
target Object describing the target of the payment (payee) Object
recurrence Object describing the recurring payment Object
additional_params Additional parameters of payment Object array
lang Language of payment string, can gain values see lang
gw_url URL to initiate the payment gateway string

Initiation of the payment gateway

To initiate the payment gateway, it is possible to use HTML form using javascript initiates the payment gateway.

Inline option

Form to initiate the inline payment gateway

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

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

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

#import <GPAPIWebView.h>

GPAPIWebView *webView = [[GPAPIWebView alloc] init];
webView.openInSafariUrls = [[GPAPI sharedAPI] bankURLs];
webView.url = payment.gw_url; // z vytvorene platby ziskame url brany, kterou otevreme v GPAPIWebView

webView.webViewDidDone = ^(long long paymentID) {
[self dismissViewControllerAnimated:YES completion:nil];
};

webView.webViewCanceled = ^{
[self dismissViewControllerAnimated:YES completion:nil];
};

UINavigationController *navController = [[UINavigationController alloc] initWithRootViewController:webView];
navController.modalPresentationStyle = UIModalPresentationFormSheet;
[self presentViewController:navController animated:YES completion:nil]; // otevreme GPAPIWebView jako modal view

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

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

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

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.

Form’s parameter Description Required
action gw_url of created payment YES
method HTTP method YES
id Form ID YES

Redirect option

Form to redirect to “redirect” the payment gateway

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

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

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

#import <GPAPIWebView.h>

GPAPIWebView *webView = [[GPAPIWebView alloc] init];
webView.openInSafariUrls = [[GPAPI sharedAPI] bankURLs];
webView.url = payment.gw_url; // z vytvorene platby ziskame url brany, kterou otevreme v GPAPIWebView

webView.webViewDidDone = ^(long long paymentID) {
[self dismissViewControllerAnimated:YES completion:nil];
};

webView.webViewCanceled = ^{
[self dismissViewControllerAnimated:YES completion:nil];
};

UINavigationController *navController = [[UINavigationController alloc] initWithRootViewController:webView];
navController.modalPresentationStyle = UIModalPresentationFormSheet;
[self presentViewController:navController animated:YES completion:nil]; // otevreme GPAPIWebView jako modal view

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

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

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

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

Form’s parameter Description Required
action gw_url of created payment YES
method HTTP method YES

Other payment operations

Status of the payment

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.

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

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3000006529 \
-X "GET" \
-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)

[[GPAPI sharedAPI] getPaymentWithID:paymentID withHandleSuccess:^(GPPayment *payment) {    
NSLog(@"payment state: %@", [payment userReadableState]);
} failure:^(NSError *error) {  
    NSLog(@"error: %@", error);
}];

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();
    }            
}

try {
    Payment payment = connector.paymentStatus(<PAYMENT_ID>);
} catch (GPClientException e) {
  //
}

try {
  var payment = connector.PaymentStatus(<PAYMENT_ID>);
} catch (GPClientException e) {
//
}

Request

GET /api/payments/payment/{id}

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> YES

Response.

<?php
if ($response->hasSucceed()) {
    echo $response;
}

if response.has_succeed():
    print(response)
{
  "id":3000006529,
  "order_number":"001",
  "state":"PAID",
  "sub_state":"_3002",
  "amount":1000,
  "currency":"CZK",
  "payment_instrument":"BANK_ACCOUNT",
  "payer":{
           "default_payment_instrument":"BANK_ACCOUNT",
           "allowed_payment_instruments":["BANK_ACCOUNT"],
           "default_swift":"FIOBCZPP",
           "bank_account":{
                      "prefix":"670100",
                      "account_number":"7654322",
                      "bank_code":"0100",
                      "account_name":"JAN NOVAK"
                      },
           "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
          },
  "additional_params":[{"name":"invoicenumber",
                        "value":"2015001003"
                      }],
  "lang":"en",
  "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}  

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
order_number Order identification within the point of sale string, alphanumeric characters only (128 characters)
state Payment status string, can gain values see state
sub_state Payment substate string, can gain values see sub_state
amount Amount in cents long > 0
currency Payment currency string, can gain values see currency
payment_instrument Code of chosen payment method string, can gain values see payment_instrument
payer Object describing the payer of payment Object
target Object describing the target of payment (payee) Object
recurrence Object describing the recurring payment Object
additional_params Additional parameters of the payment Object array
lang Payment language string, can gain values see lang
gw_url URL for redirecting to the payment gateway string

Refund of the payment (cancelation)

Refund of the payment is a functionality which allows recovering funds for already made payment to the customer. Refund can be done in two ways. Fully refundable payment can refunded based on the parameter amount full amount of the payment, on the other hand partially refundable payment is specified by the amount for refund.

You can find additional information about refundations in help center.

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3000006620/refund \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type:application/x-www-form-urlencoded" \
-H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969" \
-d "amount=1000"

<?php
$response = $gopay->refundPayment(3000006620, 1000);

response = api.refund_payment(3000006620, 1000)

[[GPAPI sharedAPI] refundPaymentWithID:3000006620 amount:10000 withHandleSuccess:^(GPAPIResult result) {
} failure:^(NSError *error) {

}];

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();
    }              
}

try {
    PaymentResult result = connector.refundPayment(<PAYMENT_ID>, <AMOUNT>);
} catch (GPClientException e) {
    //
}

try {
    var result = connector.RefundPayment(<PAYMENT_ID>, <AMOUNT>);
} catch (GPClientException e) {
//
}

Request

POST /api/payments/payment/{id}/refund

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
amount Refunded amount YES long > 0

Response

<?php
if ($response->hasSucceed()) {
    echo $response;
}

if response.has_succeed():
    print(response)
{
 "id":3000006620,
 "result":"FINISHED"
}

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
result Status of request Object

Recurring payment on demand

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.

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3000006542/create-recurrence \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type:application/json" \
-H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969" \
-d'{
    "amount":"500",
    "currency":"CZK",
    "order_number":"002",
    "order_description":"pojisteni02",
    "items":[{"name":"item01","amount":"500"}],
    "additional_params":[{
                          "name":"invoicenumber",
                          "value":"2015001004"
                        }]
}'

<?php
$response = $gopay->createRecurrence(
    3000006542,
    [
        'amount' => '500',
        'currency' => 'CZK',
        'order_number' => '002',
        'order_description' => 'pojisteni02',
        'items' => [
            ['name' => 'item01', 'amount' => '500']
        ],
        'additional_params' => [
            ['name' => 'invoicenumber', 'value' => '2015001004']
        ]
    ]
);

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'}
        }
    }
)

GPCreateNextPayment *createNextPayment = [[GPCreateNextPayment alloc] init];
createNextPayment.amount = 500;
createNextPayment.currency = @"CZK";
createNextPayment.order_number = @"002";
createNextPayment.order_description = @"pojisteni02";
createNextPayment.items = @[[[GPItem alloc] initWithName:@"item01" amount:500]];

[[GPAPI sharedAPI] createRecurrence:createNextPayment forPaymentWithID:3000006542 withHandleSuccess:^(GPPayment *payment) {

} failure:^(NSError *error) {

}]; 

try {
  NextPaymentBuilder builder = PaymentFactory.createNextPaymentBuilder();
  ...
  PaymentResult recurrentPayment = connector.createRecurrentPayment(<ID>, builder.build());
} catch (GPClientException ex) {
  //
}

try {
  NextPaymentBuilder builder = PaymentFactory.createNextPaymentBuilder();
  ...
  PaymentResult recurrentPayment = connector.createRecurrentPayment(<ID>, builder.build());
} catch (GPClientException ex) {
  //
}

var nextPayment = new NextPayment()
  {
    Amount = <Amount>,
    Currency = <Currency>,
    OrderNumber = <OrderNumber>,
    OrderDescription = <OrderDescription>
  };
try
  {
    connector.CreateRecurrentPayment(<IdOfPaidOnDemandPayment>, nextPayment)
  }
    catch (GPClientExcepetion exception)
  {
    //
  }

Request

POST /api/payments/payment/{id}/create-recurrence

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
amount Amount YES long > 0
currency Specifies the currency of the payment, currency format corresponds toISO 4217 YES string, can gain values see currency
order_number Order ID Order identification within the point of sale string, alphanumeric characters only (128 characters)
order_description Description of goods/service YES string, alphanumeric characters only (256 characters)
items Itemized in detail of each item of the order YES Object
additional_params Additional parameters of the payment NO Object

Response

<?php
if ($response->hasSucceed()) {
    echo $response;
}

if response.has_succeed():
    print(response)
{
 "id":3000006621,
 "parent_id":3000006542,
 "order_number":"002",
 "state":"CREATED",
 "amount":1000,
 "currency":"CZK",
 "payment_instrument":"PAYMENT_CARD",
 "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
          },
 "additional_params":[{"name":"invoicenumber","value":"2015001004"}],
 "lang":"en",
 "gw_url":"https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
parent_id Parent payment ID long
order_number Order ID string, alphanumeric characters only (128 characters)
state Payment status Object
amount Amount in cents long > 0
currency Specifies the currency payment, currency format corresponds to ISO 4217 string, can gain values see currency
payment_instrument Code of chosen payment method string can gain values see payment_instrument
payer Object describing the payer of the payment Object
target Object describing the target of the payment (payee) Object
additional_params Additional parameters of the payment Object arrays
lang Payment language string, can gain values see lang
gw_url URL for initiation of the payment gateway string

Cancellation of the recurring payment

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

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

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3000006542/void-recurrence \
-X "POST" \
-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)

[[GPAPI sharedAPI] voidRecurrenceForPaymentWithID:3000139597 withHandleSuccess:^(GPAPIResult result) {

} failure:^(NSError *error) {

}];

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();
    }           
}

try {
    PaymentResult voidRecurrency = connector.voidRecurrency(<ID>);
} catch (GPClientException ex) {
    //
}

try {
    var voidRecurrency = connector.VoidRecurrency(<ID>);
} catch (GPClientException ex) {
//
}

Request

POST /api/payments/payment/{id}/void-recurrence

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> YES

Response

<?php
if ($response->hasSucceed()) {
    echo $response;
}

if response.has_succeed():
    print(response)
{
 "id":3000006542,
 "result":"FINISHED"
}

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
result Object describing the request status Object

Cancellation of the pre-authorized payment

The functionality allows you to cancel previously created​ pre-authorized payment

More information about pre-authorized payments you can find in help center.

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3000006542/void-authorization \
-X "POST" \
-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)

[[GPAPI sharedAPI] voidAuthorizationForPaymentWithID:3000006542 withHandleSuccess:^(GPAPIResult result) {

} failure:^(NSError *error) {

}];

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();
    }           
}

try {
    PaymentResult voidAuthorization = connector.voidAuthorization(<ID>);
} catch (GPClientException ex) {
    //
}

try {
    var result = connector.VoidAuthorization(<ID>);
} catch (GPClientException ex) {
//
}

Request

POST /api/payments/payment/{id}/void-authorization

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> YES

Response

<?php
if ($response->hasSucceed()) {
    echo $response;
}

if response.has_succeed():
    print(response)
{
 "id":3000006542,
 "result":"FINISHED"
}

Response

Parameter’s name Parameter’s description Data’s type
id payment ID long
result Object describing of request status long

Charge of pre-authorized payment

The functionality enables charging of pre-authorized funds previously created by pre-authorized payment.

Additional information about pre-authorized payments you can find in help center.

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3000006542/capture \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type:application/x-www-form-urlencoded" \
-H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"

<?php
$response = $gopay->captureAuthorization(3000006542);

response = api.capture_authorization(3000006542)

[[GPAPI sharedAPI] capturePaymentWithID:3000006542 withHandleSuccess:^(GPAPIResult result) {

} failure:^(NSError *error) {

}];

try {
    PaymentResult capture = connector.capturePayment(<ID>);
} catch (GPClientException ex) {
    //
}

try {
    PaymentResult capture = connector.capturePayment(<ID>);
} catch (GPClientException ex) {
    //
}

try {
    var capture = connector.CapturePayment(<ID>);
} catch (GPClientException ex) {
//
}    

Request

POST /api/payments/payment/{id}/capture

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> ANYESO

Response

<?php
if ($response->hasSucceed()) {
    echo $response;
}

if response.has_succeed():
    print(response)
{ 
 "id":3000006542,
 "result":"FINISHED"
}

Response

Parameter’s name Parameter’s description Data’s type
id payment ID long
result Object describing the request status Object

List of avaliable payment methods

Retruns JSON structure of all avaliable payment methods on eshop profile. GoID of eshop and code of currency must be passed in URL.

Request

curl -v -N https://gw.sandbox.gopay.com/api/eshops/eshop/8123456789/payment-instruments/CZK \
-X "GET" \
-H "Accept: application/json" \
-H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"

REQUEST

GET /api/eshops/eshop/{GoID}/payment-instruments/{currency}

HEADER OF THE REQUEST

Parameter’s name Parameter’s description Required
Accept application/json ANO
Authorization Bearer ANO

Response

{
"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},
    ...]},
]}

RESPONSE

Parameter’s name Parameter’s description
groups Definition of payment method groups
enabledPaymentInstruments Object that contains payment methods that are avaliable on eshop profile

Generating of account statement

The funcionality generates statements from GoPay business account for specific e-shop and currency. It returns content of account statement file. More information about file types specification you can find in help center.

Request

curl -v -N https://gw.sandbox.gopay.com/api/accounts/account-statement \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer kRwD4pd8I+YYK0SOb7g+khEfxZmc8m/fX91zbsv2Pc/h3LjqeAN7lHe9R2qnw2YcurQNAXi0KCRJlME71OR1sm1YgVMSRf71ty5ASpU05+U=" \
-d '{
"date_from":"2016-07-08",
"date_to":"2016-08-08",
"goid":"8123456789",
"currency":"CZK",
"format":"CSV_A"
}'

REQUEST

POST /api/accounts/account-statement

HHeader of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
date_from Statement start date YES string yyyy-mm-dd
date_to Statement end date YES string yyyy-mm-dd
goid Unique identifier of an e-shop in the payment gateway system YES long
currency Specifies the currency, currency format corresponds to ISO 4217 YES string
format Specifies format type of generated statement YES string

RESPONSE

Response in type application/octet-stream

Registration of sales

Standard payment

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer xzZnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p" \
-d '{
    "payer": {
                "default_payment_instrument":"BANK_ACCOUNT",
                "allowed_payment_instruments":["BANK_ACCOUNT"],
                "default_swift":"FIOBCZPP",
                "allowed_swifts":["FIOBCZPP","BREXCZPP"],
                "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"
                        }
                  },
    "target": {
                "type":"ACCOUNT",
                "goid":"8123456789"
              },
    "amount":"139951",
    "currency":"CZK",
    "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":21
                }, 
            {
                "type":"ITEM", 
                "name":"oprava podpatku",
                "product_url":"https://www.eshop.cz/boty/opravy", 
                "ean":1234567890189,
                "amount":19961,
                "count":1,
                "vat_rate":15
                }],
    "eet":{
                "celk_trzba":139951,
                "zakl_dan1":99160,
                "dan1":20830,
                "zakl_dan2":17358,
                "dan2":2603,
                "mena":"CZK"
            },
    "additional_params":[{"name":"invoicenumber",
                        "value": "2015001003"
                        }],
    "callback":{
                "return_url":"https://www.eshop.cz/return",
                "notification_url":"https://www.eshop.cz/notify"
              },
    "lang":"cs"
}'

<?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
]);

Request

POST /api/payments/payment

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
payer The object describing the payer of the payment NO Object
target The object describing the target of the payment (payee) YES Object
amount Amount in cents YES long > 0
currency Specifies the currency of payment, currency format corresponds to ISO 4217 YES string
order_number Identification of the order within the point of sale YES string, alphanumeric characters only (128 characters)
order_description Description of goods / service NO string, alphanumeric characters only (256 characters)
items Itemized in detail each item of the order YES Object
eet Parameters for registration of sales YES Object
callback Callback URL for processing of the payment result / Notification URL for processing of change of payment status YES Object
additional_params Additional payment parameters No According to object
lang Parameters defines language of the payment NO string, can gain values see lang

Response

{
  "id":3000006529,
  "order_number":"001",
  "state":"CREATED",
  "amount":139951,"currency":"CZK",
  "payer":{
           "default_payment_instrument":"BANK_ACCOUNT",
           "allowed_payment_instruments":["BANK_ACCOUNT"],
           "default_swift":"FIOBCZPP",
           "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
          },
  "additional_params":[{"name":"invoicenumber",
                        "value":"2015001003"
                      }],
  "lang":"en",
  "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
order_number Identification of order string, alphanumeric characters only (128 characters)
state Payment status string, can gain values see state
amount Amount in cents long > 0
currency Specifies the currency of payment string, can gain values see currency
payer Object describing the payer of the payment Object
target Object describing the target of the payment (payee) Object
additional_params Additional parameters of payments Object array
lang Parameter defines payment language string, can gain values see lang
gw_url URL for initiation of the payment gate string

Recurring payment

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer xzZnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p" \
-d '{
      "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"
                  }
      },
      "target":{"type":"ACCOUNT",
                 "goid":"8123456789"
               },
      "amount":"139951",
      "currency":"CZK",
      "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":21
                }, 
                {
                "type":"ITEM", 
                "name":"oprava podpatku",
                "product_url":"https://www.eshop.cz/boty/opravy", 
                "ean":1234567890189,
                "amount":19961,
                "count":1,
                "vat_rate":15
                }],
      "eet":{
                "celk_trzba":139951,
                "zakl_dan1":99160,
                "dan1":20830,
                "zakl_dan2":17358,
                "dan2":2603,
                "mena":"CZK"
            },
      "recurrence":{"recurrence_cycle":"DAY",
                    "recurrence_period":"7",
                    "recurrence_date_to":"2015-12-31"},
      "additional_params":[{"name":"invoicenumber",
                            "value":"2015001003"
                          }],
      "callback":{
                  "return_url":"http://www.eshop.cz/return",
                  "notification_url":"http://www.eshop.cz/notify"
                 }
}'

<?php
use GoPay\Definition\Language;
use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Payment\VatRate;
use GoPay\Definition\Payment\PaymentItemType;

$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' => 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
    ],
    'recurrence' => ['recurrence_cycle' => 'DAY',
            'recurrence_period' => '7',
            'recurrence_date_to' => '2020-12-31'],
    'additional_params' => [['name' => 'invoicenumber',
            'value' => '2015001003'
    ]],
    'callback' => [
            'return_url' => 'http://www.eshop.cz/return',
            'notification_url' => 'http://www.eshop.cz/notify'
    ]
]);

Request

POST /api/payments/payment

Header of request

Parameter name Parameter description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
payer Object describing the payer of the payment NO Object
target Object describing the target of the payment (payee) YES Object
amount Amount in cents YES long > 0
currency Specifies the currency payment, currency format corresponds to ISO 4217 YES string, can gain values see currency
order_number Order identification within the point of sale YES string, alphanumeric characters only (128 characters)
order_description Description of goods/service NO string, alphanumeric characters only (256 characters)
items Itemized in detail each item of the order YES Object array
eet Parameters for registration of sales YES Object
recurrence Object describing the recurring payment YES Object
additional_params Additional parameters of the payment NO Object array
callback Callback URL and Notification URL for change in the payment status YES Object

Response

{
  "id":3000006542,
  "order_number":"001",
  "state":"CREATED",
  "amount":139951,"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":"2020-12-31",
                  "recurrence_state":"REQUESTED"
                },
    "additional_params":[{"name":"invoicenumber",
                          "value":"2015001003"
                        }],
    "lang":"en",
    "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF "
}

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
order_number Order ID string, alphanumeric characters only (128 characters)
state Payment status Object
amount Amount in cents long > 0
payer Object describing the payer of the payment Object
target Object describing the target of the payment (payee) Object
recurrence Object describing the recurring payment Object
additional_params Additional parameters of payment Object array
lang Language of payment string, can gain values see lang
gw_url URL to initiate the payment gateway string

Recurring payment on demand

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3000006542/create-recurrence \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type:application/json" \
-H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969" \
-d '{
    "amount":"119990",
    "currency":"CZK",
    "order_number":"Nakup",
    "order_description":"2016-0001254",
    "items":[
    {
        "type":"ITEM", 
        "name":"lodicky",
        "product_url":"https://www.eshop.cz/boty//lodicky", 
        "ean":1234567890123,
        "amount":119990,
        "count":1,
        "vat_rate":21
    }],
    "eet":{
        "celk_trzba":119990,
        "zakl_dan1":99160,
        "dan1":20830,
        "mena":"CZK"
    },
    "additional_params":[{
        "name":"invoicenumber",
        "value":"2016001004"
    }]
}'

<?php
    use GoPay\Definition\Language;
    use GoPay\Definition\Payment\Currency;
    use GoPay\Definition\Payment\VatRate;
    use GoPay\Definition\Payment\PaymentItemType;

    $response = $gopay->createRecurrence(3000006620, [
    'amount' => '119990',
    'currency' => Currency::CZECH_CROWNS,
    'order_number' => 'Nakup',
    'order_description' => '2016-0001254',
    'items' => [
            [
                    'type' => PaymentItemType::ITEM,
                    'name' => 'lodicky',
                    'product_url' => 'https://www.eshop.cz/boty//lodicky',
                    'ean' => 1234567890123,
                    'amount' => 119990,
                    'count' => 1,
                    'vat_rate' => VatRate::RATE_4
            ]],
    'eet' => [
            'celk_trzba' => 119990,
            'zakl_dan1' => 99160,
            'dan1' => 20830,
            'mena' => Currency::CZECH_CROWNS
    ],
    'additional_params' => [[
            'name' => 'invoicenumber',
            'value' => '2016001004'
    ]]
]);

Request

POST /api/payments/payment/{id}/create-recurrence

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
amount Amount YES long > 0
currency Specifies the currency of the payment, currency format corresponds toISO 4217 YES string, can gain values see currency
order_number Order ID Order identification within the point of sale string, alphanumeric characters only (128 characters)
order_description Description of goods/service YES string, alphanumeric characters only (256 characters)
items Itemized in detail of each item of the order YES Object
eet Parameters for registration of sales YES Object
additional_params Additional parameters of the payment NO Object

Response

{
 "id":3000006621,
 "parent_id":3000006542,
 "order_number":"002",
 "state":"CREATED",
 "amount":119990,
 "currency":"CZK",
 "payment_instrument":"PAYMENT_CARD",
 "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
          },
 "additional_params":[{"name":"invoicenumber","value":"2016001004"}],
 "lang":"en",
 "gw_url":"https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
parent_id Parent payment ID long
order_number Order ID string, alphanumeric characters only (128 characters)
state Payment status Object
amount Amount in cents long > 0
currency Specifies the currency payment, currency format corresponds to ISO 4217 string, can gain values see currency
payment_instrument Code of chosen payment method string can gain values see payment_instrument
payer Object describing the payer of the payment Object
target Object describing the target of the payment (payee) Object
additional_params Additional parameters of the payment Object arrays
lang Payment language string, can gain values see lang
gw_url URL for initiation of the payment gateway string

Status of the payment

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3000006529 \
-X "GET" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"

Request

GET /api/payments/payment/{id}

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> YES

Response.

{
  "id":3000006529,
  "order_number":"001",
  "state":"PAID",
  "sub_state":"_3002",
  "amount":139951,
  "currency":"CZK",
  "payment_instrument":"BANK_ACCOUNT",
  "payer":{
           "default_payment_instrument":"BANK_ACCOUNT",
           "allowed_payment_instruments":["BANK_ACCOUNT"],
           "default_swift":"FIOBCZPP",
           "bank_account":{
                      "prefix":"670100",
                      "account_number":"7654322",
                      "bank_code":"0100",
                      "account_name":"JAN NOVAK"
                      },
           "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
          },
  "additional_params":[{"name":"invoicenumber",
                        "value":"2015001003"
                      }],
  "eet_code":{
        "fik":"28da0811-e050-46c7-a62c-aa456d1f07ef-ff",
        "bkp":"5d874afc-251f8661-ff0e0b13-c7cd8793-6bf0386a",
        "pkp":"Ca8sTbURReQjjgcy/znXBKjPOnZof3AxWK5WySpyMrUXF0o7cz1BP6a....."
     },
  "lang":"cs",
  "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}  

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
order_number Order identification within the point of sale string, alphanumeric characters only (128 characters)
state Payment status string, can gain values see state
sub_state Payment substate string, can gain values see sub_state
amount Amount in cents long > 0
currency Payment currency string, can gain values see currency
payment_instrument Code of chosen payment method string, can gain values see payment_instrument
payer Object describing the payer of payment Object
target Object describing the target of payment (payee) Object
recurrence Object describing the recurring payment Object
additional_params Additional parameters of the payment Object array
eet_code Information about registration of sales Object
lang Payment language string, can gain values see lang
gw_url URL for redirecting to the payment gateway string

Refund of the payment (cancelation)

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3000006620/refund \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969" \
-d '{
    "amount":119990,
    "items":[
        {
            "type":"ITEM", 
            "name":"lodicky",
            "product_url":"https://www.eshop.cz/boty/damske/lodicky-cervene", 
            "ean":1234567890123,
            "amount":-119990,
            "count":1,
            "vat_rate":21
        }],
    "eet":{
            "celk_trzba":-119990,
            "zakl_dan1":-99160,
            "dan1":-20830,
            "mena":"CZK"
        }
    }'

<?php
    use GoPay\Definition\Payment\VatRate;
    use GoPay\Definition\Payment\PaymentItemType;

    $response = $gopay->refundPayment(3000006620, [
    'amount' => 119990,
    'items' => [
            [
                    'type' => PaymentItemType::ITEM,
                    'name' => 'lodicky',
                    'product_url' => 'https://www.eshop.cz/boty/damske/lodicky-cervene',
                    'ean' => 1234567890123,
                    'amount' => -119990,
                    'count' => 1,
                    'vat_rate' => VatRate::RATE_4
            ]],
    'eet' => [
            'celk_trzba' => -119990,
            'zakl_dan1' => -99160,
            'dan1' => -20830,
            'mena' => Currency::CZECH_CROWNS
    ]
]);

Request

POST /api/payments/payment/{id}/refund

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
amount Refunded amount YES long > 0
items Itemized in detail each item of the order YES Object
eet Parameters for registration of sales YES Object

Response

{
 "id":3000006620,
 "result":"FINISHED"
}

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
result Status of request Object

EET payment receipts

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3048468774/eet-receipts \
-X "GET" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 1437hmoAEdbMRcfdQeXz052Dt9MRKzcsC/+zVwfZIUVUZ3Ki+Xcf+EER9JfQ3uFKq50WLkEjBR"

Request

GET /api/payments/payment/{id}/eet-receipts

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Response

[{
  "celk_trzba":139951,
  "zakl_dan1":99160,
  "dan1":20830,
  "zakl_dan2":17358,
  "dan2":2603,
  "payment_id":3048468774,
  "state":"DELIVERED",
  "date_last_attempt":"2017-03-03T15:21:00.450+0100",
  "date_next_attempt":"2017-03-03T15:21:00.226+0100",
  "eet_mode":"EET",
  "uuid_zprava":"e382c8e5-195f-4b30-b6f4-eef15899240f",
  "date_odesl":"2017-03-03T15:21:00.241+0100",
  "dic_popl":"CZ1212121218",
  "id_provoz":11,
  "id_pokl":"1",
  "dat_trzby":"2017-03-03T15:21:00.162+0100",
  "porad_cis":"3048468774",
  "fik":"5f4286a4-ab97-496f-b860-cd8542911449-ff",
  "bkp":"713FB9FD-8EC9D865-4F6E5A49-68992939-408F9E59",
  "pkp":"Kzvh4JmZszaytn1XPy1wTKpJ2eqtxyQsHRlULOgKbJBPrXVeNw18uwzA1/JxViPEFKdGBRsImKH5Y4V07ZrekVs5HZGK11h+mww4P6q2KtA79/CO9S7NnBr44vwesK5PXX6gcSq4p0ptk6H5uTpmsyCxQjVesNXI1m5zduxQ93SoaZ/3kMBbhUaaqekMvxKpsxgtlbm8h8J6Fh+jvkF2NyPkEfgTyI/s9OuEq6JQ8rvTcTpz3phNXX+Cvb3oJpSNk8mtn3/uo6a/hmgdpG+W3f8pwUFZ1hQ0A5+/jyrv+pURS67l3Mh+ElUVLBEE2/Iai/jqxjklGeAa8hjQowsy3g=="
}]

Response

Parameter’s name Parameter’s description Data’s type
dic_poverujiciho DIČ of the entrustment taxpayer varchar
celk_trzba The total amount long in cents
zakl_nepodl_dph The total amount of supplies exempt from VAT long in cents
zakl_dan1 The total tax base amount, the basic VAT rate long in cents
dan1 The total amount of VAT, the basic rate long in cents
zakl_dan2 The total tax base amount with a first reduced rate of VAT long in cents
dan2 The total VAT amount with a first reduced rate long in cents
zakl_dan The total tax base amount with a second reduced rate of VAT long in cents
dan3 The total VAT amount with a second reduced rate long in cents
cest_sluz The total amount of the VAT regime for travel service long in cents
pouzit_zboz1 The total amount of the VAT regime for the sale of used goods with a basic rate long in cents
pouzit_zboz2 The total amount of the VAT regime for the sale of used goods with a first reduced rate long in cents
pouzit_zboz3 The total amount of the VAT regime for the sale of used goods with a second reduced rate long in cents
urceno_cerp_zuct The total amount of payments designated for subsequent pumping or settlement long in cents
cerp_zuct The total amount of payments which are followed by pumping or settlement of the payment long in cents
payment_id ID of payment long
state Receipt delivery status can gain values of state
date_last_attempt Date and time of last attempt to registration of transaction yyyy-MM-dd’T'HH:mm:ss.SSSZ
date_next_attempt Date and time of next attempt to registration of transaction yyyy-MM-dd’T'HH:mm:ss.SSSZ
eet_mode EET mode variant can gain values of eet_mode
uuid_zprava UUID of message string
date_odesl Date and time of registration of transaction yyyy-MM-dd’T'HH:mm:ss.SSSZ
dic_popl DIČ of the taxpayer varchar
id_provoz ID of virtual workshop integer
id_pokl ID of cash register string
dat_trzby Date and time of the payment receive yyyy-MM-dd’T'HH:mm:ss.SSSZ
porad_cis ID of receipt long
kod_chyby Every possible fault caused during communication with EET service integer
error_code EET error code integer
kody_varovani EET warning code string
fik Fiscal identification code (FIK) varchar, 39 characters
bkp Security code of the taxpayer (BKP) varchar, 44 characters
pkp Signature code of the taxpayer (PKP) varchar, 344 characters

List of EET receipts

Request

curl -v -N https://gw.sandbox.gopay.com/api/eet-receipts \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 1437hmoAEdbMRcfdQeXz052Dt9MRKzcsC/+zVwfZIUVUZ3Ki+Xcf+EER9JfQ3uFKq50WLkEjBR" \
-d '{
      "date_from": "2017-03-01",
      "date_to":"2017-03-06",
      "id_provozovny":"11"
    }'

Request

POST /api/eet-receipts

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
date_from The start date YES string yyyy-mm-dd
date_to The end date YES string yyyy-mm-dd
id_provozovny ID of virtual workshop YES long

Response

[{
  "celk_trzba":-139951,
  "zakl_dan1":-99160,
  "dan1":-20830,
  "zakl_dan2":-17358,
  "dan2":-2603,
  "payment_id":3048468774,
  "state":"DELIVERED",
  "date_last_attempt":"2017-03-03T15:22:34.853+0100",
  "date_next_attempt":"2017-03-03T15:22:34.652+0100",
  "eet_mode":"EET",
  "uuid_zprava":"3592a5be-49f0-4c32-9634-fb4738657bb9",
  "date_odesl":"2017-03-03T15:22:34.669+0100",
  "dic_popl":"CZ1212121218",
  "id_provoz":11,
  "id_pokl":"1",
  "porad_cis":"3048468774-4000000573",
  "fik":"fb60760a-34e4-4cef-b93e-15dca3dfae14-ff",
  "bkp":"802476B0-C9E62225-98C83257-C8104A37-3D8C0AEA",
  "pkp":"hZTkX2DkwtPcIHdORO/gYAF6gE3uTf+YA1m/3SYCll4tQramRbCBqAQZoiUk0yNRXYulyS0G4nRlK4qcrFyOY1ptohNGe57oXzGTJuv7yE3c5c6S9UdwPqDjb3ZHxWjZLkSLMEu9LVdQp4R8b4vUikvC3ALN148a2140LmY8xXpEQDZkjDD6POrx1fybtUFo+VQYV+w3M3MpMjPKcDf4Zabq53r/UXVGOJBJQUrALAYRmylbKWZlk0gHV7cImXVnnXwUtSIU90kLu69EOAUIYgnILZqCACXQwUV5Uh+2roCqyojdoqh3ij7qTOd+KDHXXZH0sjTPQOR9ZVP9IUmifg=="},
  {
  "celk_trzba":139951,
  "zakl_dan1":99160,
  "dan1":20830,
  "zakl_dan2":17358,
  "dan2":2603,
  "payment_id":3048468774,
  "state":"DELIVERED",
  "date_last_attempt":"2017-03-03T15:21:00.450+0100",
  "date_next_attempt":"2017-03-03T15:21:00.226+0100",
  "eet_mode":"EET",
  "uuid_zprava":"e382c8e5-195f-4b30-b6f4-eef15899240f",
  "date_odesl":"2017-03-03T15:21:00.241+0100",
  "dic_popl":"CZ1212121218",
  "id_provoz":11,
  "id_pokl":"1",
  "dat_trzby":"2017-03-03T15:21:00.162+0100",
  "porad_cis":"3048468774",
  "fik":"5f4286a4-ab97-496f-b860-cd8542911449-ff",
  "bkp":"713FB9FD-8EC9D865-4F6E5A49-68992939-408F9E59",
  "pkp":"Kzvh4JmZszaytn1XPy1wTKpJ2eqtxyQsHRlULOgKbJBPrXVeNw18uwzA1/JxViPEFKdGBRsImKH5Y4V07ZrekVs5HZGK11h+mww4P6q2KtA79/CO9S7NnBr44vwesK5PXX6gcSq4p0ptk6H5uTpmsyCxQjVesNXI1m5zduxQ93SoaZ/3kMBbhUaaqekMvxKpsxgtlbm8h8J6Fh+jvkF2NyPkEfgTyI/s9OuEq6JQ8rvTcTpz3phNXX+Cvb3oJpSNk8mtn3/uo6a/hmgdpG+W3f8pwUFZ1hQ0A5+/jyrv+pURS67l3Mh+ElUVLBEE2/Iai/jqxjklGeAa8hjQowsy3g=="},
  {
  ...
  }] 

Response

Parameter’s name Parameter’s description Data’s type
dic_poverujiciho DIČ of the entrustment taxpayer varchar
celk_trzba The total amount long in cents
zakl_nepodl_dph The total amount of supplies exempt from VAT long in cents
zakl_dan1 The total tax base amount, the basic VAT rate long in cents
dan1 The total amount of VAT, the basic rate long in cents
zakl_dan2 The total tax base amount with a first reduced rate of VAT long in cents
dan2 The total VAT amount with a first reduced rate long in cents
zakl_dan The total tax base amount with a second reduced rate of VAT long in cents
dan3 The total VAT amount with a second reduced rate long in cents
cest_sluz The total amount of the VAT regime for travel service long in cents
pouzit_zboz1 The total amount of the VAT regime for the sale of used goods with a basic rate long in cents
pouzit_zboz2 The total amount of the VAT regime for the sale of used goods with a first reduced rate long in cents
pouzit_zboz3 The total amount of the VAT regime for the sale of used goods with a second reduced rate long in cents
urceno_cerp_zuct The total amount of payments designated for subsequent pumping or settlement long in cents
cerp_zuct The total amount of payments which are followed by pumping or settlement of the payment long in cents
payment_id ID of payment long
state Receipt delivery status can gain values of state
date_last_attempt Date and time of last attempt to registration of transaction yyyy-MM-dd’T'HH:mm:ss.SSSZ
date_next_attempt Date and time of next attempt to registration of transaction yyyy-MM-dd’T'HH:mm:ss.SSSZ
eet_mode EET mode variant can gain values of eet_mode
uuid_zprava UUID of message string
date_odesl Date and time of registration of transaction yyyy-MM-dd’T'HH:mm:ss.SSSZ
dic_popl DIČ of the taxpayer varchar
id_provoz ID of virtual workshop integer
id_pokl ID of cash register string
dat_trzby Date and time of the payment receive yyyy-MM-dd’T'HH:mm:ss.SSSZ
porad_cis ID of receipt long
kod_chyby Every possible fault caused during communication with EET service integer
error_code EET error code integer
kody_varovani EET warning code string
fik Fiscal identification code (FIK) varchar, 39 characters
bkp Security code of the taxpayer (BKP) varchar, 44 characters
pkp Signature code of the taxpayer (PKP) varchar, 344 characters

Advanced features of superCASH

Advanced features of superCASH payment method allow to create a group (a batch) of coupons for getting the payment information including barcodes. The customer therefore doesn´t operate with GoPay payment gateway. You can display all important information for offline payment via superCASH payment method for example to the customer’s invoice for the order.

Creation of superCASH batch

The function will create a group (a batch) of superCASH coupons. When the creation is complete, notification URL specified in “batch_completed_notification_url” parameter is called. Default parameters of coupons are specified in “defaults” object specific parameters then in “coupons” object.

Request

curl -v -N https://gw.sandbox.gopay.com/api/supercash/coupon/batch \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer cwY6kMhLcXGVWTOR3qIV92uonFcKtdLm0sJQurAOLORcPHw9PV3AoBQWumnJJq4pmCIU1xC1ZNxDgdzMrJuD3PMgk1pSv1Qf0cu/ILubBgY=" \
-d '{
    "go_id":8123456789,
    "batch_completed_notification_url":"http://http-notify.cz/supercash",
    "defaults":{
        "sub_type":"POSTPAID",
        "amounts":[300,400,500,600,700,800,900,1000],
        "order_description":"supercash batch test"
    },
    "coupons":[
        {
            "buyer_email":"zakaznik1@example.com",
            "custom_id":"ID-123457",
            "buyer_phone":"+420777666111",
            "amounts":[100]
        },
        {
            "buyer_email":"zakaznik2@example.com",
            "custom_id":"ID-123458",
            "buyer_phone":"+420777666222",
            "amounts":[200]
        },
        {
            "buyer_email":"zakaznik3@example.com",
            "custom_id":"ID-123459",
            "buyer_phone":"+420777666333"
        }
    ]
}'

def _create_supercash_batch(self):
    base_batch = {
        'batch_completed_notification_url' : 'http://www.notify.cz/super',
        'defaults' : {
            'sub_type' : SupercashSubType.SUB_TYPE_POSTPAID,
            'amounts' : [300, 400, 500, 600, 700, 800, 900, 1000],
            'order_description' : 'supercash_coupon_batch_test',
        },
        'coupons' : [
            {
                'buyer_email' : 'zakaznik1@example.com',
                'custom_id' : 'ID-123457',
                'buyer_phone' : '+420777666111',
                'amounts' : [100],
            },
            {
                'buyer_email' : 'zakaznik2@example.com',
                'custom_id' : 'ID-123458',
                'buyer_phone' : '+420777666222',
                'amounts' : [200],
            },
            {
                'buyer_email' : 'zakaznik3@example.com',
                'custom_id' : 'ID-123459',
                'buyer_phone' : '+420777666333',
                'amounts' : [300],
            },
        ],
    }
    }

SupercashRequestBuilder batchItemBuilder = new SupercashRequestBuilder();

SupercashRequestBuilder batchRequestBuilder = new SupercashRequestBuilder();

SupercashBatchRequest batchRequest = batchRequestBuilder
        <GOID>
        <NOTIFY_URL>
        .withDefaults(batchItemBuilder
                .subType(SubType.POSTPAID)
                .withAmounts(Arrays.asList(300L, 400L, 500L, 600L, 700L, 800L, 900L, 1000L))
                .orderDescription("Supercash Coupon Batch Test")
                .buildBatchItem()
        )
        .addCoupon(batchItemBuilder
                .reset()
                .withBuyerEmail("zakaznik1@example.com")
                .customId("ID-123457")
                .withBuyerPhone("+420777666111")
                .withAmounts(Arrays.asList(100L))
                .buildBatchItem()
        )
        .addCoupon(batchItemBuilder
                .reset()
                .withBuyerEmail("zakaznik2@example.com")
                .customId("ID-123458")
                .withBuyerPhone("+420777666222")
                .withAmounts(Arrays.asList(200L))
                .buildBatchItem()
        )
        .addCoupon(batchItemBuilder
                .reset()
                .withBuyerEmail("zakaznik3@example.com")
                .customId("ID-123459")
                .withBuyerPhone("+420777666333")
                .withAmounts(Arrays.asList(300L))
                .buildBatchItem()
        )
        .buildBatchRequest();

SupercashBatchResult batchResult = null;

try {
    batchResult = connector
            .getAppToken(CLIENT_ID, CLIENT_SECRET, OAuth.SCOPE_PAYMENT_ALL)
            .createSupercashCouponBatch(batchRequest);

} catch (GPClientException e) {
    //
}

SupercashBatchRequest batchRequest = new SupercashBatchRequest()
{
    GoId = GOID,
    BatchNotificationUrl = "http://www.notify.cz/super",
    Defaults = new SupercashBatchItem()
    {
        SubType = SubType.POSTPAID,
        Amounts = new List<long> { 300, 400, 500, 600, 700, 800, 900, 1000 },
        OrderDescription = "Supercash Coupon Batch Test"
    },
    Coupons = new List<SupercashBatchItem> {
        new SupercashBatchItem()
        {
            BuyerEmail = "zakaznik1@example.com",
            CustomId = "ID-123457",
            BuyerPhone = "+420777666111",
            Amounts = new List<long> { 100 }
        },
        new SupercashBatchItem()
        {
            BuyerEmail = "zakaznik2@example.com",
            CustomId = "ID-123458",
            BuyerPhone = "+420777666222",
            Amounts = new List<long> { 200 }
        },
        new SupercashBatchItem()
        {
            BuyerEmail = "zakaznik3@example.com",
            CustomId = "ID-123459",
            BuyerPhone = "+420777666333",
            Amounts = new List<long> { 300 }
        }
    }
};

try
{
    SupercashBatchResult result = connector.GetAppToken().CreateSupercashCouponBatch(batchRequest);
    Console.WriteLine(result.ToString());
}
catch (GPClientException ex)
{
    //
}  

Request

POST /api/supercash/coupon/batch

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
go_id Unique identifier of an e-shop in the payment gateway system YES long
batch_completed_notification_url URL address for sending asynchronous notification in the case of changes in the batch status (with protocol) YES string
defaults Default values of superCASH coupons YES Object
coupons Specific values of superCASH coupons YES Object

Response

{"batch_request_id":951806260} 

Response

Parameter’s name Parameter’s description Data’s type
batch_request_id Coupons batch’s ID long

Creation of superCASH coupon

The function will create a single superCASH coupon. When the creation is complete, notification URL specified in “notification_url” is called.

Request

curl -v -N https://gw.sandbox.gopay.com/api/supercash/coupon \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eMk5PlDzC9wjGle/1F1sfOI7MvOoFZoFjVVzWMiBTD0KoiT2HgyW9z9wfIBaZg1eDzN21tbf11oABJmgbliXd4d+ZlqVlOoY78kdhGR0tEE=" \
-d '{
    "go_id":8123456789,
    "sub_type":"POSTPAID",
    "custom_id":"ID-123457",
    "order_number":"1",
    "amount":100,
    "order_description":"supercash test",
    "buyer_email":"zakaznik@example.com",
    "buyer_phone":"+420777666111",
    "date_valid_to":"2018-12-31",
    "notification_url":"http://http-notify.cz/supercash"
}'

def test_create_supercash_coupon(self):
    base_coupon = {
        'sub_type' : SupercashSubType.SUB_TYPE_POSTPAID,
        'custom_id' : 'ID-123457',
        'amount' : 100,
        'order_number' : '1',
        'order_description' : 'supercash_coupon_test',
        'buyer_email' : 'zakaznik@example.com',
        'buyer_phone' : '+420777123456',
        'date_valid_to' : '2018-12-31',
        'notification_url' : 'http://www.example-notify.cz/supercash',
    }

SupercashRequestBuilder couponRequestBuilder = new SupercashRequestBuilder();

SupercashCouponRequest couponRequest = couponRequestBuilder
        <GOID>
        .subType(SubType.POSTPAID)
        .withAmount(100L)
        .customId("ID-123457")
        .orderNumber("1")
        .orderDescription("Supercash Coupon Test")
        .withBuyerEmail("zakaznik@example.com")
        .withBuyerPhone("+420777123456")
        .validTo(new Date(2018, 12, 31))
        <NOTIFY_URL>
        .buildCouponRequest();

SupercashCoupon coupon = null;

try {
    coupon = connector
            .getAppToken(CLIENT_ID, CLIENT_SECRET, OAuth.SCOPE_PAYMENT_ALL)
            .createSupercashCoupon(couponRequest);

} catch (GPClientException e) {
    //
}

SupercashCouponRequest couponRequest = new SupercashCouponRequest()
{
    GoId = GOID,
    SubType = SubType.POSTPAID,
    CustomId = "ID-123457",
    Amount = 100,
    OrderNumber = "1",
    OrderDescription = "Supercash Coupon Test",
    BuyerEmail = "zakaznik@example.com",
    BuyerPhone = "+420777123456",
    DateValidTo = new DateTime(2018, 12, 31),
    NotificiationUrl = "http://www.example-notify.cz/supercash"
};

try
{
    SupercashCoupon result = connector.GetAppToken().CreateSupercashCoupon(couponRequest);

    Console.WriteLine("SC coupon id: {0}", result.SupercashCouponId);
    Console.WriteLine("SC custom id: {0}", result.CustomId);
    Console.WriteLine("SC coupon number: {0}", result.SupercashNumber);
}
catch (GPClientException ex)
{
   //
}   

Request

POST /api/supercash/coupon

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
go_id Unique identifier of an e-shop in the payment gateway system YES long
sub_type Type of superCASH coupon YES Can gain values of sub_type
custom_id Custom ID for coupon NO string, alphanumeric characters only
amount Amount in cents YES long > 0
order_number Identification of the order within the point of sale NO string, alphanumeric characters only
order_description Description of goods/service NO string, alphanumeric characters only)
buyer_email Valid e-mail address YES string
buyer_phone Phone number with country code YES string
date_valid_to Date of the coupon’s validity YES string, yyyy-mm-dd
notification_url URL address for sending asynchronous notification in the case of changes in the coupon’s status (with protocol) YES string

Response

{
    "supercash_coupon_id":100154021,
    "custom_id":"ID-123457",
    "barcode_image_url":"https://partner.sandbox.gopay.com/gp-gateways/supercash/generateImg.action?barCode=14969119252751496911925275149691",
    "supercash_number":"1496911925275",
    "barcode":"14969119252751496911925275149691",
    "date_created":"2017-06-08T10:52:05.224+0200",
    "date_valid_to":"2018-12-31",
    "payment_session_id_list":[3050854820]
}

Response

Parameter’s name Parameter’s description Data’s type
supercash_coupon_id superCASH coupon’s ID string
custom_id Custom ID for coupon string
barcode_image_url superCASH barcode in JPG format string
supercash_number superCASH number string
barcode Barcode string
date_created Date of coupon’s creation yyyy-MM-dd’T'HH:mm:ss.SSSZ
date_valid_to Date of the coupon’s validity string, yyyy-mm-dd
payment_session_id_list List of payments’ IDs string

Status of the batch

The funcionality allows the to determine the status of superCASH batch.

Request

curl -v -N https://gw.sandbox.gopay.com/api/batch/951806260 \
-X "GET" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer m/7OTknCbdIiHTNfFW6GWMyfL7XO40OfOKixtzUvkp+eLw9gWBl96+Lk4fPz7BrpFUGWvA3bi29Ywc8gC5tOONeUJQvXmruhjJQNw7QyeqQ=" \

def _get_supercash_coupon_batch_status(self):
    batch_id = 961667719

long batchId = 961667719;
SupercashBatchState batchState = null;

try {
    batchState = connector
            .getAppToken(CLIENT_ID, CLIENT_SECRET, OAuth.SCOPE_PAYMENT_ALL)
            .getSupercashCouponBatchStatus(batchId);

} catch (GPClientException e) {
    //
}

var batchId = 961667719;

try
{
    SupercashBatchState result = connector.GetAppToken().GetSupercashCouponBatchStatus(batchId);
    Console.WriteLine(result.ToString());
}
catch (GPClientException ex)
{
    //
}

Request

GET /api/batch/{id_of_batch}

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> YES

Response

{
    "state":"COMPLETED",
    "batch_completed":true,
    "items_finished":10,
    "items_count":10
}

Response

Parameter’s name Parameter’s description Data’s type
state Status of the batch string,can gain values state
batch_completed Batch completed boolean
items_finished Number of finished items long
items_count Total count of items long

Details of superCASH coupons for the batch

The function lists details of superCASH coupons for the batch. The ID of batch is specified in GET parameter of request URL.

Request

curl -v -N "https://gw.sandbox.gopay.com/api/supercash/coupon/find?batch_request_id=960614882&go_id=8123456789" \
-X "GET" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer UQH6YC1vnL4byosE+tquq/OzQAvRvWfkTAT/70UzF8Gfl8zfWybisHZ+jkJ2/cGcyigfPGZrWcAjYypwNwoc7DLSgs8Qyhbf3RqpMhY+s2o=" \

def _get_suppercash_coupon_batch(self):
       batch_id = 961667719

long batchId = 961667719;

SupercashBatch supercashBatch = null;

try {
    supercashBatch = connector
            .getAppToken(CLIENT_ID, CLIENT_SECRET, OAuth.SCOPE_PAYMENT_ALL)
            .getSupercashCouponBatch(8712700986L, batchId);
} catch (GPClientException e) {
    //
}

var batchId = 961667719;

try
{
    SupercashBatch result = connector.GetAppToken().GetSupercashCouponBatch(batchId, GOID);
    Console.WriteLine(result.ToString());
}
catch (GPClientException ex)
{
    //
}

Request

GET /api/supercash/coupon/find?batch_request_id={id_of_batch}&go_id={goid_of_eshop}

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> YES

Response

{
    "coupons":[{
        "supercash_coupon_id":100153130,
        "custom_id":"ID-123459",
        "barcode_image_url":"https://partner.sandbox.gopay.com/gp-gateways/supercash/generateImg.action?barCode=14950224806731495022480673149502",
        "supercash_number":"1495022480673",
        "barcode":"14950224806731495022480673149502",
        "date_created":"2017-05-17T14:01:20.364+0200",
        "date_valid_to":"2017-08-15",
        "payment_session_id_list":[3050400275]
        },
        {
        "supercash_coupon_id":100153141,
        "custom_id":"ID-123458",
        "barcode_image_url":"https://partner.sandbox.gopay.com/gp-gateways/supercash/generateImg.action?barCode=14950224823601495022482360149502",
        "supercash_number":"1495022482360",
        "barcode":"14950224823601495022482360149502",
        "date_created":"2017-05-17T14:01:22.310+0200",
        "date_valid_to":"2017-08-15",
        "payment_session_id_list":[3050400288]
        },
        ...
    ]
}

Response

Parameter’s name Parameter’s description Data’s type
supercash_coupon_id superCASH coupon’s ID string
custom_id Custom ID for coupon string
barcode_image_url superCASH barcode in JPG format string
supercash_number superCASH number string
barcode Barcode string
date_created Date of coupon’s creation yyyy-MM-dd’T'HH:mm:ss.SSSZ
date_valid_to Date of the coupon’s validity string, yyyy-mm-dd
payment_session_id_list List of payments’ IDs string

Details of superCASH coupons for the payment

The function lists details of superCASH coupons for the payment. The ID of payment is specified in GET parameter of request URL. More payments are separated with comma separator.

Request

curl -v -N "https://gw.sandbox.gopay.com/api/supercash/coupon/find?payment_session_id_list={3050400405,3050400392}&go_id=8123456789" \
-X "GET" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer CuuEOc6RJ14G0cWuVgXVb5U5VcrW4h6/mmu9wjbKj4Kfhy/0VzhRb2rBOasX5QHFlBjPlHl8XH5Q10BPWa0MYyVQgXN4cC3M4jiU6e5yMzc=" \

def _find_supercash_coupons(self):
       payment_session_id = [3050857992, 3050858018]
       #payment_session_id = 3050857992

//      long paymentSessionIds = 3050857992L;
        Long[] paymentSessionIds = new Long[] { 3050857992L, 3050858018L };

        SupercashBatch supercashBatch = null;

        try {
            supercashBatch = connector
                    .getAppToken(CLIENT_ID, CLIENT_SECRET, OAuth.SCOPE_PAYMENT_ALL)
                    .findSupercashCoupons(8712700986L, paymentSessionIds);
        } catch (GPClientException e) {
            //
        }

    }

//long[] paymentSessionIds = new long[] { 3050857992, 3050858018 };
long paymentSessionIds = 3050857992;

try
{
    SupercashBatch result = connector.GetAppToken().FindSupercashCoupons(GOID, paymentSessionIds);
    Console.WriteLine(result.ToString());
}
catch (GPClientException ex)
{
    //
}

Request

GET /api/supercash/coupon/find?payment_session_id_list={id_of_payment}&go_id={goid_of_eshop}

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> YES

Response

{
    "coupons":[{
        "supercash_coupon_id":100153229,
        "custom_id":"ID-123457",
        "barcode_image_url":"https://partner.sandbox.gopay.com/gp-gateways/supercash/generateImg.action?barCode=14950224995111495022499511149502",
        "supercash_number":"1495022499511",
        "barcode":"14950224995111495022499511149502",
        "date_created":"2017-05-17T14:01:39.462+0200",
        "date_valid_to":"2017-08-15",
        "payment_session_id_list":[3050400405]}
    ]
}
{
    "coupons":[{
        "supercash_coupon_id":100153218,
        "custom_id":"ID-123457",
        "barcode_image_url":"https://partner.sandbox.gopay.com/gp-gateways/supercash/generateImg.action?barCode=14950224973471495022497347149502",
        "supercash_number":"1495022497347",
        "barcode":"14950224973471495022497347149502",
        "date_created":"2017-05-17T14:01:37.297+0200",
        "date_valid_to":"2017-08-15",
        "payment_session_id_list":[3050400392]}
    ]
}

Response

Parameter’s name Parameter’s description Data’s type
supercash_coupon_id superCASH coupon’s ID string
custom_id Custom ID for coupon string
barcode_image_url superCASH barcode in JPG format string
supercash_number superCASH number string
barcode Barcode string
date_created Date of coupon’s creation yyyy-MM-dd’T'HH:mm:ss.SSSZ
date_valid_to Date of the coupon’s validity string, yyyy-mm-dd
payment_session_id_list List of payments’ IDs string

Details of superCASH coupon

The function lists details of superCASH coupons.

Request

curl -v -N https://gw.sandbox.gopay.com/api/supercash/coupon/100153229 \
-X "GET" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer Ufgxd1w6C4rvm/UD8PovgE4fV9phwJKTEbWFQeoWY69w9Ph7+qFCajyBxVz75k7/G6yGhQpwFmgPfB9cahnJR6wp8ja/mX8x/0wAlgbX1o8=" \

def _get_supercash_coupon(self):
        coupon_id = 100154175

long couponId = 100154175;

SupercashPayment supercashPayment = null;

try {
    supercashPayment = connector
            .getAppToken(CLIENT_ID, CLIENT_SECRET, OAuth.SCOPE_PAYMENT_ALL)
            .getSupercashCoupon(couponId);
} catch (GPClientException e) {
    //
}

long couponId = 100154175;

try
{
    SupercashPayment result = connector.GetAppToken().GetSupercashCoupon(couponId);
    Console.WriteLine(result.ToString());
}
catch (GPClientException ex)
{
    //
}

Request

GET /api/supercash/coupon/{id_of_coupon}

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> YES

Response

{
    "coupons":[{
        "supercash_coupon_id":100153229,
        "custom_id":"ID-123457",
        "barcode_image_url":"https://partner.sandbox.gopay.com/gp-gateways/supercash/generateImg.action?barCode=14950224995111495022499511149502",
        "supercash_number":"1495022499511",
        "barcode":"14950224995111495022499511149502",
        "date_created":"2017-05-17T14:01:39.462+0200",
        "date_valid_to":"2017-08-15",
        "payment_session_id_list":[3050400405]}
    ]
}

Response

Parameter’s name Parameter’s description Data’s type
supercash_coupon_id superCASH coupon’s ID string
custom_id Custom ID for coupon string
barcode_image_url superCASH barcode in JPG format string
supercash_number superCASH number string
barcode Barcode string
date_created Date of coupon’s creation yyyy-MM-dd’T'HH:mm:ss.SSSZ
date_valid_to Date of the coupon’s validity string, yyyy-mm-dd
payment_session_id_list List of payments’ IDs string

Verification payment

The function of verification payment via payment card allow to making payments on the e-shop with customers’s unique payment card. The functionality also guarantee that the customer has got full access to authorize transactions with the payment card.

The first verification 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.

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer xzZnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p" \
-d '{
    "payer": {
            "allowed_payment_instruments":["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"
            },
    "target": {"type":"ACCOUNT",
               "goid":"8123456789"
              },
    "amount":"1000",
    "currency":"CZK",
    "order_number":"001",
    "order_description":"pojisteni01",
    "items":[{"name":"item01","amount":"500"},
             {"name":"item02","amount":"500"}],
    "preauthorization":"true",
    "additional_params":[{"name":"invoicenumber",
                          "value":"2015001003"
                        }],
    "callback":{
                "return_url":"http://www.eshop.cz/return",
                "notification_url":"http://www.eshop.cz/notify"
               }
}'

Request

POST /api/payments/payment

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
payer Object describing the payer of the payment YES Object
target Object describing the target of the payment (payee) YES Object
amount Amount in cents YES long > 0
currency Specifies the currency of the payment, currency format corresponding to ISO 4217 YES string, can gain values see currency
order_number Order identification within the point of sale YES string, alphanumeric characters only (128 characters)
order_description Description of goods / service NO string, alphanumeric characters only (256 characters)
items Itemized in detail each item of the order YES Object array
preauthorization Activation of pre-authorized payment YES bool
additional_params Additional parameters of the payment NO Object array
callback Callback URL and notification URL for change in the payment status YES Object

Response

{
  "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":"en",
  "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF "
}

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
order_number order ID string, alphanumeric characters only (128 characters)
state Payment status string, can gain values see state
amount Amount in cents long > 0
payer Object describing the payer of the payment Object
target Object describing the target of the payment (payee) Object
preauthorization Object describing the pre-authorization Object
additional_params Additional parameters of the payment Object array
lang Payment language string, can gain values see lang
gw_url URL to initiate the payment gateway string

Status of the payment

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.

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

For the verification payment functionality the response of payment status contains “card_token” a “3ds_result” parameters in payment_card object.

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment/3000006542 \
-X "GET" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969"

Request

GET /api/payments/payment/{id}

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/x-www-form-urlencoded YES
Authorization Bearer <access-token> YES

Response.

{
  "id":3000006542,
  "order_number":"001",
  "state":"AUTHORIZED",
  "sub_state":"_3002",
  "amount":1000,
  "currency":"CZK",
  "payment_instrument":"PAYMENT_CARD",
  "payer":{
           "payment_card": {
                      "card_number":"444444******4448",
                      "card_expiration":"1909",
                      "card_brand":"VISA",
                      "card_issuer_country":"CZE",
                      "card_issuer_bank":"AIR BANK, A.S.",
                      "card_token":"6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcb",
                      "3ds_result":"Y/Y"
                      },
           "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
          },
  "additional_params":[{"name":"invoicenumber",
                        "value":"2015001003"
                      }],
  "lang":"cs",
  "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}  

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
order_number Order identification within the point of sale string, alphanumeric characters only (128 characters)
state Payment status string, can gain values see state
sub_state Payment substate string, can gain values see sub_state
amount Amount in cents long > 0
currency Payment currency string, can gain values see currency
payment_instrument Code of chosen payment method string, can gain values see payment_instrument
payer Object describing the payer of payment Object
target Object describing the target of payment (payee) Object
recurrence Object describing the recurring payment Object
additional_params Additional parameters of the payment Object array
lang Payment language string, can gain values see lang
gw_url URL for redirecting to the payment gateway string

The next verification payment

The request for creation of the next verification payment is based on standard payment creation with use of “allowed_card_token” parameter that is returned in payment status response of the first verification payment.

Request

curl -v -N https://gw.sandbox.gopay.com/api/payments/payment \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer xzZnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p" \
-d '{
    "payer": {
                "allowed_payment_instruments":["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"
              },
    "target": {
                "type":"ACCOUNT",
                "goid":"8123456789"
              },
    "amount":"1000",
    "currency":"CZK",
    "order_number":"001",
    "order_description":"pojisteni01",
    "items":[{"name":"item01","amount":"500"},
             {"name":"item02","amount":"500"}
            ],
    "additional_params":[{"name":"invoicenumber",
                          "value":"2015001003"
                        }],
    "callback":{
                "return_url":"http://www.eshop.cz/return",
                "notification_url":"http://www.eshop.cz/notify"
              },
    "lang":"en"
}'

Request

POST /api/payments/payment

Header of request

Parameter’s name Parameter’s description Required
Accept application/json YES
Content-Type application/json YES
Authorization Bearer <access-token> YES

Body of request

Parameter’s name Parameter’s description Required Data’s type
payer The object describing the payer of the payment YES Object
target The object describing the target of the payment (payee) YES Object
amount Amount in cents YES long > 0
currency Specifies the currency of payment, currency format corresponds to ISO 4217 YES string
order_number Identification of the order within the point of sale YES string, alphanumeric characters only (128 characters)
order_description Description of goods / service NO string, alphanumeric characters only (256 characters)
items Itemized in detail each item of the order YES Object
callback Callback URL for processing of the payment result / Notification URL for processing of change of payment status YES Object
additional_params Additional payment parameters No According to object
lang Parameters defines language of the payment NO string, can gain values see lang

Response

{
  "id":3000006529,
  "order_number":"001",
  "state":"CREATED",
  "amount":1000,"currency":"CZK",
  "payer":{,
           "allowed_payment_instruments":["PAYMENT_CARD"],
           "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
          },
  "additional_params":[{"name":"invoicenumber",
                        "value":"2015001003"
                      }],
  "lang":"en",
  "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}  

Response

Parameter’s name Parameter’s description Data’s type
id Payment ID long
order_number Identification of order string, alphanumeric characters only (128 characters)
state Payment status string, can gain values see state
amount Amount in cents long > 0
currency Specifies the currency of payment string, can gain values see currency
payer Object describing the payer of the payment Object
target Object describing the target of the payment (payee) Object
additional_params Additional parameters of payments Object array
lang Parameter defines payment language string, can gain values see lang
gw_url URL for initiation of the payment gate string

Objects

Description of each object used within the communication with the payment gateway.

payer

Definition of the payer or the payment

 {
   "allowed_payment_instruments":["PAYMENT_CARD", "BANK_ACCOUNT"],
   "default_payment_instrument":"BANK_ACCOUNT",
   "default_swift":"GIBACZPX",
   "allowed_swifts":["FIOBCZPP","BREXCZPP"],
   "bank_account":{},
   "contact": {}
 }
Parameter´s name Parameter´s description Data´s type
allowed_payment_instruments Array of allowed payment methods string, can gain values of payment_instrument
default_payment_instrument Preferred payment method string, can gain values of payment_instrument
default_swift Preferred bank if default_payment_instrument is set to BANK_ACCOUNT, set by SWIFT code string, can gain values of SWIFT
allowed_swifts Array of allowed bank codes string, can gain values of SWIFT
bank_account Bank account´s information Object
payment_card Payment card´s information Object
contact Customer´s data Object
verify_pin PIN for verification payment purposes String, 4 digits
allowed_card_token Token for verification payment purposes String

bank_account

Bank account´s information

{
    "prefix":"670100",
    "account_number":"7654322",
    "bank_code":"0100",
    "account_name":"JAN NOVAK"
}
Parameter´s name Parameter´s description Data´s type
iban International bank account number string, 50 characters
bic Business identification code (SWIFT) string, 11 characters
prefix Bank account prefix string, 64 characters
account_number Bank account number string, 128 characters
bank_code Bank account code string, 8 characters
account_name Bank account name string, 70 characters

payment_card

Payment card´s information

{
    "card_number":"444444******4448",
    "card_expiration":"1909",
    "card_brand":"VISA",
    "card_issuer_country":"CZE",
    "card_issuer_bank":"AIR BANK, A.S."
}
Parameter´s name Parameter´s description Data´s type
card_number Masked payment card´s number string, 16 characters
card_expiration Expiration date string, 4 characters
card_brand Payment card´s type string, 50 characters
card_issuer_country Country code of issuing bank string, 3 characters
card_issuer_bank Issuing bank string, 80 characters
card_token Token for verification payment purposes string
3ds_result 3D Secure authorization’s result string

contact

Customer´s information

{
   "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"
}
Parameter´s name Parameter´s description Data´s type
first_name First name string, 256 characters
last_name Last name string, 256 characters
email E-mail string, 128 characters
phone_number Phone number with country code string 128 characters
city City string, 128 characters
street Street string, 128 characters
postal_code Postal code string 16 characters
country_code Country code string ISO 3166-1 alpha-3

target

Identification of the payee

{
  "type":"ACCOUNT",
  "goid":"8123456789"
}
Parameter´s name Parameter´s description Data´s type
type Description of payee string, set to ACCOUNT
goid Unique identifier of an e-shop in the payment gateway system long

items

Each item of the order

[
    "type":"ITEM", 
    "name":"obuv",
    "product_url":"https://www.eshop.cz/boty/lodicky", 
    "ean":1234567890123,
    "amount":119990,
    "count":1,
    "vat_rate":21
]
Parameter´s name Parameter´s description Data´s type
type Type of row, for registration of sales enum, can gain values see type
product_url URL address of the product string
ean EAN code of the product varchar, (13 characters)
count Number of items long > 0
name Product name string, alphanumeric characters (256 characters)
amount Total price of items in cents long, positive or negative integers
vat_rate VAT rate, for registration of sales can gain values see vat_rate

eet

Parameters for registration of sales

[
    "celk_trzba":139950,
    "zakl_dan1":99165,
    "dan1":20825,
    "zakl_dan2":17357,
    "dan2":2604,
    "mena":"CZK"
]
Parameter´s name Parameter´s description Data´s type
dic_poverujiciho DIČ of the entrustment taxpayer varchar
celk_trzba The total amount long in cents
zakl_nepodl_dph The total amount of supplies exempt from VAT long in cents
zakl_dan1 The total tax base amount, the basic VAT rate long in cents
dan1 The total amount of VAT, the basic rate long in cents
zakl_dan2 The total tax base amount with a first reduced rate of VAT long in cents
dan2 The total VAT amount with a first reduced rate long in cents
zakl_dan The total tax base amount with a second reduced rate of VAT long in cents
dan3 The total VAT amount with a second reduced rate long in cents
cest_sluz The total amount of the VAT regime for travel service long in cents
pouzit_zboz1 The total amount of the VAT regime for the sale of used goods with a basic rate long in cents
pouzit_zboz2 The total amount of the VAT regime for the sale of used goods with a first reduced rate long in cents
pouzit_zboz3 The total amount of the VAT regime for the sale of used goods with a second reduced rate long in cents
urceno_cerp_zuct The total amount of payments designated for subsequent pumping or settlement long in cents
cerp_zuct The total amount of payments which are followed by pumping or settlement of the payment long in cents
mena Currency of the parameters string

eetCode

Information about registration of sales

{
    "fik":"28da0811-e050-46c7-a62c-aa456d1f07ef-ff",
    "bkp":"5d874afc-251f8661-ff0e0b13-c7cd8793-6bf0386a",
    "pkp":"Ca8sTbURReQjjgcy/znXBKjPOnZof3AxWK5WySpyMrUXF0o7cz1BP6a....."
}
Parameter´s name Parameter´s description Data´s type
fik Fiscal identification code (FIK) varchar, 39 characters
bkp Security code of the taxpayer (BKP) varchar, 44 characters
pkp Signature code of the taxpayer (PKP) varchar, 344 characters

callback

Definition of callback and notification URL

{
   "return_url":"http://www.eshop.cz/return",
   "notification_url":"http://www.eshop.cz/notify"
}
Parameter´s name Parameter´s description Data´s type
return_url URL address for return to e-shop (with protocol) string
notification_url URL address for sending asynchronous notification in the case of changes in the payment status (with protocol) string

additional_params

Additional parameters of the payment

[
   {"name":"invoicenumber","value":"2015001003"},
   {"name":"...","value":"..."}
]
Parameter´s name Parameter´s description Data´s type
name Parameter name string
value Value of optional parameter string

recurrence

Setting of recurring payment

Recurring each seventh day

{
  "recurrence_cycle":"DAY",
  "recurrence_period":"7",
  "recurrence_date_to":"2015-12-31"
}

Recurring each third day

{
  "recurrence_cycle":"DAY",
  "recurrence_period":"3",
  "recurrence_date_to":"2015-12-31"
}

Recurring each second month

{
  "recurrence_cycle":"MONTH",
  "recurrence_period":"2",
  "recurrence_date_to":"2015-12-31"
}
Parameter´s name Parameter´s description Data´s type
recurrence_cycle Time period of recurring string, can gain values see recurrence_cycle
recurrence_period Recurring period of recurring payment long
recurrence_date_to The period of validity recurring payment string yyyy-mm-dd
recurrence_state Describes state of recurring payment string, can gain values REQUESTED, STARTED, STOPPED

groups

Name of every group corresponds to group codes

Parameter´s name Parameter´s description
label Object that contains localised name of payment group
cs Czech name of payment group

group-codes

Names of payment method groups

"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í"}
      }
    }
Group name Group description
card-payment Payment card payments
bank-transfer Bank transfers
wallet E-wallet payments
others Other payment methods

enabledPaymentInstruments

Name of every object coresponds to payment method codes

  "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},
                ...
            }]
Parameter´s name Parameter´s description
label Object that contains localised name of payment method
image Logo of payment method avaliable in two formats - normal, large
group Group into which payment method belongs, coresponds to groups
enabledSwifts Each sub object represents allowed banks for payment method. It is set only for BANK_ACCOUNT

enabledSwifts

Name of each object coresponds to SWIFT codes

"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},
    ...
    ]}
Parameter´s name Parameter´s description
label Object that contains localised name of bank
image Logo of bank avaliable in two formats - normal, large
isOnline State that symbolise if bank supports online bank transfers

defaults

Default values of superCASH coupons

"defaults":{
    "sub_type":"POSTPAID",
    "amounts":[300,400,500,600,700,800,900,1000],
    "order_description":"supercash batch test"
}
Parameter´s name Parameter´s description
sub_type Type of superCASH coupon
custom_id Custom ID for coupon
amounts Array of amounts in cents
order_number Identification of the order within the point of sale
order_description Description of goods/service
buyer_email Valid e-mail address
buyer_phone Phone number with country code
date_valid_to Date of the coupon’s validity
notification_url URL address for sending asynchronous notification in the case of changes in the coupon’s status (with protocol)

coupons

Specific values of superCASH coupons

"coupons":[
                {
                    "buyer_email":"zakaznik1@example.com",
                    "custom_id":"ID-123457",
                    "buyer_phone":"+420777666111",
                    "amounts":[100]
                },
                {
                    "buyer_email":"zakaznik2@example.com",
                    "custom_id":"ID-123458",
                    "buyer_phone":"+420777666222",
                    "amounts":[200]
                },
                {
                    "buyer_email":"zakaznik3@example.com",
                    "custom_id":"ID-123459",
                    "buyer_phone":"+420777666333"
                }
            ]
Parameter´s name Parameter´s description
sub_type Type of superCASH coupon
custom_id Custom ID for coupon
amounts Array of amounts in cents
order_number Identification of the order within the point of sale
order_description Description of goods/service
buyer_email Valid e-mail address
buyer_phone Phone number with country code
date_valid_to Date of the coupon’s validity
notification_url URL address for sending asynchronous notification in the case of changes in the coupon’s status (with protocol)

Code lists

recurrence_cycle

Cycle of recurring payment

Parameter’s value Description
DAY Daily recurring
WEEK Weekly recurring
MONTH Monthly recurring
ON_DEMAND Set only at manual recurring payments

currency

Payment currency

Parameter’s value Description
CZK Czech crowns
EUR Euros
PLN Polish złoty
HUF Hungarian forint
GBP British pound
USD US dollar
RON Romanian Leu
HRK Kuna
BGN Bulgarian Lev

scope

Parameter describing group of acquired rights

Parameter’s value Description
payment-create Allows only the establishment of payments
payment-all Allows all operations above payments

result

Result of operation

Parameter’s name Parameter’s description
ACCEPTED Request accepted
FINISHED Operation finished
FAILED Operation failed

Payment status

Payment can gain values following status

Parameter’s name Parameter’s description
CREATED Payment created
PAYMENT_METHOD_CHOSEN Payment method chosen
PAID Payment paid
AUTHORIZED Payment pre-authorized
CANCELED Payment canceled
TIMEOUTED Payment timeouted
REFUNDED Payment refunded
PARTIALLY_REFUNDED Payment partially refunded

Payment substate

Payment can gain values following substates

Parameter’s value Parameter’s description
_101 Payment pending. We are waiting for the online payment to be made.
_102 Payment pending. We are waiting for the offline payment to be made.
_3001 Bank payment confirmed by letter of advice.
_3002 Bank payment confirmed by statement.
_3003 Bank payment not authorised.
_5002 Payment declined by the customer’s bank authorization centre. The payment card limit had been reached.
_5003 Payment declined by the customer’s bank authorization centre. There are some issues at the card issuer side.
_5004 Payment declined by the customer’s bank authorization centre. Issues at the card issuer side.
_5005 Payment declined by the customer’s bank authorization centre. Payment card blocked.
_5006 Payment declined by the customer’s bank authorization centre. Insufficient funds at the payment card.
_5007 Payment declined by the customer’s bank authorization centre. The payment card is expired.
_5008 Payment declined by the customer’s bank authorization centre. The CVV/CVC code had been declined.
_5009, _5015, _5017, _5018, _5019, _6502, _6504 Payment declined in the 3D Secure system of the customer’s bank.
_5010, _5014 Payment declined by the customer’s bank authorization centre. There are some issues with the payment card.
_5011, _5036 Payment declined by the customer’s bank authorization centre. There are some issues with the payment card account.
_5012 Payment declined by the customer’s bank authorization centre. There are some technical issues in the customer’s bank authorization centre.
_5013 Payment declined by the customer’s bank authorization centre. The customer entered an incorrect card number.
_5016 Payment declined by the customer’s bank authorization centre. The customer’s card had not been authorized to make the payment.
_5021 Payment declined by the customer’s bank authorization centre. The card limits had been exceeded.
_5022 A technical issue occured in the customer’s bank authorization centre.
_5023, _5038 Payment not made.
_5024 Payment not made. Customer did not enter the payment credentials in the time limit at the payment gateway.
_5025 Payment not made. The specific reason is to be reported to the customer.
_5026 Payment not made. The total credited amounts exceeded the amount paid.
_5027 Payment not made. The user is not authorized to undertake the operation.
_5028 Payment not made. The amount due exceeded the amount authorized.
_5029 Payment has not been made yet.
_5030 Payment not made. There were several attempts to settle the payment.
_5031 A technical issue occurred in the bank while processing the payment.
_5033 SMS failed to be received.
_5035 Card issued in a region where the card payments are not supported.
_5037 Cardholder cancelled the payment.
_5039 Payment declined by the customer’s bank authorization centre. The payment card is blocked.
_5042 Bank transfer declined.
_5043 Payment cancelled by user.
_5044 SMS has been sent. It has not been delivered yet.
_5045 Payment received. Payment is to be credited after it has been processed in the Bitcoin system.
_5046 A full amount of payment not made.
_5047 Payment made after due date.

lang

Setting of the language of the payment gateway

Language’s code Language
CS Czech
EN English
SK Slovak
DE German
RU Russian
PL Polish
HU Hungarian
FR French
RO Romanian

payment_instrument

Payment method codes

Payment method’s code Payment method’s description
PAYMENT_CARD Payment cards
BANK_ACCOUNT Bank transfer
PRSMS Premium SMS
MPAYMENT mPayment
PAYSAFECARD Paysafecard
SUPERCASH superCASH
GOPAY GoPay account
PAYPAL PayPal account
BITCOIN Bitcoin payment

SWIFT

Bank SWIFT codes

Bank SWIFT code Bank name
GIBACZPX Česká spořitelna
KOMBCZPP Komerční Banka
RZBCCZPP Raiffeisenbank
BREXCZPP mBank
FIOBCZPP FIO Bank
CEKOCZPP ČSOB
CEKOCZPP-ERA ERA
SUBASKBX Všeobecná úverová banka
TATRSKBX Tatra Banka
UNCRSKBX Unicredit Bank SK
GIBASKBX Slovenská spořitelna
POBNSKBA Poštová Banka
CEKOSKBX ČSOB SK
LUBASKBX Sberbank Slovensko
OTHERS Special SWIFT without specific bank selected
BREXPLPW mBank
CITIPLPX Citi Handlowy
BPKOPLPW-IKO IKO
BPKOPLPW-INTELIGO Inteligo
IVSEPLPP Plus Bank
BPHKPLPK BANK BPH S.A.
TOBAPLPW Toyota Bank
VOWAPLP1 Volkswagen Bank
GBWCPLPP SGB
POCZPLP4 Pocztowy bank
GOPZPLPW BGZ Bank
IEEAPLPA IDEA
POLUPLPR BPS
GBGCPLPK-GIO Getin Online
GBGCPLPK-BLIK Blik
GBGCPLPK-NOB Noble bank
BREXPLPW-OMB Orange
WBKPPLPP BZ WBK
RCBWPLPW RAIFFEISEN BANK POLSKA S.A.
BPKOPLPW POWSZECHNA KASA OSZCZEDNOSCI BANK POLSKI SA
ALBPPLPW Alior Bank
INGBPLPW ING Bank Śląski
PKOPPLPW PEKAO S.A
GBGCPLPK Getin Online
BIGBPLPW Bank Millennium
EBOSPLPW Bank Ochrony Środowiska
PPABPLPK BNP Paribas Polska
AGRIPLPR Credit Agricole
DEUTPLPX DEUTSCHE BANK POLSKA S.A.
DNBANOKK DnB Nord
NBPLPLPW E-SKOK
SOGEPLPW Eurobank
PBPBPLPW POLSKI BANK PRZEDSIEBIORCZOSCI SPOLKA AKCYJNA

format

Format of account statement file

Parameter’s value Description
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 (.gpc)

type

Type of row for the registration of sales

Parameter’s value Description
ITEM Item
DELIVERY Delivery
DISCOUNT Discount

vat_rate

VAT rate for the registration of sales

Parameter’s value Description
0 VAT rate 0 %
10 VAT rate 10 %
15 VAT rate 15 %
21 VAT rate 21 %

state

Parameter’s value Description
CREATED Created
DELIVERY_FAILED Delivery failed
DELIVERED Delivered

eet_mode

Parameter’s value Description
AUTO variant A
EET variant B

state of superCASH batch

Parameter’s value Description
CREATED Created
RUNNING Running
QUEUED Queued
SCHEDULED Scheduled
COMPLETED Completed
STOPPED Stopped
FAILED Failed

sub_type

Type of superCASH coupon

Parameter’s value Description
POSTPAID Coupon suitable for one-time payment. Payment is generated with coupon creation.
PREPAID Coupon suitable for multiple payments. Payment is generated after each customer’s payment.

3ds_result

3D Secure authorization’s result

Parameter’s value Description
“N/” The payment card doesn’t support 3D Secure authorization
“Y/Y” Full 3D Secure authorization
“Y/A” Partial 3D Secure authorization
“X/X” 3D Secure authorization was not made

Errors

HTTP result codes

HTTP code Meaning of code
200 Calling was successful
403 Not-authorized access
409 Validation errors
500 Calling ended with error
404 Service does not exist

Return errors

Example of error response - field specific

{"date_issued":1390336022001,
"errors":[
    {"scope":"F","field":"email","message":"E-mail already existed.","error_code":112,"error_name":"NOT_UNIQUE"},
    {"scope":"F","field":"mobile_phone","message":"Mobile phone already existed.","error_code":112,"error_name":"NOT_UNIQUE"}
]}

Example of error response - global

{"scope":"G","field":null,"error_code":500,"error_name":null,"message":null,"description":null}

Detail of error is described in body of response as application/json datas of next structure

Parameter Parameter’s description
date issued timestamp of error moment
errors List of error messages

errors

Parameter Parameter’s description
scope F - field specific, G - global
field Set only in case of validation error joined with field
message Localized message. Localization based on Accept-Language header. Localization is set to en-US by default. It is possible to use Accept-Language: cs header for czech localization.
description Technical description of error
error_code Numbers type of error
error_name Code type of error

List of errors

Global

Code Description
100 System error
110 Required
111 Error format
112 Already existed
113 Not possible to change
114 Not possible to delete
115 Not clear
116 Invalid request

Authentication, authorization

Code Description
200 Not authorized access
201 Method of allocation of rights is not supported
202 Wrong access data
203 Access via PIN was deactivated

Payment

Code Description
350 Charged of payment failed
351 Charged of payment was successful
352 Cancel of pre-authorization failed
353 Cancel of pre-authorization was successful
340 Recurring payment failed
341 Recurring payment is not supported
342 Recurring payment was stopped
343 Number of attempts to recure payment was exceeded
330 Payment is not possible to refund
331 Payment is not possible to refund
332 Wrong amount
333 Not sufficient funds on account
301 Not possible to create a payment
302 Not possible to make a payment
303 Payment in wrong state
304 Payment not found