API Reference

Authentication

BRICS Pay API uses OAuth 2.0 client credentials flow for authentication.

Base URL

https://api.bricspay.com/v1

Get Access Token

POST /oauth/token
Content-Type: application/json

Request:
{
  "grant_type": "client_credentials",
  "client_id": "bp_live_xxxxxxxxxxxx",
  "client_secret": "sk_live_xxxxxxxxxxxx"
}

Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Payments

Create QR Payment

POST /payments/qr
Authorization: Bearer {access_token}
Content-Type: application/json

Request:
{
  "amount": 150.50,
  "currency": "CNY",
  "merchant_id": "MERCHANT_001",
  "merchant_name": "ABC Store",
  "order_id": "ORD-123456",
  "description": "Purchase at ABC Store",
  "metadata": {
    "customer_id": "CUST_789",
    "items": ["Product A", "Product B"]
  }
}

Response:
{
  "payment_id": "PAY_abc123def456",
  "qr_code": "data:image/svg+xml;base64,...",
  "qr_string": "bricspay://pay/PAY_abc123def456",
  "amount": 150.50,
  "currency": "CNY",
  "status": "pending",
  "expires_at": "2026-04-04T12:30:00Z"
}

Get Payment Status

GET /payments/{payment_id}
Authorization: Bearer {access_token}

Response:
{
  "payment_id": "PAY_abc123def456",
  "status": "completed",
  "amount": 150.50,
  "currency": "CNY",
  "paid_at": "2026-04-04T12:25:30Z",
  "payer": {
    "country": "CN",
    "masked_id": "****1234"
  }
}

Wallets

Get Wallet Balance

GET /wallets/balance
Authorization: Bearer {access_token}

Response:
{
  "merchant_id": "MERCHANT_001",
  "balances": {
    "CNY": 12500.00,
    "USD": 5000.00,
    "INR": 75000.00
  }
}

Transactions

List Transactions

GET /transactions?from=2026-04-01&to=2026-04-04&limit=50
Authorization: Bearer {access_token}

Response:
{
  "transactions": [
    {
      "id": "TXN_xyz789",
      "payment_id": "PAY_abc123def456",
      "type": "payment",
      "amount": 150.50,
      "currency": "CNY",
      "status": "settled",
      "created_at": "2026-04-04T12:25:30Z"
    }
  ],
  "pagination": {
    "total": 1250,
    "page": 1,
    "limit": 50
  }
}

Refunds

Create Refund

POST /refunds
Authorization: Bearer {access_token}
Content-Type: application/json

Request:
{
  "payment_id": "PAY_abc123def456",
  "amount": 50.00,
  "reason": "Partial refund - item returned",
  "idempotency_key": "REF_123456789"
}

Response:
{
  "refund_id": "REF_xyz987",
  "payment_id": "PAY_abc123def456",
  "amount": 50.00,
  "status": "processing",
  "created_at": "2026-04-04T14:00:00Z"
}

Settlements

Get Settlement

GET /settlements/{settlement_id}
Authorization: Bearer {access_token}

Response:
{
  "settlement_id": "STL_abc456",
  "amount": 50000.00,
  "currency": "USD",
  "bank_account": "****5678",
  "status": "processing",
  "estimated_arrival": "2026-04-06"
}

Webhooks

Configure webhook endpoints to receive real-time payment notifications.

Headers

X-BRICS-Signature: sha256=xxxxxxxxxxxx
X-BRICS-Timestamp: 1712232000
Content-Type: application/json

Event Types

• payment.completed
• payment.failed
• payment.expired
• refund.completed
• refund.failed
• settlement.completed

Error Codes