Implementing required interfaces

Before using the Raylo Pay module, you'll need to implement a few interfaces that will be used to pass information to the SDK.

IConfigProvider

This interface is used by the SDK to get basic configuration information about the merchant for the integration. You'll get the values for merchantId and jwtSigningKey from Raylo when discussing the integration.

Stub implementation with comments:

use \Raylo\RayloPay\SDK\IConfigProvider;
use \Raylo\RayloPay\SDK\RayloPayEnvironment;

class ConfigProvider implements IConfigProvider {
    private bool $isProduction;

    private function __construct(bool $isProduction) {
        $this->isProduction = $isProduction;
    }
    
    function merchantId() : string {
        return '<constant, provided by Raylo>';
    }

    function jwtSigningKey() : string {
        // treat this as a secret, i.e. fetch it from a secrets store, env var, etc.
        return '<provided by Raylo>';
    }
    
    function rayloPayEnvironment() : RayloPayEnvironment {
        // determines whether the SDK will connect to Raylo Pay prod or sandbox envs.
        return $this->isProduction
            ? RayloPayEnvironment::production()
            : RayloPayEnvironment::sandbox();
    }

    function raylopayServerBaseUrl() : string {
        return ''; // not needed for RayloPay production or sandbox
    }

    function raylopayWidgetsBaseUrl() : string {
        return ''; // not needed for RayloPay production or sandbox
    }
}

IMerchantUrlProvider

This interface is used by the SDK to get which URLs should be used in different situations.

In all cases, but particularly importantly in the server-to-server URL, the merchantReference should be encoded in a format which is not be guessable and ideally should be verifiably a value that only your system could have produced. An option for that would be encoding it using a JWT.

success: Checkout completed and approved by Raylo Pay

When a customer completes a checkout and their lease is approved while their browser is still in the final page of the Raylo Pay checkout, their browser will be redirected to this URL.

failure: Checkout completed and declined by Raylo Pay

When a customer completes a checkout and is declined while their browser is still in the final page of the Raylo Pay checkout, their browser will be redirected to this URL.

notify: Server-to-server communication

Independently of the customer still being in the checkout page or not when a decision is determined by the Raylo Pay service, a server-to-server POST request is made from Raylo Pay's server to this URL to report the checkout decision.

The payload of that request follows the format documented here; But you don't need to implement the decoding or even read it in detail, the SDK has an API to validate and decode it: \Raylo\RayloPay\SDK\Checkout::getCheckoutOutcome($requestBody).

Stub implementation with comments:

// data object
use \Raylo\RayloPay\SDK\IStdClassConvertible;
use \Raylo\RayloPay\SDK\StdClassConversionTrait;

class MerchantCallbackInfo implements IStdClassConvertible {
    use StdClassConversionTrait;

    public string $merchantReference;
}

// interface implementation
use \Raylo\RayloPay\SDK\IMerchantUrlProvider;
use \Raylo\RayloPay\SDK\JWT\IJwtEncoder;
use \Raylo\RayloPay\SDK\JWT\JwtEncoder;

class MerchantUrlProvider implements IMerchantUrlProvider {
    private IJwtEncoder $jwtEncoder;

    public function __construct(ConfigProvider $config) {
        $this->jwtEncoder = new JwtEncoder($config->jwtSigningKey(), $config->merchantId(), 'Merchant');
    }

    function callbackUrl(string $type, string $merchantReference) : string {
        $args = new MerchantCallbackInfo;
        $args->merchantReference = $merchantReference;
        $jwt = $this->jwtEncoder->sign($args);
        return $type === 'notify'
            ? "https://example.com/decision-callback/$type?jwt=$jwt"
            : "https://example.com/checkout-callback/$type?jwt=$jwt"
    }
}

Handling notification call from Raylo Pay

Given the above stub implementation, on the handlers of the mentioned URLs the merchantReference can be read from the ?jwt=... query string argument, and the payload can be decoded as follows:

// header...
use \Raylo\RayloPay\SDK\JWT\IJwtEncoder;
use \Raylo\RayloPay\SDK\JWT\JwtEncoder;
use \Raylo\RayloPay\SDK\Checkout as CheckoutHelper;
use \Raylo\RayloPay\SDK\JwtDecodeException;

// initialisation/constructor...
$config = new ConfigProvider(...);
$checkoutHelper = new CheckoutHelper(...)
$jwtEncoder = new JwtEncoder($config->jwtSigningKey(), $config->merchantId(), 'Merchant');

// function/method body...
try {
    // get order ID / merchant reference from the jwt parameter
    $args = new MerchantCallbackInfo;
    $this->jwtEncoder->decode($jwtQueryStringArgument, $args);
    $orderId = $args->merchantReference;
    
    // decode response body to record whether the checkout was successful or not
    $bodyJson = json_decode($requestBodyRaw, true);
    $payloadJwt = $bodyJson['payload'] ?? '';
    $outcome = $checkoutHelper->getCheckoutOutcome($payloadJwt);
    if ($outcome->outcome == 'success') {
        // process successful order
        // $outcome is of type \Raylo\RayloPay\SDK\CheckoutOutcome
        // and contains the customer details which the customer used
        // to complete the checkout with Raylo Pay
        // (may be different from those initially submitted)
    } else if ($outcome->outcome == 'failure') {
        // cancel order
    } else {
        // unsupported value, log/throw
    }
} catch (JwtDecodeException $ex) {
    ...
}