Endpoint

POST /api/v1/checkout creates a PENDING transaction and returns checkout URL.

POST /api/v1/checkout
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "orderId": "INV-2026-001",
  "amount": 10,
  "currency": "SOL",
  "customerEmail": "buyer@example.com",
  "customerReference": "CUST-REF-001",
  "customerName": "Avery Stone",
  "notes": "Priority support customer",
  "successUrl": "https://yourstore.com/success",
  "cancelUrl": "https://yourstore.com/cart"
}

Request body

• orderId: required, unique per merchant.
• amount: required, positive number.
• currency: required, currently only SOL.
• customerEmail, customerReference, customerName, notes, successUrl, cancelUrl: optional.

Responses

Success returns 201. Errors return structured payload with error.code and diagnostics.

After settlement, customer checkout page shows a structured paid receipt with order reference and on-chain verification link.

During payment, checkout also provides a QR code so customers can scan and continue the same hosted session on mobile wallets.

Success 201

{
  "message": "Checkout session created successfully",
  "transactionId": "txn_7K29...",
  "checkoutUrl": "https://trezalink.com/pay/txn_7K29...",
  "expiresAt": "2026-05-21T10:00:00.000Z"
}

Error contract

{
  "error": {
    "code": "CHECKOUT_VALIDATION_FAILED",
    "message": "Request payload failed validation.",
    "requestId": "req_0f8f7a7b-...",
    "retryable": false,
    "docsUrl": "/docs/error-reference#error-checkout_validation_failed",
    "details": {
      "amount": {
        "_errors": ["Amount must be a positive number"]
      }
    }
  }
}

Troubleshooting

• Log requestId in your backend logs to correlate failed calls.
• Use retryable=true as machine signal for safe retry behavior.
• Open docsUrl to jump directly to the error reference anchor.
• For maintenance responses (503), respect Retry-After before retrying.