{"version":"1.0","service":{"name":"AtomicRails Gift Card Store","description":"Buy gift cards, mobile top-ups, and digital products with USDC on Base. 10,001+ brands across 180 countries.","url":"https://x402.atomicrails.com"},"payment":{"protocol":"x402","scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bDA02913","assetSymbol":"USDC","assetDecimals":6,"note":"Default rail is USDC on Base. Send X-Preferred-Network: <id> on POST /v1/orders to choose a different rail (see networks[] below). Prices are set by the product; amount is returned in PAYMENT-REQUIRED on the first POST."},"networks":[{"id":"base","default":true,"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bDA02913","assetSymbol":"USDC","assetDecimals":6,"signing":"EIP-3009 transferWithAuthorization (EIP-712). Payload shape: { signature, authorization: {from, to, value, validAfter, validBefore, nonce} }.","extra":{"name":"USD Coin","version":"2","decimals":6}},{"id":"solana","default":false,"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","assetSymbol":"USDC","assetDecimals":6,"signing":"Build an SPL token Transfer instruction to the ATA derived from (owner=payTo, mint=asset). Partially-sign the versioned transaction with your wallet. The facilitator countersigns as feePayer (extra.feePayer in PAYMENT-REQUIRED) and broadcasts. Payload shape: { transaction: <base64-encoded partially-signed tx> }.","extra_required":["feePayer"],"phase2_must_echo":"X-Session-Id header from the 402 response (the Solana payload is opaque, so the gateway needs the session id to route the resubmit)."}],"request_headers":{"X-Preferred-Network":"Optional. id of one of networks[] above. Defaults to the network with default:true.","X-Session-Id":"Required on Phase 2 for Solana, optional for Base. Echoed verbatim from the X-Session-Id response header on the 402."},"response_headers":{"PAYMENT-REQUIRED":"Phase 1 only. base64url-encoded JSON, x402 v2 PaymentRequired envelope.","X-Session-Id":"Phase 1 only. UUID identifying this payment session. Echo on Phase 2 via the X-Session-Id request header."},"flow":["1. GET /v1/brands?country_code=us — discover brand names available in a country.","2. GET /v1/catalog?country_code=us&brand_name=<brand_name> — get product_id values and pricing for that brand.","3. POST /v1/orders (optionally X-Preferred-Network: solana, default base) — server responds 402 with PAYMENT-REQUIRED header (rail-specific JSON) and an X-Session-Id header.","4. Build the rail-specific payload — EVM: sign an EIP-3009 authorization. Solana: build + partially-sign an SPL transfer transaction with the destination ATA derived from payTo+asset. Encode as base64url JSON matching the AcceptedPayment schema.","5. Re-POST /v1/orders with PAYMENT-SIGNATURE header (and X-Session-Id, which is required for Solana) — server verifies, settles via the facilitator, returns 200 with order receipt.","6. Poll GET /v1/orders/{order_id} until status is 'completed'. Voucher codes appear in deliveries[]."],"endpoints":{"brands":{"method":"GET","path":"/v1/brands","description":"Discover all brands available in a country. Use this first to get brand_name values for the catalog endpoint.","parameters":{"country_code":{"type":"string","required":true,"example":"us","note":"Lowercase ISO 3166-1 alpha-2 country code."}},"response_fields":{"brand_name":"Use this value as brand_name in /v1/catalog.","family":"Product family (e.g. Gift Cards, Mobile Recharge).","category":"Product category (e.g. Gaming, Entertainment).","min":"Minimum denomination available (informational).","max":"Maximum denomination available (informational)."}},"catalog":{"method":"GET","path":"/v1/catalog","description":"Get available denominations and product_id values for a specific brand. Use brand_name values from /v1/brands.","parameters":{"country_code":{"type":"string","required":true,"example":"us","note":"Lowercase ISO 3166-1 alpha-2 country code."},"brand_name":{"type":"string","required":false,"example":"Amazon.com","note":"Brand name from /v1/brands. At least one of brand_name or family_name is required."},"family_name":{"type":"string","required":false,"example":"Gaming","note":"Filter by product family from /v1/brands response."}},"response_fields":{"product_id":"Use this value in items[].product_id when placing an order.","product_name":"Human-readable product name, including denomination (e.g. 'Free Fire Gift Card 100 Diamonds').","brand_name":"Brand for this product.","is_range":"Boolean. true = range product (caller picks USD amount via product_value). false = fixed denomination.","denomination":"Upstream descriptive denomination when available (e.g. '100 Diamonds'). Absent for generic currency-only products.","denomination_label":"Short human-readable tag that is unique per row of the same brand ('100 Diamonds', '$25', '$5 – $500').","face_value_usd":"Fixed USD face value. Present only when is_range is false.","currency":"Face-value currency (typically 'USD').","min_value":"Minimum USD amount for range products. Present only when is_range is true.","max_value":"Maximum USD amount for range products. Present only when is_range is true.","price_usdc":"Indicative USDC price for fixed products; 'variable' for range products. Final amount is confirmed in PAYMENT-REQUIRED.","country_code":"ISO country code for this product.","type":"Product family (e.g. 'Free Fire', 'Amazon.com').","product_value_required":"Set items[].product_value when is_range is true; omit otherwise."}},"createOrder":{"method":"POST","path":"/v1/orders","description":"Two-phase endpoint. First call (no PAYMENT-SIGNATURE) returns 402. Second call (with PAYMENT-SIGNATURE) returns 200.","request_body":{"email":{"type":"string","required":true,"description":"Contact email for the order."},"items":{"type":"array","required":true,"description":"List of products to purchase.","item_fields":{"product_id":{"type":"string","required":true,"description":"From catalog product_id."},"beneficiary_account":{"type":"string","required":true,"description":"Email or account to receive the voucher."},"product_value":{"type":"number","required":false,"description":"Required for range products. USD amount to load."}}},"callback_url":{"type":"string","required":false,"description":"Webhook URL for order state change notifications."}},"phase1_response":{"status":402,"header":"PAYMENT-REQUIRED","header_format":"base64url-encoded JSON","decoded_schema":{"x402Version":"integer","accepts":[{"scheme":"exact","network":"eip155:8453","maxAmountRequired":"USDC amount in atomic units (6 decimals)","asset":"USDC contract address on Base","extra":{"name":"USD Coin","version":"2","decimals":6,"_note":"name and version are the USDC EIP-712 domain fields the facilitator uses to reconstruct the signed digest."},"payTo":"Destination wallet address for this order session","description":"Human-readable amount and product description"}],"resource":"POST /v1/orders"}},"phase2_request_header":{"name":"PAYMENT-SIGNATURE","format":"base64url-encoded JSON","evm_schema":{"x402Version":2,"scheme":"exact","network":"eip155:8453","payload":{"signature":"EIP-712 signature hex string","authorization":{"from":"Payer wallet address","to":"payTo address from PAYMENT-REQUIRED","value":"maxAmountRequired from PAYMENT-REQUIRED","validAfter":"Unix timestamp (seconds) — use 0","validBefore":"Unix timestamp (seconds) — order expiry","nonce":"32-byte random hex"}}},"solana_schema":{"x402Version":2,"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","payload":{"transaction":"base64-encoded partially-signed Solana versioned transaction; SPL Transfer to ATA(owner=payTo, mint=asset) for amount = paymentRequirements.maxAmountRequired"}},"phase2_companion_headers":{"X-Session-Id":"Required for Solana, optional for EVM. Echo the value from the 402 response."}},"phase2_response":{"status":200,"fields":{"order_id":"CryptoRefills order ID.","status":"processing | completed | failed | expired","email":"Order contact email.","estimated_delivery_seconds":"Typical delivery time. Poll until completed.","poll_url":"GET path to check order status.","deliveries":"Array of delivery items (may be empty initially — poll for codes)."}}},"getOrder":{"method":"GET","path":"/v1/orders/{order_id}","description":"Poll for order status and voucher delivery. Poll every 5–10 seconds until status = 'completed' or 'failed'. Voucher fields appear inside deliveries[] once delivery_state = 'completed'.","response_fields":{"order_id":"Order identifier.","status":"processing | completed | failed | expired","deliveries":"Array of delivered items. Each item is populated only after CryptoRefills provisions the code; empty/pending items will fill in on subsequent polls.","delivery_fields":{"id":"Delivery identifier.","delivery_state":"pending | completed | failed","brand_name":"Product brand.","product_name":"Product name (often includes denomination, e.g. '100 Diamonds').","denomination":"Denomination descriptor when available (e.g. '100 Diamonds', '$25').","face_value":"Face value amount as a string.","currency":"Face value currency code (typically 'USD').","voucher_code":"Redemption code / PIN. Primary field for redemption.","pin_serial":"Serial number accompanying the voucher code (if issued).","security_code":"Extra activation code (if issued).","redeem_instructions":"HTML instructions from the brand for redeeming the code.","terms_and_conditions":"Brand terms & conditions, when provided.","url":"Redemption URL — falls back to barcode_image_url, qr_image_url, or a URL parsed out of redeem_instructions.","barcode_image_url":"Barcode image URL, when applicable.","qr_image_url":"QR image URL, when applicable.","beneficiary_account":"Email or account the voucher was sent to (confirms delivery target).","country_code":"ISO country code for the voucher.","delivery_type":"by_email | by_sms | inline","failure_reason":"Populated when delivery_state = 'failed'."}}}}}