Skip to content
GoPay's PHP SDK for Payments REST API
Branch: master
Clone or download
FSichinger Merge pull request #33 from jkavalik/patch-1
update the documentation of Response::json property type from object to array
Latest commit bee33af Jan 7, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Update eet example Apr 28, 2017
tests Merge pull request #32 from florianjiri/fix/http_build_query-ArgSepar… Jul 10, 2018
.directory unit testy, pridani octetStreamBrowseru, formaty Mar 14, 2017
.travis.yml Update .travis.yml Aug 29, 2017
composer.json set phpunit version Jul 28, 2017
phpunit.xml.dist Gopay - remote authentication, test localizing errors Sep 23, 2015

GoPay's PHP SDK for Payments REST API

License Latest Stable Version Total Downloads Monthly Downloads Dependency Status

Build Status PHP runtimes

## Requirements

  • PHP >= 5.4.0
  • enabled extension curl, json

## Installation

The simplest way to install SDK is to use Composer:

composer require gopay/payments-sdk-php

Basic usage

// minimal configuration
$gopay = GoPay\Api::payments([
    'goid' => 'my goid',
    'clientId' => 'my id',
    'clientSecret' => 'my secret',
    'isProductionMode' => false

// full configuration
$gopay = GoPay\Api::payments([
    'goid' => 'my goid',
    'clientId' => 'my id',
    'clientSecret' => 'my secret',
    'isProductionMode' => false,
    'scope' => GoPay\Definition\TokenScope::ALL,
    'language' => GoPay\Definition\Language::CZECH,
    'timeout' => 30


Required fields

Required field Data type Documentation
goid string default GoPay account used in createPayment if target is not specified
clientId string
clientSecret string
isProductionMode boolean test or production environment?

Optional fields

Optional field Data type Default value Documentation
scope string GoPay\Definition\TokenScope::ALL
language string GoPay\Definition\Language::ENGLISH language used in createPayment if lang is not specified + used for localization of errors
timeout int 30 Browser timeout in seconds

### Available methods

API SDK method
Create standard payment $gopay->createPayment(array $payment)
Status of the payment $gopay->getStatus($id)
Refund of the payment $gopay->refundPayment($id, $amount)
Create recurring payment $gopay->createPayment(array $payment)
Recurring payment on demand $gopay->createRecurrence($id, array $payment)
Cancellation of the recurring payment $gopay->voidRecurrence($id)
Create pre-authorized payment $gopay->createPayment(array $payment)
Charge of pre-authorized payment $gopay->captureAuthorization($id)
Cancellation of the pre-authorized payment $gopay->voidAuthorization($id)

SDK response? Has my call succeed?

SDK returns wrapped API response. Every method returns GoPay\Http\Response object. Structure of json/__toString should be same as in documentation. SDK throws no exception. Please create an issue if you catch one.

$response = $gopay->createPayment([/* define your payment  */]);
if ($response->hasSucceed()) {
    echo "hooray, API returned {$response}";
    return $response->json['gw_url']; // url for initiation of gateway
} else {
    // errors format:
    echo "oops, API returned {$response->statusCode}: {$response}";
Method Description
$response->hasSucceed() checks if API returns status code 200
$response->json decoded response, returned objects are converted into associative arrays
$response->statusCode HTTP status code
$response->__toString() raw body from HTTP response

### Are required fields and allowed values validated?

No. API validates fields pretty extensively so there is no need to duplicate validation in SDK. It would only introduce new type of error. Or we would have to perfectly simulate API error messages. That's why SDK just calls API which behavior is well documented in

Advanced usage

Initiation of the payment gateway

// create payment and pass url to template 
$response = $gopay->createPayment([/* define your payment  */]);
if ($response->hasSucceed()) {
    $templateParameters = [
        'gatewayUrl' => $response->json['gw_url'],
        'embedJs' => $gopay->urlToEmbedJs()
    // render template

Inline gateway

<form action="<?php echo $gatewayUrl; ?>" method="post" id="gopay-payment-button">
  <button name="pay" type="submit">Pay</button>
  <script type="text/javascript" src="<?php echo $embedJs;>"></script>

Redirect gateway

<form action="<?php echo $gatewayUrl; ?>" method="post">
  <button name="pay" type="submit">Pay</button>

Asynchronous initialization using JavaScript

Enums (Code lists)

Instead of hardcoding bank codes string you can use predefined enums. Check using enums in create-payment example

Type Description
Language Payment language, localization of error messages
Token scope Authorization scope for OAuth2
Payment enums Enums for creating payment
Response enums Result of creating payment, executing payment operations
ItemType enums Type of an item
VatRate enums VatRate of an item

Framework integration

Cache access token

Access token expires after 30 minutes so it's expensive to use new token for every request. Unfortunately it's default behavior of GoPay\Token\InMemoryTokenCache. But you can implement your cache and store tokens in Memcache, Redis, files, ... It's up to you.

Your cache must implement GoPay\Token\TokenCache interface. Be aware that there are two scopes (TokenScope) and SDK can be used for different clients (clientId, isProductionMode). So client passed to methods is unique identifier (string) that is built for current environment. Below you can see example implementation of caching tokens in file:

// register cache in optional service configuration
$gopay = GoPay\payments(
    [/* your config */],
    ['cache' => new PrimitiveFileCache()]

use GoPay\Token\TokenCache;
use GoPay\Token\AccessToken;

class PrimitiveFileCache implements TokenCache
    public function setAccessToken($client, AccessToken $t)
        file_put_contents(__DIR__ . "/{$client}", serialize($t));

    public function getAccessToken($client)
        $file = __DIR__ . "/{$client}";
        if (file_exists($file)) {
            return unserialize(file_get_contents($file));
        return null; 

Log HTTP communication

You can log every request and response from communication with API. Check available loggers below. Or you can implement your own logger, just implement GoPay\Http\Log\Logger interface.

// register logger in optional service configuration
$gopay = GoPay\payments(
    [/* your config */],
    ['logger' => new GoPay\Http\Log\PrintHttpRequest()]
Available logger Description
NullLogger Default logger which does nothing
PrintHttpRequest Prints basic information about request and response, used in remote tests


Contributions from others would be very much appreciated! Send pull request/ issue. Thanks!


Copyright (c) 2015 MIT Licensed, see LICENSE for details.

You can’t perform that action at this time.