README

Official PHP SDK for the Wonderful One API. Accept Open Banking payments, manage customers, orders, and generate reusable payment links — directly from your PHP or Laravel application.

Requirements

• PHP 8.0 or higher
• Guzzle ^7.0 (installed automatically)
• A Wonderful One merchant account and API token

Installation

composer require wonderfulpaymentsltd/one-api-sdk-php

Configuration

Standalone

use Wonderful\OneApi\OneApiClient;

$client = OneApiClient::make('your-api-key');

Laravel

The Service Provider and Facade are registered automatically via Package Discovery.

1. Add your API key to .env:

ONE_API_KEY=your-api-key

1. (Optional) Publish the config file:

php artisan vendor:publish --tag=one-api-config

1. Use the Facade:

use OneApi;

OneApi::customers()->list();

Or inject via constructor:

use Wonderful\OneApi\OneApiClient;

class PaymentController
{
    public function __construct(protected OneApiClient $oneApi) {}

    public function index()
    {
        return $this->oneApi->payments()->list();
    }
}

Usage

Quick Pay

Create a customer, order, order line, and payment in a single request.

$payment = $client->quickPay()
    ->amount(1000)                           // £10.00 in GB pence
    ->reference('ORDER-1234')                // Shown on bank statement (max 18 chars, A-Z, 0-9, -)
    ->description('Website Order #1234')      // Order description
    ->customerEmail('john@example.com')       // Links order to customer
    ->redirectUrl('https://mysite.com/success')
    ->webhookUrl('https://mysite.com/webhooks')
    ->create();

echo $payment->pay_link; // Send customer to this URL to pay

Minimum required fields:

$payment = $client->quickPay()
    ->amount(500)
    ->reference('ORDER-1')
    ->redirectUrl('https://mysite.com/success')
    ->create();

Advanced options:

$payment = $client->quickPay()
    ->amount(1000)
    ->reference('ORDER-1234')
    ->bankId('natwest')                     // Pre-select the customer's bank
    ->skipConfirmation(true)                // Skip the confirmation page
    ->sendToTap('a1b2c3d4')                 // Send to a Tap device
    ->create();

Reusable Payment Links (QR Codes)

Create a fixed-amount payment link that can be reused (e.g., for donations, subscriptions, or physical QR codes).

$qrCode = $client->qrCodes()->create([
    'amount' => 2000,
    'label' => 'Donation - General Fund',
    'customer_data_collection' => 'email_only',
]);

echo $qrCode->pay_link;   // Payment URL
echo $qrCode->image_link;  // QR code image URL

Customer data collection levels: none, email_only, contact_light, contact_full, billing

List, find, update, and delete QR codes:

$qrCodes = $client->qrCodes()->list();
$qrCode  = $client->qrCodes()->find('0e261265');
$client->qrCodes()->update('0e261265', ['amount' => 3000, 'label' => 'Updated']);
$client->qrCodes()->delete('0e261265');

Customers

// Create
$customer = $client->customers()->create([
    'first_name' => 'John',
    'last_name' => 'Smith',
    'email' => 'john@example.com',
    'telephone' => '01234 567890',
    'marketing_consent' => true,
    'address' => '123 Some Street, London, SW1A 1AA',
]);

// Find
$customer = $client->customers()->find('1d368e62');

// Update (pass all fields - the API replaces the entire record)
$client->customers()->update('1d368e62', [
    'first_name' => 'Jonathan',
    'last_name' => 'Smith',
    'email' => 'jonathan@example.com',
    'telephone' => '01234 567890',
]);

// Delete (soft-delete)
$client->customers()->delete('1d368e62');

// List with filters
$list = $client->customers()->list([
    'search' => 'John',
    'sort' => 'last_name_asc',
    'start_date' => '2024-01-01',
    'end_date' => '2024-12-31',
    'per_page' => 50,
]);

foreach ($list->data as $customer) {
    echo $customer->full_name . ' - ' . $customer->email . "\n";
}

Orders & Refunds

// List orders
$orders = $client->orders()->list([
    'payment_status' => 'paid',
    'sort' => 'created_desc',
    'per_page' => 25,
]);

// Find a specific order
$order = $client->orders()->find('ed6d3016');

// Access related data
echo $order->total_formatted;
echo $order->customer->email;
echo $order->payments[0]->pay_link;
echo $order->order_lines[0]->description;

// Create a refund (amount in GB pence)
$refund = $client->orders()->refund(
    id: 'ed6d3016',
    amount: 500,
    reference: 'REF-001',          // Optional, max 18 chars
    reason: 'Item returned, too big.' // Optional, internal note
);

echo "Refunded: {$refund->refund_amount_formatted} ({$refund->status})";

Payments

// List payments
$payments = $client->payments()->list([
    'sort' => 'created_desc',
    'per_page' => 10,
]);

// Find a specific payment
$payment = $client->payments()->find('e2611865');

// Stop a payment (before it's authorised at the bank)
$payment = $client->payments()->stop('e2611865');

// Delete a payment (only if status is 'created')
$client->payments()->delete('e2611865');

Tap Devices

// List all tap devices
$devices = $client->tapDevices()->list();

// Filter by action type
$tapDevices = $client->tapDevices()->list(['tap_payments']);
$reusableLinkDevices = $client->tapDevices()->list(['reusable_payment']);
$merchantLinkDevices = $client->tapDevices()->list(['merchant_link']);

Supported Banks

$banks = $client->banks()->list();

foreach ($banks->data as $bank) {
    echo "{$bank->bank_name} ({$bank->bank_id}) - {$bank->status}\n";
}

Error Handling

The SDK throws typed exceptions for common HTTP errors:

use Wonderful\OneApi\Exceptions\AuthenticationException;
use Wonderful\OneApi\Exceptions\ValidationException;
use Wonderful\OneApi\Exceptions\NotFoundException;
use Wonderful\OneApi\Exceptions\OneApiException;

try {
    $payment = $client->quickPay()
        ->amount(1000)
        ->reference('ORDER-1234')
        ->redirectUrl('https://mysite.com/success')
        ->create();
} catch (AuthenticationException $e) {
    // 401 - Invalid or missing API key
    echo $e->getMessage();
} catch (ValidationException $e) {
    // 422 - Validation failed (check invalid fields)
    print_r($e->getInvalidFields());
} catch (NotFoundException $e) {
    // 404 - Resource not found
} catch (OneApiException $e) {
    // Other API errors (4xx, 5xx)
    echo "{$e->getMessage()} (code: {$e->getCode()})";
}

Running Tests

composer install
vendor/bin/phpunit

Changelog

See CHANGELOG.md.

License

MIT © Wonderful Payments Ltd