README

The Payum extension to purchase through Square using Elements

Install and Use

To install, it's easiest to use composer:

composer require cognito/payum_square

Build the config

<?php

use Payum\Core\PayumBuilder;
use Payum\Core\GatewayFactoryInterface;

$defaultConfig = [];

$payum = (new PayumBuilder)
    ->addGatewayFactory('square', function(array $config, GatewayFactoryInterface $coreGatewayFactory) {
        return new \Cognito\PayumSquare\SquareGatewayFactory($config, $coreGatewayFactory);
    })

    ->addGateway('square', [
        'factory' => 'square',
        'access_token' => 'Your-access-token',
        'app_id' => 'Your-app-id',
        'location_id' => 'Your-location-id',
        'sandbox' => false,
        'img_url' => 'https://path/to/logo/image.jpg',
    ])

    ->addGateway('square_afterpay', [
        'factory' => 'square_afterpay',
        'access_token' => 'Your-access-token',
        'app_id' => 'Your-app-id',
        'location_id' => 'Your-location-id',
        'sandbox' => false,
        'img_url' => 'https://path/to/logo/image.jpg',
    ])

    ->getPayum()
;

Request card payment

<?php

use Payum\Core\Request\Capture;

$storage = $payum->getStorage(\Payum\Core\Model\Payment::class);
$request = [
    'invoice_id' => 100,
];

$payment = $storage->create();
$payment->setNumber(uniqid());
$payment->setCurrencyCode($currency);
$payment->setTotalAmount(100); // Total cents
$payment->setDescription(substr($description, 0, 45));
$storage->setInternalDetails($payment, $request);
$payment->setDetails([
    'square_item_name' => 'Payment name', // Optional, sets the line item to this product
    'square_line_items' => [ // Optional, sets the line items, and creates catalogue items
        [
            'name' => 'Product Name',
            'qty' => 2,
            'amount' => 50,
            'note' => 'Optional Note',
        ],
        // ...
    ],
    'square_discount' => 0, // Optional, sets the whole order discount where the total of the line items does not match the total amount above
    'square_customer' => [ // Optional, sets this order to this customer
        'email' => 'xx@xx.com', // Required
        'given_name' => 'Customer First Name', // Optional
        'family_name' => 'Customer Last Name', // Optional
        'id' => 'My internal id', // Optional
    ],
]);

$captureToken = $payum->getTokenFactory()->createCaptureToken('square', $payment, 'done.php');
$url = $captureToken->getTargetUrl();
header("Location: " . $url);
die();

Request Afterpay payment

Afterpay requires more information about the customer to process the payment

<?php

use Payum\Core\Request\Capture;

$storage = $payum->getStorage(\Payum\Core\Model\Payment::class);
$request = [
    'invoice_id' => 100,
];

$payment = $storage->create();
$payment->setNumber(uniqid());
$payment->setCurrencyCode($currency);
$payment->setTotalAmount(100); // Total cents
$payment->setDescription(substr($description, 0, 45));
$payment->setDetails([
    'ship_item' => false,
    'pickup_contact' => [ // Optional if shipping the item
        'addressLines' => [
            'Address Line 1',
            'Address Line 2', // Optional
        ],
        'city' => 'Address City',
        'state' => 'Address State',
        'postalCode' => 'Address Postal Code',
        'countryCode' => 'AU',
        'givenName' => 'Business Name or contact person',
        'familyName' => '',
        'email' => 'pickup@email.address', // Optional
        'phone' => 'Pickup Phone', // Optional
    ],
    // merchant_reference is sent to the below api endpoints to assist in identifying the purchase
    'merchant_reference' => '12345',
    // Add api endpoint that gets the selected Afterpay address and returns shipping options
    'afterpay_addresschange_url' => 'https://mysite/afterPayAddress',
    // Add api endpoint that records which shipping option the user chooses
    'afterpay_shippingchange_url' => 'https://mysite/afterPayShipping',
    // Use below if dynamic shipping options not used with callback
    'afterpay_shipping_options' => [
        [
            'amount' => '0.00',
            'id' => 'shipping-option-1',
            'label' => 'Free Shipping',
            'taxLineItems' => [
                [
                    'amount' => '0.00',
                    'label' => 'Tax'
                ],
            ],
            'total' => [
                'amount' => '15.00', // Needs to be order total including shipping
                'label' => 'total',
            ],
        ],
        [
            'amount' => '10.00',
            'id' => 'shipping-option-2',
            'label' => 'Standard Shipping',
            'taxLineItems' => [
                [
                    'amount' => '0.91',
                    'label' => 'Tax'
                ],
            ],
            'total' => [
                'amount' => '25.00', // Needs to be order total including shipping
                'label' => 'total',
            ],
        ],
    ],
]);
$storage->setInternalDetails($payment, $request);

$captureToken = $payum->getTokenFactory()->createCaptureToken('square', $payment, 'done.php');
$url = $captureToken->getTargetUrl();
header("Location: " . $url);
die();

Check it worked

<?php
/** @var \Payum\Core\Model\Token $token */
$token = $payum->getHttpRequestVerifier()->verify($request);
$gateway = $payum->getGateway($token->getGatewayName());

/** @var \Payum\Core\Storage\IdentityInterface $identity **/
$identity = $token->getDetails();
$model = $payum->getStorage($identity->getClass())->find($identity);
$gateway->execute($status = new GetHumanStatus($model));

/** @var \Payum\Core\Request\GetHumanStatus $status */

// using shortcut
if ($status->isNew() || $status->isCaptured() || $status->isAuthorized()) {
    // success
} elseif ($status->isPending()) {
    // most likely success, but you have to wait for a push notification.
} elseif ($status->isFailed() || $status->isCanceled()) {
    // the payment has failed or user canceled it.
}

License

Payum Square is released under the MIT License.

cognito / payum_square

Maintainers

Details