Download the PHP package gobtcpay/php-merchant-sdk without Composer

gobtcpay/php-merchant-sdk

PHP client for the GoBTC Pay API — accept Bitcoin payments and track them until they settle on-chain. Two clients share one toolkit:

• GoBTCPay — POS terminals. Every request is signed with a fresh HMAC-SHA256 signature + timestamp (per-terminal key).
• GoBTCPayServer — server-side shop integrations. Authenticates with the merchant's secret key (sk_live_…): create a payment for an order, track it, cancel it, reconcile.

Both share webhook verification and payment polling helpers.

Requirements

• PHP 8.1+
• A PSR-18 HTTP client and PSR-17 factories. Install Guzzle and the SDK auto-discovers it — or pass your own implementation.

Installation

guzzlehttp/guzzle is a suggestion, not a hard dependency: any PSR-18 client works. With Guzzle installed you don't need to wire anything up.

⚠️ The POS apiKey and the server sk_live_… key are secrets. Keep them server-side or on a controlled POS device. Never ship them to a browser.

Quick start

POS terminal (GoBTCPay)

Server-side shop (GoBTCPayServer)

Bring your own HTTP client

Any PSR-18 client + PSR-17 factories work. Pass them explicitly to skip auto-discovery (or to reuse a configured client):

Configuration

GoBTCPay (POS)

GoBTCPayServer

Methods

GoBTCPay

GoBTCPayServer

listPayments() is a generator that pages transparently, newest first:

Auto-polling

watchPayment() returns a PaymentPoller. Because PHP request handlers are synchronous, poll() is a blocking loop: it calls getPayment on an interval until the payment reaches one of the statuses it stops at (paid / cleared / expired / canceled / failed). The interval defaults to and is clamped to a minimum of 3 seconds.

Options (array keys): paymentId (required), intervalMs, timeoutMs, immediate (default true), until (list of PaymentStatus), stopOnError.

paid vs cleared: paid means the funds are confirmed on-chain — the success state for external wallet payments. To stop as soon as that happens, pass 'until' => [PaymentStatus::Paid], or react to onPaid while polling continues.

Stopping is not the same as deciding. The default stop set is "no longer worth polling", not "nothing can change". expired in particular is not terminal on the server: the window closing does not close the payment, and funds arriving within the grace period still move it to paid afterwards — so cancelling an order on expired can strand a payment that later succeeds. When your decision is irreversible, read $payment->paidAt (settlement time, null until the payment settles) and $payment->transactions rather than PaymentStatus::isFinal().

Webhooks

Register a webhook URL in the merchant dashboard to receive payment.status.updated events. The handler verifies the X-GoBTCPay-Signature header (t={timestamp},v1={hmac_hex}), enforces a replay window, and de-duplicates on eventId.

Guard on hasPaymentData(). A test delivery (see below) arrives correctly signed, through the same listener, with no payment behind it — $event->test is true and $event->data is empty. Calling payment() on one throws a GoBTCPayException; answering 2xx anyway is the right behaviour, and it is what tells the sender the endpoint works.

handle() returns the parsed WebhookEvent, or null if it was a duplicate. Use constructEvent() to only verify + parse without dispatching. Always feed the raw request body — do not decode and re-encode it, or the signature will not match.

Inspecting and testing endpoints

listWebhooks() returns the endpoints configured for the merchant, and testWebhook() asks the platform to send a test delivery to one of them:

The test delivery is a normal signed delivery of type payment.status.updated carrying test: true and no payment data, so your existing handler receives it — guard with hasPaymentData() as shown above and answer 2xx.

Three things worth knowing before you build a "test my webhook" button on this:

• testWebhook() returning normally means the delivery was queued, not that it arrived. Deliveries are dispatched by a scheduled job, so the test lands at your endpoint some time later — and can still fail there. Whether the webhook works is answered at the receiving end, by observing the delivery.
• Both calls are merchant-level, so listWebhooks() doubles as the cheapest probe of whether a key can manage webhooks at all — an empty list is a perfectly successful answer, while a key restricted to a single store is refused with HTTP 403 (AuthException). The refusal does not say why: the same 403 covers a store-scoped key, a revoked key, an unknown key, a publishable key and an inactive merchant. Show the server's message rather than guessing the cause.
• listWebhooks() returns one page. Compare the page against totalCount and page with skip before concluding that a URL is not registered.

Plain PHP

Laravel

Symfony

Error handling

Every error extends GoBTCPay\PosApiSdk\Exception\GoBTCPayException:

The server client retries network failures, 429 and 5xx automatically (maxRetries, default 2) with exponential backoff + jitter. Reads and idempotent create calls (those with an externalId) are retried; a create without an externalId is not, so a retry can't double-charge. The POS client does not retry — a human at the terminal sees the failure and taps again.

Development

Docker

A Dockerfile is included so that all checks run in an identical environment locally and in CI:

CI builds this image per pipeline and runs lint, phpstan, and test jobs against it.

Testing

Unit tests — pure logic, no network. They gate every MR and run in CI: request signing (HMAC cross-checked against hash_hmac), the envelope transport (retries, typed exceptions), webhook verification (signature / replay window / de-dup), and the poller lifecycle.

Integration tests — exercise the SDK end-to-end against a live POS API on the test contour. Opt-in and self-skipping unless credentials are present:

Use test-contour credentials only — never a production key.

Versioning

The API version is pinned inside each client (POS v1.1, server v1.2), exported as GoBTCPay::API_VERSION / GoBTCPayServer::SERVER_API_VERSION — you don't put it in a URL. Need a different version or environment? Override baseUrl.

Publishing

How it works

1. A merge into main triggers the lint, phpstan, and test GitHub Actions jobs.
2. If they pass, the release job runs semantic-release, which reads the Conventional Commits since the last release: fix: bumps a patch version, feat: bumps minor, a BREAKING CHANGE: footer bumps major. Anything else (docs:, chore:, ci:, …) does not trigger a release.
3. On a release, semantic-release updates CHANGELOG.md, bumps SDK_VERSION in src/GoBTCPay.php / src/GoBTCPayServer.php, commits chore(release): x.y.z [skip ci], tags it, and creates a GitHub release.
4. That push fires a GitHub webhook (Settings → Webhooks, configured on this repo) that pings https://packagist.org/api/github. Packagist re-reads the tag from GitHub and publishes it as a new version — no manual "Update" click, no separate publish step.

Distribution is through the public Packagist package gobtcpay/php-merchant-sdk.

Giving this to a merchant

Nothing special — it's a public Composer package like any other. Point them at this repo or the Packagist page; they run composer require gobtcpay/php-merchant-sdk in their own project and follow Quick start. No token, no invite, no access request. Their apiKey / sk_live_… credentials are issued separately and are unrelated to installing the package.

Exception — WordPress/WooCommerce/Shopify plugins: those merchants typically don't run Composer at all, and bundling this SDK's dependencies (Guzzle, PSR interfaces) as-is risks class name collisions with other plugins on the same site. A plugin that embeds this SDK should vendor it at build time with a namespace-prefixing tool (php-scoper or Strauss) and ship the prefixed code inside the plugin's own zip — the merchant never touches Composer or this package directly.

License

MIT — see LICENSE. You may freely use, copy, modify, merge, publish, distribute, sublicense, and sell the software, including in closed-source and commercial products. Keep the copyright notice and license text in copies. Provided "as is", without warranty.