v1 REST Specification

API Reference

Direct endpoints for invoice creation, cryptographic validation, on-chain transaction verification, and event synchronization on Robinhood Chain.

POST/api/v1/invoices/create

Create Invoice

Generates a signed, self-contained payment invoice token (inv_...) without writing to a database.

Request Body (JSON)

{
  "merchant": "0x2ae25f1c0e6431bc7d93c26be79762e7e02c8ead",
  "amount": "49.00",
  "token": "USDC", // or "ETH"
  "description": "Pro Tier Subscription",
  "externalRef": "ORD-2026-X839",
  "expiresInMinutes": 1440
}

Response (200 OK / 201 Created)

{
  "token": "inv_eyJtZXJjaGFudCI6IjB4MmFlMjVmMWMwZTY0...",
  "url": "https://robinpay.xyz/pay/inv_eyJtZXJjaGFudCI6IjB4MmFlMjVmMWMwZTY0...",
  "expiresAt": 1792434000
}

GET/api/v1/invoices/:token

Get Invoice Details

Decodes and validates a cryptographic invoice token, checking signature and expiration status.

Response (200 OK / 201 Created)

{
  "valid": true,
  "invoice": {
    "merchant": "0x2ae25f1c0e6431bc7d93c26be79762e7e02c8ead",
    "amount": "49000000",
    "token": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
    "decimals": 6,
    "description": "Pro Tier Subscription",
    "externalRef": "ORD-2026-X839",
    "verified": false,
    "exp": 1792434000
  }
}

POST/api/v1/checkout/verify

Verify Payment Transaction

Derives confirmation status directly from the Robinhood Chain block receipt and dispatches registered webhooks.

Request Body (JSON)

{
  "token": "inv_eyJtZXJjaGFudCI6IjB4MmFlMjVmMWMwZTY0...",
  "txHash": "0x6406fc67749c72b6e261d931c071f742409acb3707c7dd7880701d5c69a04e08"
}

Response (200 OK / 201 Created)

{
  "status": "PAID",
  "orderId": "ORD-2026-X839",
  "txHash": "0x6406fc67749c72b6e261d931c071f742409acb3707c7dd7880701d5c69a04e08",
  "verified": false
}

GET/api/v1/events?merchant=0x...

Query Merchant Payment Logs

Returns real-time PaymentProcessed events and direct ERC20 transfers on Robinhood Chain Testnet (46630).

Response (200 OK / 201 Created)

{
  "events": [
    {
      "type": "PaymentProcessed",
      "blockNumber": "138212940",
      "txHash": "0x6406fc67749c72b6e261d931c071f742409acb3707c7dd7880701d5c69a04e08",
      "args": {
        "orderId": "ORD-2026-MXS9RM",
        "payer": "0x49F4AED7512120fC0690bCb4786810Ffe28c3236",
        "amount": "0.0001 ETH"
      }
    }
  ],
  "head": "138215000"
}

POST/api/testnet/faucet

Request Testnet Tokens

Mints 100 Testnet USDC on Robinhood Chain Testnet to any recipient address.

Request Body (JSON)

{
  "address": "0x49F4AED7512120fC0690bCb4786810Ffe28c3236",
  "token": "USDC"
}

Response (200 OK / 201 Created)

{
  "success": true,
  "txHash": "0x78ab12...",
  "amount": "100.00 USDC",
  "network": "Robinhood Chain Testnet (46630)"
}

Error Schemas & Status Codes

All error responses return { error: { code, message } } with appropriate HTTP status codes:

Error Code	HTTP Status	Reason
INVALID_TOKEN	400	The invoice token has expired or the cryptographic HMAC signature failed.
INVALID_TX	400	Transaction reverted or receipt not found on Robinhood Chain Testnet.
AMOUNT_MISMATCH	400	The gross on-chain transferred amount is less than invoice requirement.
RATE_LIMITED	429	Exceeded IP or merchant rate limit window (includes retryAfter header).
PENDING	202	Transaction is in the mempool and awaiting required block confirmations.