Get started
Quickstart
Go from API key to a confirmed payment with a webhook receipt, in under five minutes.
What you need
- A merchant account in the Xpend Console (sandbox is fine).
- A server you control to receive webhooks.
- cURL, Node, or Python.
1. Create an API credential
In the Console, open Settings → API credentials → Create. The plaintext secret is shown once.
export XPEND_SECRET_KEY="key_id.plaintext_secret"
export XPEND_BASE="https://bapi.justxpend.ai"2. Verify the credential
A quick auth sanity check is /v1/merchant/principal.
curl $XPEND_BASE/v1/merchant/principal \
-H "Authorization: Bearer $XPEND_SECRET_KEY"Response
{
"merchant_id": "mch_01HXY...",
"environment": "sandbox",
"actor_type": "api_credential",
"actor_id": "cred_01HXY...",
"scopes": ["payment_intents:create", "payment_intents:read", "webhooks:manage"]
}3. Create a payment intent
Create an intent with a token amount, chain, token, and optional metadata. Pass an Idempotency-Key so retries never double-create.
curl $XPEND_BASE/v1/payment-intents \
-H "Authorization: Bearer $XPEND_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_8421" \
-d '{
"amount": "150.00",
"chain": "ethereum",
"token": "USDC",
"metadata": { "order_id": "order_8421" }
}'4. Register a webhook endpoint
Subscribe a server you control to the events you care about. Save the returned signing secret in your secret manager.
curl $XPEND_BASE/v1/webhooks/endpoints \
-H "Authorization: Bearer $XPEND_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/xpend",
"event_types": ["payment_intent.completed", "payout.completed"]
}'Save the signing secret
The signing secret is returned once from this endpoint and is required to verify deliveries. Store it in a secret manager before continuing.
5. Pay & receive the webhook
Display the returned deposit address or hosted checkout URL to the payer. When the on-chain deposit confirms, Xpend signs and POSTs a payment_intent.completed event to your endpoint.
That's it
You went from API key to a confirmed payment with a webhook receipt. Next: harden your consumer with signature verification and idempotency.