Download the PHP package lacasoft/coatipay-sdk without Composer

lacasoft/coatipay-sdk — PHP SDK

The CoatiPay PHP SDK — Stripe-compatible payments for the open web. Accept USDC on Base with no gatekeepers: gasless settlement (ERC-3009), webhooks, and x402 micropayments. 1.5% protocol fee (1.05% nodeit / 0.45% treasury), settled trustlessly on-chain.

• ⛽ Gasless for payers — they sign an ERC-3009 authorization; the nodeit pays the gas.
• 🧩 Stripe-like DX — paymentIntents->create(...), webhooks->verify(...).
• 🌐 Open network — no lock-in: any nodeit can settle your payments, and anyone can run one.

Install

Requires PHP ≥ 8.1. Depends on guzzlehttp/guzzle.

Quick start

Other payment-intent methods: retrieve($id), list($limit = 10, $startingAfter = null), cancel($id).

Gasless settlement with ERC-3009

Payers authorize USDC transfers off-chain with an EIP-712 signature. The nodeit pays the gas to settle on-chain.

intentId is required: the authorization's ERC-3009 nonce is that intent. The SettlementHub enforces nonce == keccak256(utf8(intentId)), so a signature can only ever pay the intent it was signed for — the nodeit that submits the transaction cannot redirect it to a different intent.

Pass the plain pi_… id: the SDK derives the on-chain bytes32 for you, so there is no hash to get wrong. If you build the typed data yourself, derive it with the same helper the SDK uses:

For batch settlement, pass a list of ['intent_id' => ..., 'authorization' => $auth] items to $relay->paymentIntents->submitAuthorizationBatch($items) (max 50 per batch).

x402 micropayments

Protect a route with a PSR-15 middleware that returns 402 Payment Required when the X-PAYMENT header is missing or invalid.

Webhooks

• verify() checks the HMAC-SHA256 signature in constant time and rejects a timestamp more than 5 minutes away from now (replay protection): ['tolerance' => …] changes it, in seconds.
• On failure it throws WebhookSignatureError (an \InvalidArgumentException) with a reason: malformed_header, timestamp_out_of_tolerance or no_matching_signature.
• Events: payment_intent.created, payment_intent.settled, payment_intent.expired, payment_intent.cancelled.
• Changing the secret. The API does not rotate secrets yet. Register a second endpoint with the same URL, verify with either secret while both exist (the same event arrives through each, with the same $event['id']), then delete the old one. verify() already accepts a header with several v1 signatures, for when the API signs with two.
• Deliveries that exhausted their retries stay in a dead-letter queue:

Errors

Everything a call throws is a CoatiPaySDKError, with errorCode, the message, param and docUrl (the code's page at coatipay.com/docs/errors). The class tells the kind: AuthError, ValidationError, RoutingError, PaymentError, RateLimitError, or the base class for the rest and for a code this version does not know. NetworkError is one too, so catch it first. The same classes and rules in the JS and Python SDKs.

Configuration

Economics

The protocol fee is 1.5% (1.05% nodeit / 0.45% treasury), settled on-chain. The API enforces a minimum payment floor (~$0.30) — intents below it are rejected, because around that point the protocol fee stops covering settlement gas reliably, even when batched. Sub-cent x402 micropayments are on the roadmap via off-chain netting (aggregating many tiny payments into one on-chain settlement).

Links

• Repo, docs & protocol spec: https://github.com/lacasoft/coatipay-protocol
• Source: coatipay-php-sdk
• License: Apache-2.0