GOV.UK Pay - pay-integration-php
PHP client for the GOV.UK Pay API, (*1)
As of September 2021, this repository is no longer actively maintained by the GOV.UK Pay team., (*2)
PSR-7 HTTP
The Pay PHP Client is based on a PSR-7 HTTP model. You therefore need to pick your preferred HTTP Client library to use., (*3)
We will show examples here using the Guzzle v6 Adapter., (*4)
Installing
The Pay PHP Client can be installed with Composer. Run this command:, (*5)
composer require php-http/guzzle6-adapter alphagov/pay-integration-php
Usage
Assuming you've installed the package via Composer, the Pay PHP Client will be available via the autoloader., (*6)
Create a (Guzzle v6 based) instance of the Client using:, (*7)
$client = new \Alphagov\Pay\Client([
'apiKey' => '{your api key}',
'httpClient' => new \Http\Adapter\Guzzle6\Client
]);
You are then able to access the Pay API using $client., (*8)
If you need to access an environment other than production, you can pass the base URL in via the baseUrl key in the constructor:, (*9)
'baseUrl' => '{api base url}'
Create a Payment
The method signature is:, (*10)
createPayment( $amount, $reference, $description, UriInterface $returnUrl )
Where, (*11)
-
$amount A required int holding the payment amount, in pence, in British Pounds (GBP).
-
$reference A required string holding an application side payment reference.
-
$description A required string a description of the payment.
-
$returnUrl A required Psr\Http\Message\UriInterface with the URL the user will be directed back to.
An example request would look like:, (*12)
try {
$response = $client->createPayment(
10 * 100, // £10
'id-123',
'Payment for x, y and z.',
new \GuzzleHttp\Psr7\Uri('https://www.example.service.gov.uk/pay/response')
);
} catch (PayException $e){}
$response will be an instance of Alphagov\Pay\Response\Payment, which is documented here., (*13)
An instance (or sub-class) of Alphagov\Pay\Exception\PayException will be thrown if a Pay error occurs., (*14)
Lookup a Payment
The method signature is:, (*15)
getPayment( $payment )
Where, (*16)
-
$payment is a required string holding the (Pay generated) payment id.
An example request would look like:, (*17)
try {
$response = $client->getPayment( 'hu20sqlact5260q2nanm0q8u93' );
} catch (PayException $e){}
$response will be an instance of Alphagov\Pay\Response\Payment, which is documented here; or null if the payment was not found., (*18)
An instance (or sub-class) of Alphagov\Pay\Exception\PayException will be thrown if a Pay error occurs., (*19)
Cancel a Payment
The method signature is:, (*20)
cancelPayment( $payment )
-
$payment is a required string holding the (Pay generated) payment id.
An example request would look like:, (*21)
try {
$response = $client->cancelPayment( 'hu20sqlact5260q2nanm0q8u93' );
} catch (PayException $e){}
$response will be bool true if the payment was cancelled. Otherwise an instance (or sub-class) of Alphagov\Pay\Exception\PayException will be thrown if a Pay error occurs., (*22)
Refund a Payment
The method signature is:, (*23)
refundPayment( $payment, $amount, $refundAmountAvailable = null )
-
$payment is a required string holding the (Pay generated) payment id.
-
$amount A required int holding the amount to be refunded, in pence, in British Pounds (GBP).
-
$refundAmountAvailable An optional int holding the expected amount available for refund, in pence, in British Pounds (GBP).
An example request would look like:, (*24)
try {
$response = $client->refundPayment(
'hu20sqlact5260q2nanm0q8u93',
10 * 100, // £10
50 * 100 // £50
);
} catch (PayException $e){}
$response will be an instance of Alphagov\Pay\Response\Refund, which is documented here., (*25)
An instance (or sub-class) of Alphagov\Pay\Exception\PayException will be thrown if a Pay error occurs., (*26)
Lookup all Refunds for a Payment
The method signature is:, (*27)
getPaymentRefunds( $payment )
Where, (*28)
-
$payment is a required string holding the (Pay generated) payment id.
An example request would look like:, (*29)
try {
$response = $client->getPaymentRefunds( 'hu20sqlact5260q2nanm0q8u93' );
} catch (PayException $e){}
$response will be an instance of Alphagov\Pay\Response\Refunds, which will contain an instance of Alphagov\Pay\Response\Refund (docs) for each refund processed., (*30)
An instance (or sub-class) of Alphagov\Pay\Exception\PayException will be thrown if a Pay error occurs., (*31)
Lookup a single Refund for a Payment
The method signature is:, (*32)
getPaymentRefund( $payment, $refund )
Where, (*33)
-
$payment is a required string holding the (Pay generated) payment id.
-
$refund is a required string holding the (Pay generated) refund id.
An example request would look like:, (*34)
try {
$response = $client->getPaymentRefunds(
'hu20sqlact5260q2nanm0q8u93',
'j2cg5v7et0424d7shtrt7r0mj'
);
} catch (PayException $e){}
$response will be an instance of Alphagov\Pay\Response\Refund (docs), or NULL if the refund is not found., (*35)
An instance (or sub-class) of Alphagov\Pay\Exception\PayException will be thrown if a Pay error occurs., (*36)
Lookup all Events for a Payment
The method signature is:, (*37)
getPaymentEvents( $payment )
Where, (*38)
-
$payment is a required string holding the (Pay generated) payment id.
An example request would look like:, (*39)
try {
$response = $client->getPaymentEvents( 'hu20sqlact5260q2nanm0q8u93' );
} catch (PayException $e){}
$response will be an instance of Alphagov\Pay\Response\Events, which will contain an instance of Alphagov\Pay\Response\Event (docs) for each event., (*40)
An instance (or sub-class) of Alphagov\Pay\Exception\PayException will be thrown if a Pay error occurs., (*41)
Search Payments
The method signature is:, (*42)
searchPayments( array $filters = array() )
Where, (*43)
-
$filters An optional array which applies filters to the request. Zero or more filters can be used. Supported filtered:
-
reference string
-
state string
-
page string
-
display_size string
-
from_date DateTime
-
to_date DateTime
Full filter details can be found here: https://gds-payments.gelato.io/docs/versions/1.0.0/resources/general/endpoints/search-payments, (*44)
An example request would look like:, (*45)
try {
$response = $client->searchPayments([
'from_date' => new \DateTime('2015-08-14T12:35:00Z'),
'page' => '2',
'display_size' => '50'
]);
} catch (NotifyException $e){}
$response will be an instance of Alphagov\Pay\Response\Payments, which will contain an instance of Alphagov\Pay\Response\Payment (docs) for each payment found., (*46)
An instance (or sub-class) of Alphagov\Pay\Exception\PayException will be thrown if a Pay error occurs., (*47)
Responses
All Response objects except Event have a getResponse() which returns a class implementing Psr\Http\Message\ResponseInterface, containing the original API response., (*48)
Payment
An instance of Alphagov\Pay\Response\Payment, which contains the decoded JSON response from the Pay API, representing a single payment., (*49)
A full list of returned properties can be found here: https://gds-payments.gelato.io/docs/versions/1.0.0/resources/payment-id/endpoints/find-payment-by-id, (*50)
Properties can be accessed directly using the -> operator. For example:, (*51)
$response->payment_id
$response->created_date
// etc...
If available, the payment page URL to direct the user to is accessible via:, (*52)
$response->getPaymentPageUrl();
This returns either:
* an instance of Psr\Http\Message\UriInterface represening the URL; or
* null if the URL is unavailable (for example, if the payment is complete)., (*53)
Payment also includes methods for checking the state of the payment:, (*54)
The payment is finished. i.e. the user can no longer interact with the payment page., (*55)
$response->isFinished()
The payment is successful., (*56)
$response->isSuccess()
All other standard Pay states can also be checked via:, (*57)
$response->isCreated()
$response->isStarted()
$response->isSubmitted()
$response->isFailed()
$response->isCancelled()
$response->isError()
Refund
An instance of Alphagov\Pay\Response\Refund, which contains the decoded JSON response from the Pay API, representing a single refund., (*58)
A full list of returned properties can be found here: https://gds-payments.gelato.io/docs/versions/1.0.0/resources/payment-id/endpoints/find-payment-refund-by-id, (*59)
Properties can be accessed directly using the -> operator. For example:, (*60)
$response->refund_id
$response->status
$response->amount
// etc...
Event
An instance of Alphagov\Pay\Response\Event, which contains the decoded JSON response from the Pay API, representing a single event., (*61)
A full list of returned properties can be found here: https://gds-payments.gelato.io/docs/versions/1.0.0/resources/payment-id/endpoints/return-payment-events-by-id, (*62)
Properties can be accessed directly using the -> operator. For example:, (*63)
$response->state
$response->updated
// etc...
Payments, Refunds & Events
All three of these responses represent collections of their respective response type. They all extend PHP’s ArrayObject, thus can be treated as an array., (*64)
Both Refunds & Events also support the addition $response->payment_id property, containing the payment ID to which they relate., (*65)
License
The Pay PHP Client is released under the MIT license, a copy of which can be found in LICENSE., (*66)
Wallogit.com
