API ReferenceTransactions
Record a transaction
Manually records a transaction that was processed outside of Bag's checkout flow. Use this when you handle payment collection yourself (e.g., direct wallet-to-wallet transfers) but want Bag to track the transaction for reporting and settlement purposes.
The txHash must be unique — submitting a duplicate returns a 409 Conflict.
Authorization
apiKey AuthorizationBearer <token>
API key authentication for programmatic access. Include your key in the
Authorization header:
Authorization: Bearer bag_live_sk_a1b2c3d4e5f6...Keys are prefixed with bag_live_sk_ (production) or bag_test_sk_
(sandbox). Generate keys from the Bag Dashboard.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.justusebag.xyz/api/transactions" \ -H "Content-Type: application/json" \ -d '{ "amount": 150, "token": "USDC", "network": "base", "txHash": "0x9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d", "walletAddress": "0xCuStOmEr1234567890abCdEf1234567890aBcDeF", "customerEmail": "alice@example.com", "customerName": "Alice Johnson" }'{
"status": "success",
"data": {
"_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"amount": 150,
"token": "USDC",
"network": "base",
"status": "completed",
"customerEmail": "alice@example.com",
"customerName": "Alice Johnson",
"txHash": "0x9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d",
"walletAddress": "0xCuStOmEr1234567890abCdEf1234567890aBcDeF",
"merchantWalletAddress": "0x1a2B3c4D5e6F7890abCdEf1234567890aBcDeF12",
"createdAt": "2026-03-01T10:15:00.000Z"
}
}{
"status": "error",
"message": "amount: Amount must be a positive number up to 999,999,999.99; network: Invalid enum value",
"code": "BAD_REQUEST"
}{
"status": "error",
"message": "Invalid or revoked API key",
"code": "UNAUTHORIZED",
"hint": "Include a valid API key in the Authorization header: Bearer bag_live_sk_..."
}{
"status": "error",
"message": "Transaction already recorded",
"code": "CONFLICT"
}{
"status": "error",
"message": "Too many requests. Please slow down.",
"retryAfter": 10
}