tarlanpayments / gw-client
Library to work with Tarlan Payments gateway v3.0
Requires
- php: ^7.0
- ext-curl: *
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.1
- jakub-onderka/php-parallel-lint: ^0.9.2
- phpunit/phpunit: ^6.0
README
This library provide ability to make requests to Tarlan Payments Gateway API v3.
Installation
Install the latest version with
$ composer require tarlanpayments/gw-client
Basic usage
Inside form
Hold card input form on gateway side, client must be redirect to gateway.
<?php use TarlanPayments\Gateway\Gateway; $gw = new Gateway(); // Setup gateway authorization credentials $gw->auth() ->setAccountGUID("3383e58e-9cde-4ffa-85cf-81cd25b2423e") ->setSecretKey('super-secret-key'); // Create transaction object $sms = $gw->createSms(); // Set required fields $sms->money() ->setAmount(100) ->setCurrency('USD'); $sms->customer() ->setEmail("email@domain.com") ->setPhone("2445224657"); $sms->order() ->setMerchantTransactionID('A-345S') ->setDescription('Order #A-345S payment'); // Process payment via gateway inside form $sms->insideForm(); // Build transaction object to request $smsRequest = $sms->build(); // Process transaction to gateway $response = $gw->process($smsRequest);
Server to server
Hold card input form on merchant side and process via API.
<?php use TarlanPayments\Gateway\Gateway; $gw = new Gateway(); // Setup gatewayl authorization credentials $gw->auth() ->setAccountGUID("3383e58e-9cde-4ffa-85cf-81cd25b2423e") ->setSecretKey('super-secret-key'); // Create transaction object $sms = $gw->createSms(); // Set required fields $sms->paymentMethod() ->setPAN('4295550031781065') ->setExpire('06/18') ->setCVV('683') ->setCardHolderName('John Doe'); $sms->money() ->setAmount(100) ->setCurrency('USD'); // Build transaction object to request $smsRequest = $sms->build(); // Process transaction to gateway $response = $gw->process($smsRequest);
Documentation
This README
provide introduction to the library usage.
Operations
Operations are available via $gw->create<operation name>()
method.
Available operations:
- Transactions
- CANCEL
- DMS CHARGE
- DMS HOLD
- MOTO DMS
- MOTO SMS
- INIT RECURRENT DMS
- RECURRENT DMS
- INIT RECURRENT SMS
- RECURRENT SMS
- REFUND
- REVERSAL
- SMS
- Credit
- P2P
- B2P
- Information
- HISTORY
- RECURRENTS
- REFUNDS
- RESULT
- STATUS
- Verification
- 3-D Secure enrollment
- Complete card verification
- Tokenization
- Create payment data token
Pattern to work with the library can be described as follows:
<?php use TarlanPayments\Gateway\Gateway; $gw = new Gateway(); // first, you need to setup authorization. // you can change authorization data in runtime. // Thus, following operations will work under // new authorization. $gw->auth() ->setAccountGUID("3383e58e-9cde-4ffa-85cf-81cd25b2423e") ->setSecretKey('super-secret-key'); $operation = $gw->createOPERATION(); // here you setup your request through public methods // that expose you blocks of information, that you can fill for the // operation of your choice. // build() will prepare `Request` object that `$gw` will use // for the request. $operationRequest = $operation->build(); // process() will perform provided request to the gateway // `$response` will have response data (headers, body). $response = $gw->process($operationRequest);
Card verification
<?php use TarlanPayments\Gateway\DataSets\Command; // create a payment to init card verification process $message->command()->setCardVerificationMode(Command::CARD_VERIFICATION_MODE_INIT); // complete card verification $operation = $gw->createCardVerification(); $operation->data()->setGatewayTransactionID($initialResponseGatewayTransactionId); $operationRequest = $operation->build(); $response = $gw->process($request); // send a payment with flag to accept only verified cards $message->command()->setCardVerificationMode(Command::CARD_VERIFICATION_MODE_VERIFY);
Payment data tokenization
<?php use TarlanPayments\Gateway\DataSets\Command; // option 1: create a payment with flag to save payment data $message->command()->setPaymentMethodDataSource(Command::DATA_SOURCE_SAVE_TO_GATEWAY); // option 2: send "create token" request with payment data $operation = $gw->createToken(); $operation->paymentMethod() ->setPAN('<card number>') ->setExpire('<card expiry>') ->setCardHolderName('<cardholder name>'); $operation->money() ->setCurrency('<desired currency>'); $operationRequest = $operation->build(); $response = $gw->process($request); // send a payment in "token usage" mode with flag to load payment data by token $message->useToken(); $message->command() ->setPaymentMethodDataSource(Command::DATA_SOURCE_USE_GATEWAY_SAVED_CARDHOLDER_INITIATED) ->setPaymentMethodDataToken('<initial gateway-transaction-id>');
Customization
If you need to access different API URL you can set through Gateway
constructor as follows:
<?php use TarlanPayments\Gateway\Gateway; $gw = new Gateway('https://customurl.com');
Also, you can customize client for your needs. By default Http\Client\Client
class is used. It use cURL under the hood. It implements HttpClientInterface
. You can create your own (or configure default) and set it to the gateway.
<?php use TarlanPayments\Gateway\Gateway; $httpClient = new MyClient(); // implements HttpClientInterface $gw = new Gateway(); $gw->setHttpClient($httpClient); // use it! // ...
Exceptions
Main exception, that can be thrown by the library is the GatewayException
. Following exceptions are children of GatewayException
:
RequestException
- will be thrown if request fail.ValidatorException
- will be thrown if some data for the request is missing.
About
Requirements
- This library works with PHP 7.0 or above.
Submit bugs and feature requests
Bugs and feature request are tracked on GitHub
License
This library is licensed under the MIT License - see the LICENSE
file for details.