MakePay PHP SDK

Overview

The MakePay PHP SDK is the official Composer library for server-side MakePay integrations. It wraps API-key authentication, payment and donation links, anonymous public links, customers, subscriptions, invoices, bookkeeping, POS terminals, product catalogs, Simple Shop, branded domains, operational APIs, and signed webhook verification.

Public source repository:

https://github.com/makecryptoio/makepay-php-sdk

Packagist package:

https://packagist.org/packages/makepay/makepay-php

Installation

Install with Composer:

composer require makepay/makepay-php

For version-constrained installs, use the current 0.3 release line:

{
  "require": {
    "makepay/makepay-php": "^0.3"
  }
}

The SDK supports PHP 7.4 or newer and requires ext-json. ext-curl is used when available; otherwise JSON requests fall back to PHP streams.

Authentication

Create a MakePay API key from the MakeCrypto merchant developer area and keep the secret in server-side environment variables only.

use MakePay\Client;

$makepay = new Client([
    'keyId' => getenv('MAKEPAY_KEY_ID'),
    'keySecret' => getenv('MAKEPAY_KEY_SECRET'),
]);

The SDK sends X-MakeCrypto-Key-Id and X-MakeCrypto-Key-Secret headers to the MakePay partner API. You can pass baseUrl for a non-production MakeCrypto API origin, and checkoutBaseUrl for a custom MakePay checkout origin.

Create Payment Link

$response = $makepay->createPaymentLink([
    'title' => 'Order #1042',
    'description' => 'Checkout for order #1042',
    'amount' => '129.99',
    'currency' => 'USDT',
    'orderId' => 'order_1042',
    'customerEmail' => 'buyer@example.com',
    'returnUrl' => 'https://merchant.example/orders/1042',
    'successUrl' => 'https://merchant.example/orders/1042/success',
    'failureUrl' => 'https://merchant.example/orders/1042/pay',
    'expirationTime' => '12h',
]);

header('Location: ' . $response['paymentLink']['publicUrl']);

Send a payment request email during creation:

$makepay->createPaymentLink($payload, [
    'sendPaymentRequestEmail' => true,
]);

Read and manage existing links:

$makepay->listPaymentLinks();
$makepay->getPaymentLink('PAYMENT_LINK_UID');
$makepay->updatePaymentLink('PAYMENT_LINK_UID', ['status' => 'paused']);
$makepay->sendPaymentRequestEmail('PAYMENT_LINK_UID', 'buyer@example.com');

Donation Links

Donation links use the same settlement and checkout infrastructure as payment links, but they publish a public donation slug and allow flexible donor amounts.

$donation = $makepay->createDonationLink([
    'title' => 'Spring campaign',
    'description' => 'Support the 2026 spring fundraiser.',
    'defaultAmountUsd' => '25',
    'minimumAmountUsd' => '5',
    'donationSlug' => 'spring-campaign',
]);

$makepay->listDonationLinks();
$makepay->getDonationLink('DONATION_UID');
$makepay->updateDonationLink('DONATION_UID', ['status' => 'paused']);

Anonymous Payment Links

Use anonymous links when a payment page should be created without a MakePay API key. Because there is no authenticated merchant account, the request must include settlement routing.

use MakePay\Client;

$response = Client::createAnonymousPaymentLink([
    'amount' => '25',
    'settlement' => [
        'currency' => 'USDT',
        'priorities' => [
            [
                'chain' => 'ETH',
                'address' => '0xYourSettlementWallet',
                'asset' => 'ETH.USDT-0xdAC17F958D2ee523a2206206994597C13D831ec7',
            ],
        ],
    ],
    'title' => 'Invoice #1042',
    'customerEmail' => 'buyer@example.com',
    'webhookUrl' => 'https://merchant.example/webhooks/makepay',
]);

Anonymous link payloads support title, description, orderId, clientId, customerEmail, returnUrl, successUrl, failureUrl, metadata, branding, webhookUrl, and expirationTime values from 15 minutes to 72 hours.

Hosted And Embedded Checkout

Use hosted checkout URLs for full-page redirects, or the embed helpers when your frontend keeps the shopper on the merchant page.

$paymentUid = $response['paymentLink']['uid'];

$hostedUrl = $makepay->hostedCheckoutUrl($paymentUid);
$embedUrl = $makepay->embeddedCheckoutUrl($paymentUid, [
    'parentOrigin' => 'https://merchant.example',
]);

echo $makepay->embedButtonHtml($paymentUid, [
    'buttonLabel' => 'Pay with crypto',
]);

echo $makepay->iframeHtml($paymentUid, [
    'iframeTitle' => 'Secure MakePay checkout',
]);

Donation pages have hosted and embedded URL helpers too:

$makepay->hostedDonationUrl('spring-campaign');
$makepay->embeddedDonationUrl('spring-campaign', [
    'parentOrigin' => 'https://merchant.example',
]);

Use a hosted link fallback beside every iframe so shoppers can continue if the browser, CMS, or store theme blocks embedded payment pages.

Customers

$makepay->upsertCustomer([
    'email' => 'buyer@example.com',
    'name' => 'Buyer Example',
    'clientId' => 'crm_123',
    'metadata' => ['plan' => 'pro'],
]);

$makepay->listCustomers();

$makepay->createCustomerPortal('CUSTOMER_ID', [
    'returnUrl' => 'https://merchant.example/account',
]);

Subscriptions

$makepay->createSubscription([
    'amountUsd' => '29',
    'customerEmail' => 'buyer@example.com',
    'label' => 'Monthly plan',
    'billingIntervalUnit' => 'month',
    'billingIntervalCount' => 1,
    'sendPaymentRequestEmail' => true,
]);

$makepay->listSubscriptions();

Subscription invoice payment links are generated by the subscription API. Do not create subscription_invoice links directly through createPaymentLink.

POS Terminals

$terminal = $makepay->createPosTerminal([
    'name' => 'Front counter',
    'pin' => '1234',
    'allowedAssets' => ['ETH.USDT-0xdAC17F958D2ee523a2206206994597C13D831ec7'],
    'emailCollectionMode' => 'optional_after_deposit',
    'catalogEnabled' => true,
]);

$makepay->listPosTerminals();
$makepay->getPosTerminal('POS_UID');
$makepay->updatePosTerminal('POS_UID', [
    'name' => 'Front counter',
    'pin' => '5678',
    'catalogEnabled' => true,
]);

Products

Products power POS catalogs and Simple Shop storefronts.

$makepay->createProduct([
    'name' => 'Digital guide',
    'productType' => 'digital',
    'basePriceUsd' => '19',
    'shopSlug' => 'digital-guide',
    'images' => [
        ['url' => 'https://merchant.example/guide.png', 'alt' => 'Guide cover'],
    ],
    'taxRates' => [
        ['name' => 'VAT', 'rateBps' => 2000, 'isDefault' => true],
    ],
]);

$makepay->listProducts();
$makepay->getProduct('PRODUCT_UID');
$makepay->updateProduct('PRODUCT_UID', [
    'name' => 'Digital guide',
    'status' => 'active',
]);

Digital products can include downloads:

$makepay->createProductDownload('PRODUCT_UID', [
    'fileName' => 'guide.pdf',
    'contentType' => 'application/pdf',
    'url' => 'https://merchant.example/downloads/guide.pdf',
]);

$makepay->listProductDownloads('PRODUCT_UID');

Simple Shop

$makepay->updateShop([
    'slug' => 'merchant-shop',
    'displayCurrency' => 'USD',
    'checkoutMode' => 'hosted',
    'billingDetailsRequired' => true,
    'flatShippingFeeUsd' => '5',
    'freeShippingThresholdUsd' => '100',
    'branding' => ['accentColor' => '#14b8a6'],
]);

$makepay->getShop();
$makepay->updateShopBuilder(['blocks' => []]);
$makepay->getShopBuilder();

Connect and verify a shop domain:

$makepay->updateShopDomain('shop.merchant.example');
$makepay->getShopDomain();
$makepay->refreshShopDomain();

Manage coupons and orders:

$makepay->createShopCoupon([
    'code' => 'SPRING10',
    'discountType' => 'percent',
    'value' => '10',
]);

$makepay->listShopCoupons();
$makepay->updateShopCoupon('COUPON_UID', ['status' => 'archived']);
$makepay->archiveShopCoupon('COUPON_UID');
$makepay->listShopOrders(['status' => 'paid', 'limit' => 25]);

Invoices And Bookkeeping

Bookkeeping APIs manage merchant invoices, expenses, supporting documents, OCR, and reconciliation links.

$makepay->createBookkeepingInvoice([
    'title' => 'Invoice #1042',
    'currency' => 'USD',
    'issueDate' => '2026-05-15',
    'dueDate' => '2026-05-30',
    'counterparty' => [
        'name' => 'Buyer Example',
        'email' => 'buyer@example.com',
        'clientId' => 'crm_123',
    ],
    'lineItems' => [
        [
            'description' => 'Implementation services',
            'quantity' => '1',
            'unitAmount' => '500',
            'taxAmount' => '0',
        ],
    ],
    'metadata' => ['orderId' => 'order_1042'],
]);

$makepay->createBookkeepingInvoicePaymentLink('INVOICE_UID', [
    'sendPaymentRequestEmail' => true,
]);

$makepay->listBookkeepingInvoices();
$makepay->getBookkeepingInvoice('INVOICE_UID');
$makepay->updateBookkeepingInvoice('INVOICE_UID', ['status' => 'open']);

Create and reconcile expenses manually or from wallet activity:

$makepay->createBookkeepingExpense([
    'title' => 'Hosting',
    'amount' => '49',
    'currency' => 'USD',
    'incurredOn' => '2026-05-15',
    'category' => 'Infrastructure',
    'counterparty' => ['name' => 'Vendor Example', 'type' => 'vendor'],
]);

$makepay->createBookkeepingExpenseFromActivity([
    'walletActivityEventKey' => 'CHAIN_EVENT_KEY',
    'category' => 'Settlement',
]);

$makepay->createBookkeepingReconciliation([
    'invoiceId' => 'INVOICE_UID',
    'paymentSessionId' => 'PAYMENT_SESSION_ID',
    'linkType' => 'payment',
]);

Document uploads use multipart form data and accept a local path string or CURLFile.

$makepay->uploadBookkeepingDocument([
    'file' => __DIR__ . '/receipt.pdf',
    'fileName' => 'receipt.pdf',
    'contentType' => 'application/pdf',
    'documentType' => 'receipt',
    'expenseId' => 'EXPENSE_UID',
]);

$makepay->listBookkeepingDocuments();
$makepay->getBookkeepingDocumentDownloadUrl('DOCUMENT_UID');
$makepay->runBookkeepingDocumentOcr('DOCUMENT_UID');
$makepay->getBookkeepingSummary();

Branding And Domains

Branding controls merchant display details, checkout theme colors, payment-link domains, and email-sending domains.

$makepay->updateBranding([
    'brandName' => 'Merchant',
    'businessDescription' => 'Digital products and services.',
    'websiteUrl' => 'https://merchant.example',
    'supportEmail' => 'support@merchant.example',
    'brandingBrandColor' => '#111827',
    'brandingBrandTextColor' => '#ffffff',
    'brandingAccentColor' => '#14b8a6',
    'brandingAccentTextColor' => '#ffffff',
    'paymentLinkTheme' => 'system',
    'paymentLinkDomain' => 'pay.merchant.example',
    'emailSendingDomain' => 'mail.merchant.example',
]);

$makepay->getBranding();
$makepay->refreshBrandingDomains('all');

Use refreshBrandingDomains('payment-link') or refreshBrandingDomains('email-sending') when you only need one domain check.

Operational APIs

$makepay->getSettings();
$makepay->updateSettings([
    'callbackUrl' => 'https://merchant.example/webhooks/makepay',
]);

$makepay->listDestinationAssets();
$makepay->listWebhookRequests(['limit' => 25]);

listDestinationAssets is useful before configuring settlement overrides or anonymous settlement routes.

Webhook Verification

MakePay signs the exact raw request body. Read php://input before parsing JSON.

use MakePay\Webhook;

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_MAKEPAY_SIGNATURE'] ?? null;

$event = Webhook::parse(
    $rawBody,
    $signature,
    getenv('MAKEPAY_WEBHOOK_SECRET')
);

if (($event['event']['type'] ?? '') === 'status_changed') {
    // Update your local order.
}

http_response_code(200);
echo 'ok';

Use Webhook::verify() when you only need a boolean result.

SDK Method Coverage

Area	Methods
Payment links	createPaymentLink, listPaymentLinks, getPaymentLink, updatePaymentLink, sendPaymentRequestEmail
Donations	createDonationLink, listDonationLinks, getDonationLink, updateDonationLink
Anonymous links	Client::createAnonymousPaymentLink, Client::createAnonymousMakePayPaymentLink
Checkout	hosted, embedded, modal, button, iframe, and donation URL helpers
Customers	listCustomers, upsertCustomer, createCustomerPortal
Subscriptions	listSubscriptions, createSubscription
POS terminals	listPosTerminals, createPosTerminal, getPosTerminal, updatePosTerminal
Products	listProducts, createProduct, getProduct, updateProduct, listProductDownloads, createProductDownload
Simple Shop	getShop, updateShop, getShopBuilder, updateShopBuilder, getShopDomain, updateShopDomain, refreshShopDomain, coupon and order methods
Bookkeeping	summary, invoice, expense, document upload/OCR, and reconciliation methods
Branding	getBranding, updateBranding, refreshBrandingDomains
Operations	getSettings, updateSettings, listDestinationAssets, listWebhookRequests
Webhooks	Webhook::verify, Webhook::parse, plus client proxy methods

Data Models And Response Models

Payload arrays use the same camelCase field names as the MakePay API and npm SDK. Some API routes also accept snake_case for compatibility, but new integrations should send camelCase.

• Use strings for decimal money values when precision matters, for example "129.99" instead of 129.99.
• Dates are ISO strings. Date-only fields, such as invoice issueDate, should use YYYY-MM-DD.
• IDs are usually public uid values. Bookkeeping detail endpoints accept an internal UUID or public UID.
• Successful responses are decoded associative arrays. Production can add fields without breaking PHP consumers.

Accepted Payload Models

Model	Used by	Required fields	Common optional fields
Payment link array	createPaymentLink	amount	title, description, currency, asset, orderId, customerEmail, clientId, redirect URLs, metadata
Donation link array	createDonationLink	none	defaultAmountUsd, minimumAmountUsd, donationSlug, payment-link display and redirect fields
Anonymous payment link array	Client::createAnonymousPaymentLink	amount, settlement.currency, settlement.priorities	title, customerEmail, orderId, metadata, branding, webhookUrl, checkout redirect URLs
Customer array	upsertCustomer	one of email, customerEmail, name, clientId	metadata
Subscription array	createSubscription	plan amount/customer fields for your billing flow	amountUsd, customerEmail, label, billingIntervalUnit, billingIntervalCount, startAt, sendPaymentRequestEmail
POS terminal array	createPosTerminal, updatePosTerminal	name	pin, status, allowedAssets, emailCollectionMode, catalogEnabled, displaySettings, metadata
Product array	createProduct, updateProduct	name	description, sku, status, productType, basePriceUsd, shopSlug, images, variants, taxRates, metadata
Shop array	updateShop	none	slug, status, displayCurrency, checkoutMode, shipping fields, links, SEO, tracking, branding
Branding array	updateBranding	none	brand name, support email, website URL, theme colors, paymentLinkDomain, emailSendingDomain
Invoice array	createBookkeepingInvoice, updateBookkeepingInvoice	none; blank invoices are allowed as drafts	invoiceNumber, status, paymentStatus, currency, issueDate, dueDate, counterparty, lineItems, documentIds
Expense array	createBookkeepingExpense, createBookkeepingExpenseFromActivity, updateBookkeepingExpense	none; amount defaults to zero if no activity is used	amount, currency, category, incurredOn, wallet activity IDs, counterparty, metadata
Document upload array	uploadBookkeepingDocument	file	fileName, contentType, documentType, invoiceId, expenseId
Reconciliation array	createBookkeepingReconciliation	one target and one source	target: invoiceId or expenseId; source: payment, subscription cycle, or wallet activity; amount, assetSymbol, metadata

Error Handling

API errors throw MakePay\MakePayException. The exception includes the HTTP status code and decoded response body.

use MakePay\MakePayException;

try {
    $makepay->getPaymentLink('PAYMENT_LINK_UID');
} catch (MakePayException $error) {
    error_log($error->getMessage());
    error_log((string) $error->getStatusCode());
}

Source Layout

The canonical monorepo source lives in apps/plugins/php-sdk. The public repository at https://github.com/makecryptoio/makepay-php-sdk mirrors only the SDK files so developers can install or inspect it without the full MakeCrypto workspace.