README

Accepting Payconiq payments with the use of the QR code.
API documentation can be found here.

Requirements

To use the Payconiq API client, the following things are required:

• Payconiq Merchant Id and API key
• PHP >= 8.3
• PHP cURL extension

Installation

The best way to install the Payconiq API client is to require it with Composer.

$ composer require liedekef/payconiq-api-php

You may also git checkout or download all the files, and include the Payconiq API client manually.

Parameters

We use the following parameters in the examples below:

$apiKey = 'apiKey 123456'; // Used to secure request between merchant backend and Payconiq backend.
$merchantId = 'merchantid'; // payconiq merchantid (not really used, unless to verify more in notification callback)
$amount = 1000; // Transaction amount in cents
$currency = 'EUR'; // Currency
$reference = "my internal payment reference"; // an internal reference (e.g. a booking id)
      // the reference is given in the callback, allowing you to know what local payment is being handled
$callbackUrl = 'http://yoursite.com/postback'; // Callback where Payconiq needs to POST confirmation status
$returnUrl = 'http://yoursite.com/returnpage'; // Optional. the page a buyer is returned to after payment. You'll need to check
     // the payment status there

To learn more about how, when and what Payconiq will POST to your callbackUrl, please refer to the developer documentation right here.

Installation

// Include the Client.php file
require_once '/path/to/Payconiq/Client.php';

use Payconiq\Client;

Initialization

Basic Setup

// Production environment (default)
$client = new Client('your-api-key-here');

// Test environment
$client = new Client('your-test-api-key', Client::ENVIRONMENT_TEST);

// Or configure after instantiation
$client = new Client();
$client->setApiKey('your-api-key-here')
       ->setEndpointTest(); // Switch to test environment

Custom Endpoints

$client->setEndpoints(
    'https://custom.api.endpoint/v3',
    'https://custom.jwks.endpoint/'
);

Core Methods

1. Create a Payment

/**
 * @param float $amount Payment amount in cents (e.g., 1000 = €10.00)
 * @param string $currency Currency code (default: 'EUR')
 * @param string $description Payment description (optional, max 140 chars)
 * @param string $reference External reference (optional, max 35 chars)
 * @param string $bulkId Bulk ID for payouts (optional)
 * @param string $callbackUrl Webhook callback URL (optional)
 * @param string $returnUrl Return URL after payment (optional)
 * @return object Payment object with paymentId
 * @throws CreatePaymentFailedException
 */
$payment = $client->createPayment(
    1000,                   // €10.00
    'EUR',                  // Currency
    'Order #12345',         // Description
    'REF-12345',            // Your reference
    '',                     // Bulk ID
    'https://your-site.com/webhook',
    'https://your-site.com/return'
);

// Response contains:
// - $payment->paymentId
// - $payment->_links->checkout->href (payment URL for customer)

2. Retrieve Payment Details

/**
 * @param string $paymentId Payconiq payment ID
 * @return object Payment details
 * @throws RetrievePaymentFailedException
 */
$payment = $client->retrievePayment('PAYMENT_ID_HERE');

// Response contains:
// - $payment->paymentId
// - $payment->amount
// - $payment->currency
// - $payment->status (e.g., 'SUCCEEDED', 'PENDING')
// - $payment->_links->refund->href (if refundable)

3. Get Payment(s) by Reference

/**
 * @param string $reference Your external reference
 * @param string $fromDate Start date (format: YYYY-MM-ddTHH:mm:ss.SSSZ, default: yesterday)
 * @param string $toDate End date (format: YYYY-MM-ddTHH:mm:ss.SSSZ, default: now)
 * @return array List of successful payments with matching reference
 * @throws GetPaymentsListFailedException
 */
$payments = $client->getPaymentsListByReference('REF-12345');

// Returns array of payment objects

To immediately get the payment with the matching reference (since normally there's only one):

/**
 * @param string $reference Your external reference
 * @param string $fromDate Start date (format: YYYY-MM-ddTHH:mm:ss.SSSZ, default: yesterday)
 * @param string $toDate End date (format: YYYY-MM-ddTHH:mm:ss.SSSZ, default: now)
 * @return object Successful payment with matching reference
 * @throws GetPaymentsListFailedException
 */
$payments = $client->getPaymentByReference('REF-12345');

4. Get Payments by Date Range

/**
 * @param string $fromDate Start date (format: YYYY-MM-ddTHH:mm:ss.SSSZ, default: yesterday)
 * @param string $toDate End date (format: YYYY-MM-ddTHH:mm:ss.SSSZ, default: now)
 * @param int $size Page size (default: 50)
 * @return array List of successful payments in date range
 * @throws GetPaymentsListFailedException
 */
$payments = $client->getPaymentsListByDateRange(
    '2024-01-01T00:00:00.000Z',
    '2024-01-31T23:59:59.999Z',
    100
);

5. Refund a Payment

/**
 * @param string $paymentId Payconiq payment ID
 * @param float $amount Refund amount in cents
 * @param string $currency Currency (default: 'EUR')
 * @param string $description Refund description (optional)
 * @param string $idempotencyKey Optional idempotency key (UUIDv4)
 * @param string $refundUrl Optional custom refund URL
 * @return object Refund response
 * @throws RefundFailedException
 */
$refund = $client->refundPayment(
    'PAYMENT_ID_HERE',
    500,                    // Refund €5.00
    'EUR',
    'Partial refund for order #12345',
    null,                   // Auto-generated UUID if null
    null                    // Auto-detected from payment
);

6. Get Refund IBAN

/**
 * @param string $paymentId Payconiq payment ID
 * @return string IBAN for refunds
 * @throws GetRefundIbanFailedException
 */
$iban = $client->getRefundIban('PAYMENT_ID_HERE');

Webhook Signature Verification

1. Verify Webhook Signature

/**
 * @param string $payload Raw request body (php://input)
 * @param array $headers HTTP headers (getallheaders())
 * @return bool True if signature is valid
 * @throws \Exception on verification failure
 */
$isValid = $client->verifyWebhookSignature(
    file_get_contents('php://input'),
    getallheaders()
);

if ($isValid) {
    // Process webhook
    $data = json_decode(file_get_contents('php://input'), true);
    // Handle payment events
}

2. Webhook Handling Example

// Complete webhook handler example
try {
    $payload = file_get_contents('php://input');
    $headers = getallheaders();
    
    if ($client->verifyWebhookSignature($payload, $headers)) {
        $data = json_decode($payload, true);
        
        switch ($data['status']) {
            case 'SUCCEEDED':
                // Update order as paid
                break;
            case 'FAILED':
                // Handle failed payment
                break;
            case 'REFUNDED':
                // Handle refund
                break;
        }
        
        http_response_code(200);
        echo 'OK';
    } else {
        http_response_code(401);
        echo 'Invalid signature';
    }
} catch (\Exception $e) {
    error_log('Webhook error: ' . $e->getMessage());
    http_response_code(400);
}

Error Handling

Exception Types

• CreatePaymentFailedException
• RetrievePaymentFailedException
• GetPaymentsListFailedException
• RefundFailedException
• GetRefundIbanFailedException

Exception Example

try {
    $payment = $client->createPayment(1000, 'EUR');
} catch (CreatePaymentFailedException $e) {
    echo 'Payment creation failed: ' . $e->getMessage();
} catch (\Exception $e) {
    echo 'General error: ' . $e->getMessage();
}

Common Error Responses

// Check response for details
$response = $client->createPayment(1000, 'EUR');
if (isset($response->message)) {
    // API returned an error message
    echo 'Error: ' . $response->message;
}

Utility Methods

Get Environment

$environment = $client->getEnvironment(); // 'prod' or 'test'

Set Cache Directory for JWKS Keys

// If not set, the system tmp dir is used
$client->setCacheDir('/my/own/dir');

SEPA String Conversion

All strings (descriptions, references) are automatically converted to SEPA-compliant format:

• Removes diacritics/accents
• Filters to allowed characters only
• Truncates to maximum lengths

Best Practices

1. Idempotency for Refunds

// Always use idempotency keys for refunds
$idempotencyKey = 'unique-refund-key-' . time();
$client->refundPayment($paymentId, $amount, 'EUR', '', $idempotencyKey);

2. Webhook Security

• Always verify webhook signatures
• Never process unverified webhooks
• Implement replay attack protection

3. Cache Management

• JWKS keys are cached automatically
• Cache is refreshed on verification failures
• Cache refresh is done in a way to avoid hitting the jwks-servers too hard
• Cache directory can be set via method

Note: This client automatically handles SEPA compliance, JWKS caching, and signature verification according to Payconiq specifications.