# Contributte / Gopay-Inline

# Content

# Prolog

This library has no dependencies on other php libraries. It provides easy-to-use API for communication with GoPay REST API v3, known as GoPay Inline.

# Install

Install Markette/GopayInline over composer.

composer require markette/gopay-inline
1

Why is the package still called Markette? Because we don't want to break other people's projects (for now).

# Requirements

From GoPay you need:

  • GoID
  • ClientID
  • ClientSecret

On server you need:

  • PHP >= 5.6
  • cURL

# Resources / Docs

# Examples

All you can find in examples folder (opens new window).

# Library

There are 3 main parts of this library.

# 1) Client

A core class holding credentials, token, authenticator and http client. It could make authentication and requests to endpoints.

# 2) HttpClient

Delegates all requests / responses to IO. All requests go over cURL. There is a place for other implementation, go for it.

# 3) Services

Services provide easy-to-use API for creating and verifying payments.

# Supported API

  • Verify payments ($client->payments->verify(..))
  • Standard payments ($client->payments->createPayment(..))
  • Recurrent payments ($client->payments->createRecurrentPayment(..))
  • Preauthorized payments ($client->payments->createPreauthorizedPayment(..))

# Usage

# Authentication

First you need set up client with credentials.

use Contributte\GopayInline\Client;
use Contributte\GopayInline\Config;

$goId = 'GoID';
$clientId = 'ClientID';
$clientSecret = 'ClientSecret';

// TEST MODE
$client = new Client(new Config($goId, $clientId, $clientSecret));
$client = new Client(new Config($goId, $clientId, $clientSecret, $mode = Config::TEST));

// PROD MODE
$client = new Client(new Config($goId, $clientId, $clientSecret, $mode = Config::PROD));
1
2
3
4
5
6
7
8
9
10
11
12
13

Then you have to authenticate with oauth2 authority server on GoPay.

For only creating payments use Scope::PAYMENT_CREATE, for the rest Scope::PAYMENT_ALL.

use Contributte\GopayInline\Api\Lists\Scope;

$token = $client->authenticate(['scope' => Scope::PAYMENT_CREATE]);
1
2
3

Heureka! We have token, let's make some API request.

# Creating payment request

This example of payment data was copied from official documentation.

use Contributte\GopayInline\Api\Entity\PaymentFactory;
use Contributte\GopayInline\Api\Lists\Currency;
use Contributte\GopayInline\Api\Lists\Language;
use Contributte\GopayInline\Api\Lists\PaymentInstrument;
use Contributte\GopayInline\Api\Lists\SwiftCode;

$payment = [
	'payer' => [
		'default_payment_instrument' => PaymentInstrument::BANK_ACCOUNT,
		'allowed_payment_instruments' => [PaymentInstrument::BANK_ACCOUNT],
		'default_swift' => SwiftCode::FIO_BANKA,
		'allowed_swifts' => [SwiftCode::FIO_BANKA, SwiftCode::MBANK],
		'contact' => [
			'first_name' => 'John',
			'last_name' => 'Doe',
			'email' => 'johndoe@contributte.org',
			'phone_number' => '+420123456789',
			'city' => 'Prague',
			'street' => 'Contributte 123',
			'postal_code' => '123 45',
			'country_code' => 'CZE',
		],
	],
	'amount' => \Money\Money::CZK(50000),
	'order_number' => '001',
	'order_description' => 'some order',
	'items' => [
		['name' => 'item01', 'amount' => \Money\Money::CZK(40000)],
		['name' => 'item02', 'amount' => \Money\Money::CZK(13000)],
		['name' => 'item03', 'amount' => \Money\Money::CZK(7000)],
	],
	'eet' => [
		'celk_trzba' => \Money\Money::CZK(50000),
		'zakl_dan1' => \Money\Money::CZK(35000),
		'dan1' => \Money\Money::CZK(5000),
		'zakl_dan2' => \Money\Money::CZK(8000),
		'dan2' => \Money\Money::CZK(2000),
		'mena' => Currency::CZK,
	],
	'additional_params' => [
		['name' => 'invoicenumber', 'value' => '2017001'],
	],
	'callback' => [
		'return_url' => 'http://www.myeshop.cz/api/gopay/return',
		'notify_url' => 'http://www.myeshop.cz/api/gopay/notify',
	],
	'lang' => Language::CZ,
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
// Create payment request
$response = $client->payments->createPayment(PaymentFactory::create($payment));
$data = $response->getData();
1
2
3

$client->payments returns PaymentsService, you can create this service also by $client->createPaymentsService().

PaymentsService::createPayment need object of Payment, you can set-up it manually by yourself or via PaymentFactory. But over PaymentFactory, there is parameters validation and price validation.

# Tips

You cannot combine more payment instruments (according to GoPay Gateway implementation). So, you should create payment only with one payment instrument, for example only with BANK_ACCOUNT or PAYMENT_CARD.

# For ALL payment instruments

use Contributte\GopayInline\Api\Lists\PaymentInstrument;

$payment['payer']['allowed_payment_instruments']= PaymentInstrument::all();
1
2
3

# For ALL / CZ / SK swift codes

Use allowed_swifts and default_swift only with BANK_ACCOUNT.

use Contributte\GopayInline\Api\Lists\SwiftCode;

$payment['payer']['allowed_swifts']= SwiftCode::all();
// or
$payment['payer']['allowed_swifts']= SwiftCode::cz();
// or
$payment['payer']['allowed_swifts']= SwiftCode::sk();
1
2
3
4
5
6
7

# Process payment

Now we have a response with payment information. There's same data as we send it before and also new $gw_url. It's in response data.

if ($response->isSuccess()) {
	// ...
}
1
2
3
$data = $response->getData();
$url = $data['gw_url'];

$url = $response->data['gw_url'];
$url = $response->gw_url;
$url = $response['gw_url'];

// Redirect to URL
// ...

// Send over AJAX to inline variant
// ...
1
2
3
4
5
6
7
8
9
10
11
12

In case of inline variant you can use prepared javascript (opens new window) (under development at this moment).

# Verify payment (check state)

All you need is $paymentId. Response is always the same.

// Verify payment
$response = $client->payments->verify($paymentId);
1
2

# Bridges

# Nette

Fill your credentials in config.

extensions:
	gopay: Contributte\GopayInline\Bridges\Nette\DI\GopayExtension

gopay:
	goId: ***
	clientId: ***
	clientSecret: ***
	test: on / off
1
2
3
4
5
6
7
8

Inject Client into your services / presenters;

use Contributte\GopayInline\Client;

/** @var Client @inject */
public $gopay;
1
2
3
4

# Class model

# Request

It contains information for cURL.

  • $url
  • $headers
  • $options
  • $data

# Response

It contains information after execution request. It could be success or failed.

  • $data
  • $headers
  • $code
  • $error