PHP library for the Coinbase Commerce API and the new Coinbase Payment Link API.
PHP version 7.4 and above is supported.
This library supports two Coinbase APIs:
| Commerce API (Legacy) | Payment Link API (New) | |
|---|---|---|
| Auth | X-CC-Api-Key header |
JWT Bearer token (ES256) |
| Base URL | api.commerce.coinbase.com |
business.coinbase.com/api/v1 |
| Currency | Multiple cryptocurrencies | USDC only |
| Resources | Checkout, Charge, Invoice, Event | PaymentLink |
| Namespace | CoinbaseCommerce\ |
CoinbaseCommerce\PaymentLink\ |
- Commerce API docs: commerce.coinbase.com/docs/api
- Payment Link API docs: docs.cdp.coinbase.com/commerce-onchain/docs/payment-links
- Migrate from Commerce Overview
- Coinbase Business API Key Authentication
- Webhooks
- API & Schema Mapping
All errors that occur during any interaction with either API will be raised as exceptions:
| Error | Status Code |
|---|---|
| APIException | * |
| InvalidRequestException | 400 |
| ParamRequiredException | 400 |
| ValidationException | 400 |
| AuthenticationException | 401 |
| ResourceNotFoundException | 404 |
| RateLimitExceededException | 429 |
| InternalServerException | 500 |
| ServiceUnavailableException | 503 |
Install with composer:
composer require detain/coinbase-commerceThis will also install firebase/php-jwt (required for the Payment Link API).
To start using the Commerce API, register an account on Coinbase Commerce.
You will find your API_KEY from User Settings.
Initialize a Client for interacting with the API:
use CoinbaseCommerce\ApiClient;
//Make sure you don't store your API Key in your source code!
$apiClientObj = ApiClient::init(<API_KEY>);
$apiClientObj->setTimeout(3);$apiClientObj->verifySsl(false);The API resource class provides the following static methods: list, all, create, retrieve, updateById, deleteById. Additionally, the API resource class also provides the following instance methods: save, delete, insert, update.
Each API method returns an ApiResource which represents the JSON response from the API.
When the response data is parsed into objects, the appropriate ApiResource subclass will automatically be used.
It's prudent to be conscious of warnings. The library will log all warnings to a standard PSR-3 logger if one is configured.
use CoinbaseCommerce\ApiClient;
//Make sure you don't store your API Key in your source code!
$apiClientObj = ApiClient::init(<API_KEY>);
$apiClientObj->setLogger($logger);Checkouts API docs
More examples on how to use checkouts can be found in the examples/Resources/CheckoutExample.php file
use CoinbaseCommerce\Resources\Checkout;$checkoutObj = Checkout::retrieve(<checkout_id>);$checkoutData = [
'name' => 'The Sovereign Individual',
'description' => 'Mastering the Transition to the Information Age',
'pricing_type' => 'fixed_price',
'local_price' => [
'amount' => '100.00',
'currency' => 'USD'
],
'requested_info' => ['name', 'email']
];
$newCheckoutObj = Checkout::create($checkoutData);
// or
$newCheckoutObj = new Checkout();
$newCheckoutObj->name = 'The Sovereign Individual';
$newCheckoutObj->description = 'Mastering the Transition to the Information Age';
$newCheckoutObj->pricing_type = 'fixed_price';
$newCheckoutObj->local_price = [
'amount' => '100.00',
'currency' => 'USD'
];
checkoutObj->requested_info = ['name', 'email'];
checkoutObj->save();$checkoutObj = new Checkout();
$checkoutObj->id = <checkout_id>;
$checkoutObj->name = 'new name';
$checkoutObj->save();
// or
$newParams = [
'name' => 'New name'
];
Checkout::updateById(<checkout_id>, $newParams});$checkoutObj = new Checkout();
$checkoutObj->id = <checkout_id>;
$checkoutObj->delete();
// or
Checkout::deleteById(<checkout_id>);List method returns ApiResourceList object.
$params = [
'limit' => 2,
'order' => 'desc'
];
$list = Checkout::getList($params);
foreach($list as $checkout) {
var_dump($checkout);
}
// Get number of items in list
$count = $list->count();
// or
$count = count($list);
// Get number of all checkouts
$countAll = $list->countAll();
// Get pagination
$pagination = $list->getPagination();
// To load next page with previous setted params(in this case limit, order)
if ($list->hasNext()) {
$list->loadNext();
foreach($list as $checkout) {
var_dump($checkout);
}
}$params = [
'order' => 'desc'
];
$allCheckouts = Checkout::getAll($params);Charges API docs
More examples on how to use charges can be found in the examples/Resources/ChargeExample.php file
use CoinbaseCommerce\Resources\Charge;$chargeObj = Charge::retrieve(<charge_id>);$chargeData = [
'name' => 'The Sovereign Individual',
'description' => 'Mastering the Transition to the Information Age',
'local_price' => [
'amount' => '100.00',
'currency' => 'USD'
],
'pricing_type' => 'fixed_price'
];
Charge::create($chargeData);
// or
$chargeObj = new Charge();
$chargeObj->name = 'The Sovereign Individual';
$chargeObj->description = 'Mastering the Transition to the Information Age';
$chargeObj->local_price = [
'amount' => '100.00',
'currency' => 'USD'
];
$chargeObj->pricing_type = 'fixed_price';
$chargeObj->save();$list = Charge::getList();
foreach($list as $charge) {
var_dump($list);
}
$pagination = $list->getPagination();$allCharges = Charge::getAll();Resolve a charge that has been previously marked as unresolved.
$chargeObj = Charge::retrieve(<charge_id>);
if ($chargeObj) {
$chargeObj->resolve();
}
Cancels a charge that has been previously created. Note: Only new charges can be successfully canceled. Once payment is detected, charge can no longer be canceled.
$chargeObj = Charge::retrieve(<charge_id>);
if ($chargeObj) {
$chargeObj->cancel();
}
Invoices API docs
More examples on how to use charges can be found in the examples/Resources/InvoiceExample.php file
use CoinbaseCommerce\Resources\Invoice;$invoiceObj = Invoice::retrieve(<invoice_id>);$invoiceData = [
'business_name' => 'Crypto Account LLC',
'customer_email' => 'customer@test.com',
'customer_name' => 'Test Customer',
'local_price' => [
'amount' => '100.00',
'currency' => 'USD'
],
'memo' => 'Taxes and Accounting Services'
];
Invoice::create($invoiceData);
// or
$invoiceObj = new Invoice();
$invoiceObj->business_name = 'Crypto Account LLC';
$invoiceObj->customer_email = 'customer@test.com';
$invoiceObj->customer_name = 'Test Customer';
$invoiceObj->local_price = [
'amount' => '100.00',
'currency' => 'USD'
];
$invoiceObj->memo = 'Taxes and Accounting Services';
$invoiceObj->save();$list = Invoice::getList();
foreach($list as $invoice) {
var_dump($list);
}
$pagination = $list->getPagination();$allInvoices = Invoice::getAll();Resolve an invoice that has been previously marked as unresolved.
$invoiceObj = Invoice::retrieve(<charge_id>);
if ($invoiceObj) {
$invoiceObj->resolve();
}
Voids an invoice that has been previously created. Note: Only new or viewed invoices can be successfully voided. Once payment is detected, invoice can no longer be canceled.
$invoiceObj = Invoice::retrieve(<invoice_id>);
if ($invoiceObj) {
$invoiceObj->void();
}
Events API Docs
More examples on how to use events can be found in the examples/Resources/EventExample.php file
use CoinbaseCommerce\Resources\Event;$eventObj = Event::retrieve(<event_id>);$listEvent = Event::getList();
foreach($listEvent as $event) {
var_dump($event);
}
$pagination = $listEvent->getPagination();$allEvents = Event::getAll();Coinbase Commerce signs the webhook events it sends to your endpoint, allowing you to validate and verify that they weren't sent by someone else.
You can find a simple example of how to use this with Express in the examples/Webhook folder
use CoinbaseCommerce\Webhook;
try {
Webhook::verifySignature($signature, $body, $sharedSecret);
echo 'Successfully verified';
} catch (\Exception $exception) {
echo $exception->getMessage();
echo 'Failed';
}The Payment Link API uses CDP (Coinbase Developer Platform) API keys with ES256 JWT authentication. It currently supports USDC payments only.
More examples can be found in examples/PaymentLink/.
You'll need a CDP API key from the Coinbase Developer Platform. This gives you a key name (used as the JWT sub/kid) and an EC private key (PEM format) for ES256 signing.
use CoinbaseCommerce\PaymentLink\PaymentLinkClient;
use CoinbaseCommerce\PaymentLink\PaymentLink;
// Initialize the client with your CDP credentials
$client = new PaymentLinkClient(
getenv('COINBASE_CDP_KEY_NAME'), // CDP API key ID
getenv('COINBASE_CDP_PRIVATE_KEY') // EC private key PEM
);
// Optional: configure timeout (default 10s)
$client = new PaymentLinkClient($keyName, $privateKey, [
'timeout' => 15,
]);
// Set the client for the static PaymentLink facade
PaymentLink::setClient($client);$result = PaymentLink::create([
'amount' => '100.00',
'currency' => 'USDC',
'description' => 'Payment for order #12345',
'successRedirectUrl' => 'https://example.com/success',
'failRedirectUrl' => 'https://example.com/failed',
'metadata' => [
'orderId' => '12345',
'customerId' => 'cust_abc123',
],
]);
echo "Payment URL: {$result['url']}\n";
echo "Status: {$result['status']}\n"; // ACTIVE$link = PaymentLink::get($linkId);
echo "Status: {$link['status']}\n";$list = PaymentLink::list([
'pageSize' => 10,
'status' => 'ACTIVE',
]);
foreach ($list['paymentLinks'] as $link) {
echo "{$link['id']}: {$link['status']}\n";
}$deactivated = PaymentLink::deactivate($linkId);
echo "Status: {$deactivated['status']}\n"; // DEACTIVATEDPass an idempotency key to safely retry create requests:
$result = PaymentLink::create($params, 'unique-request-id-123');The Payment Link API uses a different webhook signature format (X-Hook0-Signature) than the Commerce API.
See examples/PaymentLink/WebhookExample.php for a complete example.
use CoinbaseCommerce\PaymentLink\PaymentLinkWebhook;
$payload = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_HOOK0_SIGNATURE'] ?? '';
// Collect request headers (normalized to lowercase keys)
$headers = [];
foreach ($_SERVER as $key => $value) {
if (strpos($key, 'HTTP_') === 0) {
$headerName = strtolower(str_replace('_', '-', substr($key, 5)));
$headers[$headerName] = $value;
}
}
$headers['content-type'] = $_SERVER['CONTENT_TYPE'] ?? 'application/json';
try {
// Verifies signature, checks replay protection (5 min default), then parses JSON
$event = PaymentLinkWebhook::buildEvent($payload, $signatureHeader, $webhookSecret, $headers);
switch ($event['eventType']) {
case 'payment_link.payment.success':
// Fulfill the order
break;
case 'payment_link.payment.failed':
// Handle failure
break;
case 'payment_link.payment.expired':
// Handle expiry
break;
}
http_response_code(200);
} catch (\CoinbaseCommerce\Exceptions\SignatureVerificationException $e) {
http_response_code(400);
}| Status | Description |
|---|---|
ACTIVE |
Link is live and accepting payments |
PROCESSING |
Payment is being processed |
COMPLETED |
Payment received successfully |
EXPIRED |
Link expired without payment |
DEACTIVATED |
Manually deactivated |
FAILED |
Payment failed |
Any and all contributions are welcome! The process is simple: fork this repo, make your changes, run the test suite, and submit a pull request. To run the tests, clone the repository and run the following commands:
composer install
composer testApache-2.0