API Documentation

Current developer integration guide for API keys, wallets, payments, payouts, invoices, transactions, and webhooks.

Access Requirements

KYC Gate

Developer API access requires Tier 3 KYC. Tier 1 and Tier 2 merchants cannot create API keys or webhooks.

Authentication

Dashboard developer settings use Bearer auth. Integration endpoints use the x-api-key header.

Base URL

Local: http://localhost:3000
Production: use the deployed API host.

Request Headers

{
  "Content-Type": "application/json",
  "x-api-key": "rebble_test_or_live_key",
  "x-idempotency-key": "unique-request-id"
}

x-idempotency-key is optional for payment-link creation and required for payout quotes.

Permissions

payment_links:write

Create and manage payment links

payment_links:read

View payment links and their details

wallets:read

View merchant and customer wallets, balances, and receive addresses

wallets:write

Create merchant customer wallets

wallets:send

Quote and submit wallet sends and customer payments

invoices:read

View invoice details and public links

invoices:write

Create, update, send, and delete invoices

transactions:read

View transaction history and transaction details

counterparties:read

View saved payout counterparties and destinations

counterparties:write

Create and manage payout counterparties and destinations

payouts:read

View payout records and statuses

payouts:write

Quote and submit payouts to approved counterparties

Endpoint Reference

These are the developer-facing endpoints currently implemented in the backend.

API Key Management

Auth: Bearer token

These dashboard endpoints are used by authenticated merchants. Creating, updating, and rotating API keys require Tier 3 KYC.

MethodPathPurpose
GET/api/v1/developer/api-keys/permissionsList available API key permissions
POST/api/v1/developer/api-keysCreate an API key
GET/api/v1/developer/api-keysList API keys
PATCH/api/v1/developer/api-keys/:idUpdate an API key
DELETE/api/v1/developer/api-keys/:idDisable an API key
POST/api/v1/developer/api-keys/:id/rotateRotate an API key

Webhook Management

Auth: Bearer token

Webhook creation and management require Tier 3 KYC. A webhook secret is returned once when the endpoint is created.

MethodPathPurpose
POST/api/v1/developer/webhooksCreate a webhook endpoint
GET/api/v1/developer/webhooksList webhook endpoints
PATCH/api/v1/developer/webhooks/:idUpdate a webhook endpoint
DELETE/api/v1/developer/webhooks/:idDisable a webhook endpoint
POST/api/v1/developer/webhooks/:id/testSend a signed test webhook event
GET/api/v1/developer/webhook-eventsList webhook delivery events

Payment Links

Auth: x-api-keypayment_links:read / payment_links:write

Fixed-price links are checked against the merchant KYC volume and single-transaction limits. The idempotency header is optional for creation.

MethodPathPurpose
POST/api/v1/developer/payment-linksCreate a payment link
GET/api/v1/developer/payment-linksList payment links
GET/api/v1/developer/payment-links/:idGet a payment link
PATCH/api/v1/developer/payment-links/:idUpdate a payment link
POST/api/v1/developer/payment-links/:id/disableDisable a payment link
POST/api/v1/developer/payment-links/:id/enableEnable a payment link
DELETE/api/v1/developer/payment-links/:idDelete a payment link

Merchant Customer Wallets

Auth: x-api-keywallets:read / wallets:write / wallets:send

Creates reserved wallets for a merchant customer. Customer wallet limits are assigned internally from the submitted customer KYC status.

MethodPathPurpose
POST/api/v1/developer/customers/walletsCreate or fetch wallets for a merchant customer
GET/api/v1/developer/customers/:externalCustomerId/walletsList customer wallets
GET/api/v1/developer/customers/:externalCustomerId/wallets/balancesGet all customer wallet balances
GET/api/v1/developer/customers/:externalCustomerId/wallets/:walletId/balancesGet one customer wallet balance set
POST/api/v1/developer/customers/:externalCustomerId/wallets/send/quoteCreate a send quote from a customer wallet
POST/api/v1/developer/customers/:externalCustomerId/wallets/send/confirmConfirm a customer wallet send quote
POST/api/v1/developer/customers/:externalCustomerId/payments/quoteCreate a customer-to-merchant payment quote
POST/api/v1/developer/customers/:externalCustomerId/payments/confirmConfirm a customer-to-merchant payment quote

Merchant Wallets

Auth: x-api-keywallets:read / wallets:send

These endpoints expose merchant receive wallets, balances, and stablecoin send operations through the developer API.

MethodPathPurpose
GET/api/v1/developer/wallets/receiveList receive wallets
GET/api/v1/developer/wallets/receive/address/:assetGet receive address for an asset
GET/api/v1/developer/wallets/:id/balancesGet wallet balances
POST/api/v1/developer/wallets/sendSend stablecoin from a wallet
POST/api/v1/developer/wallets/send/quoteCreate a wallet send quote
POST/api/v1/developer/wallets/send/confirmConfirm a wallet send quote

Invoices

Auth: x-api-keyinvoices:read / invoices:write

Invoice totals are checked against merchant KYC volume and single-transaction limits.

MethodPathPurpose
POST/api/v1/developer/invoicesCreate and send an invoice
POST/api/v1/developer/invoices/draftsSave an invoice as draft
GET/api/v1/developer/invoicesList invoices
GET/api/v1/developer/invoices/:idGet an invoice
GET/api/v1/developer/invoices/:id/linkGet invoice public link
PATCH/api/v1/developer/invoices/:idUpdate an invoice
POST/api/v1/developer/invoices/:id/sendSend a draft invoice
DELETE/api/v1/developer/invoices/:idDelete an invoice

Counterparties and Payouts

Auth: x-api-keycounterparties:read / counterparties:write / payouts:read / payouts:write

Counterparties are saved payout recipients. Payout quotes require x-idempotency-key and are checked against merchant KYC transaction limits.

MethodPathPurpose
POST/api/v1/developer/counterpartiesCreate a payout counterparty
GET/api/v1/developer/counterpartiesList payout counterparties
GET/api/v1/developer/counterparties/:idGet a payout counterparty
PATCH/api/v1/developer/counterparties/:idUpdate a payout counterparty
DELETE/api/v1/developer/counterparties/:idArchive a payout counterparty
POST/api/v1/developer/counterparties/:id/destinationsAdd a validated crypto destination
PATCH/api/v1/developer/counterparties/:id/destinations/:destinationIdUpdate a crypto destination
DELETE/api/v1/developer/counterparties/:id/destinations/:destinationIdArchive a crypto destination
POST/api/v1/developer/payouts/quoteCreate a crypto payout quote
POST/api/v1/developer/payouts/confirmConfirm and submit a payout
GET/api/v1/developer/payoutsList payouts
GET/api/v1/developer/payouts/:idGet a payout

Transactions

Auth: x-api-keytransactions:read

The transaction list supports filters for direction, status, transactionType, currency, network, date range, limit, offset, and search.

MethodPathPurpose
GET/api/v1/developer/transactionsList transactions
GET/api/v1/developer/transactions/:idGet a transaction

Practical Examples

These examples show the normal integration flow consumers are likely to implement from their backend.

Create merchant customer wallets

Use this when a merchant wants Rebble to create reserved wallets for one of their platform users.

curl -X POST "$REBBLE_API_URL/api/v1/developer/customers/wallets" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REBBLE_API_KEY" \
  -d '{
    "externalCustomerId": "user_123",
    "kycStatus": "verified",
    "country": "NG",
    "email": "customer@example.com",
    "name": "John Doe",
    "metadata": {
      "source": "mobile_app"
    }
  }'

Check all balances for a customer

Use this after deposits or sends to show the customer's balances across Ethereum, Solana, and Tron wallets.

curl "$REBBLE_API_URL/api/v1/developer/customers/user_123/wallets/balances" \
  -H "x-api-key: $REBBLE_API_KEY"

Quote a customer-to-merchant payment

Use this when the merchant's customer is paying the merchant from their customer wallet.

curl -X POST "$REBBLE_API_URL/api/v1/developer/customers/user_123/payments/quote" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REBBLE_API_KEY" \
  -d '{
    "network": "solana",
    "tokenSymbol": "USDT",
    "amount": "20",
    "memo": "Order #1001"
  }'

Confirm a quoted customer payment

Use the quote token from the previous response. The backend submits the sponsored stablecoin payment.

curl -X POST "$REBBLE_API_URL/api/v1/developer/customers/user_123/payments/confirm" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REBBLE_API_KEY" \
  -d '{
    "quoteToken": "send_quote_abc123"
  }'

Create a fixed-price payment link

Use an optional idempotency key if your server may retry the request.

curl -X POST "$REBBLE_API_URL/api/v1/developer/payment-links" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REBBLE_API_KEY" \
  -H "x-idempotency-key: payment-link-order-1001" \
  -d '{
    "linkType": "fixed_price",
    "title": "Order #1001",
    "description": "Checkout payment",
    "blockchainNetwork": "solana",
    "coin": "USDT",
    "amount": "50"
  }'

Create a counterparty crypto destination

Save a payout recipient first, then add a validated crypto destination to avoid retyping addresses.

curl -X POST "$REBBLE_API_URL/api/v1/developer/counterparties" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REBBLE_API_KEY" \
  -d '{
    "name": "Supplier One",
    "email": "supplier@example.com",
    "country": "NG",
    "type": "business"
  }'

curl -X POST "$REBBLE_API_URL/api/v1/developer/counterparties/counterparty_id/destinations" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REBBLE_API_KEY" \
  -d '{
    "network": "solana",
    "tokenSymbol": "USDT",
    "address": "E42bKtQaNKin9258eRc4ByLVrMMyxvzjP8yX9DAUKVF7",
    "label": "Supplier Solana USDT"
  }'

Quote and confirm a payout

Payout quotes require an idempotency key because they move value from the merchant balance.

curl -X POST "$REBBLE_API_URL/api/v1/developer/payouts/quote" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REBBLE_API_KEY" \
  -H "x-idempotency-key: payout-1001" \
  -d '{
    "counterpartyId": "counterparty_id",
    "destinationId": "destination_id",
    "tokenSymbol": "USDT",
    "amount": "25",
    "memo": "Supplier payout"
  }'

curl -X POST "$REBBLE_API_URL/api/v1/developer/payouts/confirm" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REBBLE_API_KEY" \
  -d '{
    "quoteToken": "payout_quote_abc123"
  }'

Create a webhook endpoint

Create webhooks from the authenticated dashboard context. Store the returned secret immediately.

curl -X POST "$REBBLE_API_URL/api/v1/developer/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $REBBLE_ACCESS_TOKEN" \
  -d '{
    "url": "https://example.com/webhooks/rebble",
    "events": [
      "customer_wallet.funded",
      "customer.payment_completed",
      "payout.completed"
    ]
  }'

List transactions with filters

Use this to reconcile merchant activity from your own backend or reporting pipeline.

curl "$REBBLE_API_URL/api/v1/developer/transactions?status=completed&network=solana&limit=20&offset=0" \
  -H "x-api-key: $REBBLE_API_KEY"

Merchant Customer Wallet Payload

Customer wallet creation requires a merchant-side customer reference, customer KYC status, country, email, and name. Metadata is optional.

POST /api/v1/developer/customers/wallets

{
  "externalCustomerId": "user_123",
  "kycStatus": "verified",
  "country": "NG",
  "email": "customer@example.com",
  "name": "John Doe",
  "metadata": {
    "source": "mobile_app"
  }
}

Webhook Events

Webhook subscriptions can list specific events or use * to receive all events.

webhook.test
payment_link.paid
invoice.sent
invoice.paid
invoice.failed
customer_wallet.funded
customer_wallet.send_submitted
customer_wallet.send_completed
customer_wallet.send_failed
customer.payment_submitted
customer.payment_completed
customer.payment_failed
payout.submitted
payout.completed
payout.failed
{
  "url": "https://example.com/webhooks/rebble",
  "events": ["customer_wallet.funded", "customer.payment_completed"]
}

Webhook Delivery

Webhooks are delivered asynchronously and should be treated as at-least-once delivery. Store processed event IDs and make your handler idempotent.

Expected headers

X-Rebble-EventX-Rebble-TimestampX-Rebble-Signature

Best Practices

Keep API keys on the server side only.
Use the smallest permission set needed for each integration.
Rotate API keys periodically.
Store webhook secrets securely.
Verify webhook signatures before processing payloads.
Use idempotency keys for payout quote requests and retried payment-link creation requests.
Do not assume webhook events are delivered only once.
Use customer wallet payment quote endpoints when charging a merchant customer wallet.

Need the full schema?

The shareable OpenAPI document is available at /api/v1/developer-swagger.json and the shareable Swagger UI is available at /developer-docs.