afterpay-global / afterpay-sdk-php
Official Afterpay SDK for PHP
Installs: 99 817
Dependents: 1
Suggesters: 0
Security: 0
Stars: 6
Watchers: 6
Forks: 4
Open Issues: 2
Requires (Dev)
- phpunit/phpunit: ^5.0 || ^6.0 || ^7.0 || ^8.0 || ^9.0
- squizlabs/php_codesniffer: ^3.5
README
Official Afterpay SDK for PHP
Prerequisites
Minimum requirements:
- PHP 5.6+
Optional recommendations:
- MySQL 5.6+
- PHPUnit 5+
Installation
Install with Composer.
For Production
For production usage, ensure the dist
install method is used. This will exclude development resources
such as tests and sample code.
composer require --prefer-dist afterpay-global/afterpay-sdk-php
For Development
For development purposes, install from source using the --prefer-source
option. This will include
development resources such as tests and sample code.
composer require --prefer-source afterpay-global/afterpay-sdk-php
Note: If you need to switch between source
and dist
installations, you will need to first remove the
package using the following command, then reinstall using one of the require
commands above.
composer remove afterpay-global/afterpay-sdk-php
Configuration
Environment variables are expected to be defined in a PHP file,
located at ./vendor/afterpay-global/afterpay-sdk-php/.env.php
.
A sample file is provided at ./vendor/afterpay-global/afterpay-sdk-php/sample.env.php
- use this
file as a template to create your own environment configuration file.
It is possible to configure the SDK without this expected file, by manually setting the configuration
options on each of the appropriate classes before using them in your application. As a last resort,
the SDK will attempt to load its environment variables from the system with
getenv
.
Testing
Test with PHPUnit. Ensure you have the appropriate version of PHPUnit installed based on your PHP version.
Each release is verified in the following test environments:
However, it is always recommended to also test all software in your own unique environment prior to deploying to production.
Unit Tests
These tests do not require any networking or persistent storage.
phpunit --colors=always ./vendor/afterpay-global/afterpay-sdk-php/test/unit
Service Tests
These tests assume you have configured a persistent storage provider in your .env.php
configuration file.
For example, if you provide credentials for a MySQL database, the SDK will verify that it can connect to
the database with write access.
phpunit --colors=always ./vendor/afterpay-global/afterpay-sdk-php/test/service
Network Tests
These tests will verify that the SDK can communicate with the necessary external services using PHP's native cURL libraries.
phpunit --colors=always ./vendor/afterpay-global/afterpay-sdk-php/test/network
Integration Tests
These tests assume you have configured valid Merchant credentials for the Afterpay/Clearpay Online API
in your .env.php
configuration file. If so, the SDK will verify that it can send requests to the API,
and that the API responds as expected.
phpunit --colors=always ./vendor/afterpay-global/afterpay-sdk-php/test/integration
Usage
Constructing Data Models
All the model classes are available in src/Model. These classes are intended to reflect the data models described in the official online documentation for both Afterpay and Clearpay. By using these model classes to construct HTTP Requests, validity of request format can be verified at runtime.
Sample code is provided in the sample directory:
- Using method calls
- Using associative arrays
- Using ordered arguments
- Using JSON strings
- Combination of the above
Making HTTP Requests
Most API endpoints require authentication (with the exception of Ping). You can define your API credentials for your Afterpay/Clearpay merchant account using several different methods. You will also need to specify the ISO 3166-1 alpha-2 two-character country code of the merchant account. The following methods of specifying these details are supported:
- Inside your
.env.php
file, as themerchantId
,secretKey
andcountryCode
properties of the$afterpay_sdk_env_config
array. - As the
MERCHANT_ID
,SECRET_KEY
andCOUNTRY_CODE
environment variables. - By manually defining an object of class
\Afterpay\SDK\MerchantAccount
, passing your account details using itssetMerchantId
,setSecretKey
andsetCountryCode
methods, then passing this object to the the HTTP Request object using itssetMerchantAccount
method.
Sample code is provided in the sample directory:
- Making a "Ping" request
- Making a "Get Configuration" request, and persisting the result
- Validating and creating a checkout
- Immediately capturing payment for a confirmed checkout
- Creating a payment auth for a confirmed checkout
- Capturing payment for a despatched shipment
- Voiding an unfulfillable portion of a payment auth
- Creating a refund
Troubleshooting
How To Retrieve Raw HTTP Logs
All Request and Response objects provide a getRawLog
method for returning a raw HTTP log. This is often the most useful
data to facilitate an investigation, should a scenario be encountered where the Afterpay API does not behave
as expected.
Note: By default, any potentially sensitive information is obfuscated for privacy reasons. It is strongly recommended that this feature is not disabled, unless extraordinary precautions are taken to ensure the raw HTTP logs are not stored for any extended period of time, and destroyed immediately after their intended purpose has been fulfilled.
For example:
require __DIR__ . '/vendor/autoload.php'; use Afterpay\SDK\HTTP\Request\CreateCheckout as AfterpayCreateCheckoutRequest; $createCheckoutRequest = new AfterpayCreateCheckoutRequest([ 'amount' => [ '10.00', 'AUD' ], 'consumer' => [ 'phoneNumber' => '0400 000 000', 'givenNames' => 'Test', 'surname' => 'Test', 'email' => 'test@example.com' ], 'billing' => [ 'name' => 'Joe Consumer', 'line1' => 'Level 5', 'line2' => '406 Collins Street', 'area1' => 'Melbourne', 'region' => 'VIC', 'postcode' => '3000', 'countryCode' => 'AU', 'phoneNumber' => '0400 000 000' ], 'shipping' => [ 'name' => 'Joe Consumer', 'line1' => 'Level 5', 'line2' => '406 Collins Street', 'area1' => 'Melbourne', 'region' => 'VIC', 'postcode' => '3000', 'countryCode' => 'AU', 'phoneNumber' => '0400 000 000' ], 'courier' => [ 'shippedAt' => '2019-01-01T00:00:00+10:00', 'name' => 'Australia Post', 'tracking' => 'AA0000000000000', 'priority' => 'STANDARD' ], 'items' => [ [ 'name' => 'T-Shirt - Blue - Size M', 'sku' => 'TSH0001B1MED', 'quantity' => 10, 'pageUrl' => 'https://www.example.com/page.html', 'imageUrl' => 'https://www.example.com/image.jpg', 'price' => [ '10.00', 'AUD' ], 'categories' => [ [ 'Clothing', 'T-Shirts', 'Under $25' ], [ 'Sale', 'Clothing' ] ] ] ], 'discounts' => [ [ 'displayName' => '20% off SALE', 'amount' => [ '24.00', 'AUD' ] ] ], 'merchant' => [ 'redirectConfirmUrl' => 'http://localhost', 'redirectCancelUrl' => 'http://localhost' ], 'taxAmount' => [ '0.00', 'AUD' ], 'shippingAmount' => [ '0.00', 'AUD' ] ]); $createCheckoutRequest->send(); echo $createCheckoutRequest->getRawLog();
########## BEGIN RAW HTTP REQUEST ##########
POST /v2/checkouts HTTP/2
Host: global-api-sandbox.afterpay.com
Authorization: Basic MzM******************************************************************************************************************************************************************************TA=
User-Agent: afterpay-sdk-php/1.4.1 (PHP/8.1.1; cURL/7.77.0; Merchant/*****)
Accept: */*
Content-Type: application/json
Content-Length: 1223
{"amount":{"amount":"10.00","currency":"AUD"},"consumer":{"phoneNumber":"**** *** ***","givenNames":"****","surname":"****","email":"****************"},"billing":{"name":"*** ********","line1":"***** *","line2":"*** ******* ******","area1":"*********","region":"***","postcode":"****","countryCode":"AU","phoneNumber":"**** *** ***"},"shipping":{"name":"*** ********","line1":"***** *","line2":"*** ******* ******","area1":"*********","region":"***","postcode":"****","countryCode":"AU","phoneNumber":"**** *** ***"},"courier":{"shippedAt":"2019-01-01T00:00:00+10:00","name":"********* ****","tracking":"AA0000000000000","priority":"STANDARD"},"items":[{"name":"******* * **** * **** *","sku":"TSH0001B1MED","quantity":10,"pageUrl":"https:\/\/www.example.com\/page.html","imageUrl":"https:\/\/www.example.com\/image.jpg","price":{"amount":"10.00","currency":"AUD"},"categories":[["Clothing","T-Shirts","Under $25"],["Sale","Clothing"]]}],"discounts":[{"displayName":"20% off SALE","amount":{"amount":"24.00","currency":"AUD"}}],"merchant":{"redirectConfirmUrl":"http:\/\/localhost","redirectCancelUrl":"http:\/\/localhost"},"taxAmount":{"amount":"0.00","currency":"AUD"},"shippingAmount":{"amount":"0.00","currency":"AUD"}}
########## END RAW HTTP REQUEST ##########
########## BEGIN RAW HTTP RESPONSE ##########
HTTP/2 201
date: Tue, 15 Sep 2020 14:20:49 GMT
content-type: application/json
content-length: 249
set-cookie: __cfduid=d05b6824b1ed88439e0b8edfe4905c7671600179649; expires=Thu, 15-Oct-20 14:20:49 GMT; path=/; domain=.afterpay.com; HttpOnly; SameSite=Lax; Secure
http_correlation_id: ed5d72kgz3ezlylm7g3qxiej6a
cf-cache-status: DYNAMIC
cf-request-id: 0533bcd2b60000fd36ac918200000001
expect-ct: max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
strict-transport-security: max-age=31536000; includeSubDomains; preload
server: cloudflare
cf-ray: 5d32fd97883dfd36-SYD
{
"token" : "001.ug27ke8qbpljfsssn4t98c60eq61767rva1e3f3g7g4nup7c",
"expires" : "2020-09-15T17:20:49.267Z",
"redirectCheckoutUrl" : "https://portal.sandbox.afterpay.com/au/checkout/?token=001.ug27ke8qbpljfsssn4t98c60eq61767rva1e3f3g7g4nup7c"
}
########## END RAW HTTP RESPONSE ##########
Contributing
See CONTRIBUTING.md.