Record a transaction

Records a completed on-chain transaction. The txHash must be unique — a second call with the same txHash returns 409 with code: TRANSACTION_DUPLICATE.

This endpoint is used by the BAGS checkout flow; most merchants never need to call it directly. Call it yourself only if you are running a custom checkout and need to record a completed payment for reconciliation.

Authorization

apiKey

AuthorizationBearer <token>

BAGS Agent API key from the dashboard. Standalone agentic keys manage products, payment links, and transaction reads.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount*string|number

token*string

Value in"USDC" | "USDT" | "SOL" | "ETH" | "MATIC" | "POL"

network*string

Value in

"solana" | "solana_devnet" | "base" | "base_sepolia" | "ethereum" | "eth_sepolia" | "polygon" | "polygon_amoy" | "arc_testnet"

txHash*string

Length64 <= length <= 128

walletAddress*string

Length32 <= length <= 128

status?string

Default"completed"

Value in"completed" | "pending" | "failed" | "processing"

customerEmail?string

Lengthlength <= 320

customerName?string

Lengthlength <= 200

customerAddress?string

Lengthlength <= 500

customerCountry?string

Lengthlength <= 2

customerState?string

Lengthlength <= 64

paymentLinkId?string

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

curl -X POST "https://www.getbags.app/api/v1/transactions" \  -H "Content-Type: application/json" \  -d '{    "amount": "string",    "token": "USDC",    "network": "base",    "txHash": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"  }'

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 29.99,
    "amountBaseUnits": "29990000",
    "token": "USDC",
    "network": "base",
    "mode": "test",
    "livemode": false,
    "status": "completed",
    "txHash": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
    "merchantWalletAddress": "0x1111111111111111111111111111111111111111",
    "merchantId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "paymentLinkId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "customerEmail": "buyer@example.com",
    "customerName": "Jane Buyer",
    "customerAddress": "123 Market St, San Francisco, CA",
    "customerCountry": "US",
    "subtotalAmount": 29.99,
    "taxAmount": 0,
    "confirmedAt": "2026-04-16T12:34:56.000Z",
    "settledAt": null,
    "createdAt": "2026-04-16T12:34:56.000Z",
    "updatedAt": "2026-04-16T12:34:56.000Z"
  }
}

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "One or more fields failed validation."
}

{
  "status": "error",
  "code": "AUTH_MISSING_CREDENTIALS",
  "message": "No API key or session token was provided.",
  "hint": "Include a valid API key in the Authorization header: Bearer bag_live_sk_..."
}

{
  "status": "error",
  "code": "AUTH_TENANT_MISMATCH",
  "message": "The credential does not grant access to this resource."
}

{
  "status": "duplicate",
  "message": "string"
}

{
  "status": "error",
  "code": "TRANSACTION_CHAIN_VERIFY_FAILED",
  "message": "On-chain verification failed for the supplied txHash."
}

{
  "status": "error",
  "code": "RATE_LIMITED",
  "message": "Too many requests. Back off and retry.",
  "retryAfter": 60
}

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred. The incident has been logged."
}