Client for Espago API
Unofficial client of the Espago API written in PHP7.
To install via Composer just type in your console:
composer require "9orky/espago-api-php"
and you're done!
To avoid one huge file with all API methods, client was split into smaller functional pieces. The facade APIs are behind is at: Gorky\Espago\Factory\ApiFactory
All you need to do is to instantiate an API Factory with:
- apiUrl - this is quite obvious, for development purposes your URL is: https://sandbox.espago.com
- apiCredentials - this is an object which resides at Gorky\Espago\Model\ApiCredentials and requires three arguments which should be provided to you by Espago: public key, app ID and password.
How does this look in a code?
$apiFactory = new \Gorky\Espago\Factory\ApiFactory( 'https://sandbox.espago.com', new \Gorky\Espago\Model\ApiCredentials('app_id', 'public_key', 'password') );
Ok, now with our Api Factory handy we can proceed to make our first transaction. What we needed is to ask a Customer for his card details and charge him.
First step to our simple transaction is to generate a special Token which will be a Card's representation in Espago.
$tokensApi = $apiFactory->buildTokensApi(); // first we need Customer card's representation $unauthorizedCard = $tokensApi->createUnauthorizedCard( '4111111111111111', 'John', 'Doe', '04', '2020', '111' ); // so now we can transform it to a Token $token = $tokensApi->createToken($unauthorizedCard);
Token's model is a Response object so, together with others, it resides at: Gorky\Espago\Model directory. Explore the area to be familiar with what system can handle.
We have a Token so now it's time to charge a Customer. To do this we have to call Charges API and provide some payment details.
$chargesApi = $apiFactory->buildChargesApi(); // carefuly study Gorky\Espago\Model\Response\Charge and corresponding API documents! $charge = $chargesApi->createChargeByToken($token, 12.66, 'PLN', 'doughnuts');
Yes, it was actually that easy :-)
At this moment payment transaction is executed and Customer is charged. But wait, he just forgot to buy his wife some flowers for their anniversary. Oh no, he must type all these numbers and letters once again! But no worries though, we can actually save Customer's Card in Espago for us to use it when needed.
To match Card with a Customer we need to create a Client. We have do this with a little help of our friend Token.
$tokensApi = $apiFactory->buildTokensApi(); $unauthorizedCard = $tokensApi->createUnauthorizedCard( '4111111111111111', 'John', 'Doe', '04', '2020', '111' ); $token = $tokensApi->createToken($unauthorizedCard); $clientsApi = $apiFactory->buildClientsApi(); $client = $clientsApi->createClient($token, 'email@example.com', 'Our precious client John'); $chargesApi = $apiFactory->buildChargesApi(); $charge = $chargesApi->createChargeByClient($client, 12.66, 'PLN', 'doughnuts');
All you have to do now is to persist a Client's ID and from now on you can charge Customer on demand. It's very convenient when your Customers are returning ones.
There is a simple Console Application to play with using your sandbox account! :-) To make it usable we have to make some preparations.
In a main directory create PHP file called: credentials.php:
// credentials.php return [ 'app_id' => 'your_app_id', 'public_key' => 'your_public_key', 'password' => 'your_password' ];
Create new Client:
php espago.php customer:create
php espago.php customer:charge --interactive
php espago.php customer:charge --clientId="1234" --amount="6.67" --currency="PLN" --description="flowers"
Capture Authorization hold:
php espago.php customer:charge --capture --chargeId="pay_COy6zH9fLj1d7K" --amount="23.44"
php espago.php customer:charge --refund --chargeId="pay_COy6zH9fLj1d7K" --amount="23.44"
php espago.php customer:charge --cancel --chargeId="pay_COy6zH9fLj1d7K"
Note: Remember that you can always use --interactive switch which is more convenient:
php espago.php customer:charge --cancel --interactive
API documentation is right here: https://developers.espago.com/en/v3#201-preliminary-assumptions