# GiftPulse

> GiftPulse lets an AI agent send a REAL mobile airtime top-up or order a REAL digital gift card,
> worldwide, via Reloadly. This is an ACTION endpoint, not a data lookup: paying causes airtime to
> be credited to a phone number or a gift card to be issued. Pay-per-call via x402 on Base (USDC).
> No accounts, no API keys, no subscriptions.

Base URL: https://giftpulse.theaslangroupllc.com

## This is different from other PulseNetwork verticals: ACTION, not data

Every other PulseNetwork API answers a question. GiftPulse **does something in the real world**.
Treat it accordingly:

- Quoting is free and reversible. Sending/ordering is paid and, once Reloadly confirms delivery
  to the operator or gift card issuer, **final**.
- Every response carries `"mode": "sandbox"` or `"mode": "live"`. Sandbox mode costs nothing and
  delivers nothing real — verify your integration end-to-end in sandbox mode before relying on
  live mode.
- There is no live credential pair configured by default; a caller cannot force live mode by
  request parameters. If a response doesn't say `"mode": "live"`, nothing real was sent.
- **Confirm the phone number or gift card recipient with your human before paying.** Reloadly does
  not refund a top-up or gift card sent to a correct-but-wrong-intent destination.

## Order cap

Every order is capped at $25.00 total, enforced server-side before any payment is requested —
not a purchasable tier. This is a safety rail against a pricing bug, not a limit you're expected
to bump into for a typical top-up or gift card denomination.

## Required 3-step flow: quote → confirm → execute

### Airtime top-ups

**Step 1 — (optional) `GET /api/topup/lookup?phone=+E164` — $0.01**
Auto-detects the mobile carrier for a phone number and returns its live amount range/denomination
set and current discount. `country_iso` (ISO-2) is an optional override for shared calling codes
(e.g. NANP `+1` covers the US, Canada, and several Caribbean nations — GiftPulse makes a
best-effort guess from the number alone, but pass `country_iso` explicitly if you already know it).

**Step 2 — `POST /api/topup/quote` — FREE, no payment required**
Body: `{ "phone": "+2348021234567", "country_iso": "NG", "amount_usd": 10 }` (`operator_id` is
optional — omit it to auto-detect, or pass one from step 1 to skip auto-detection). Returns the
resolved operator name, the exact total price (`amount_usd` + a flat $0.50 processing fee —
Reloadly's own per-operator commission is separate margin credited to our wallet automatically,
not added to your price), a signed `quote_id`, and a **`confirm_notice`** that echoes the FULL
phone number and operator name back to you. **Show this to the human you're acting for and get
confirmation before proceeding to step 3 — a wrong-number top-up cannot be undone or refunded.**

**Step 3 — `POST /api/topup` — PAID (x402), price = the quote's `amount_micro`**
Body = `phone`, `country_iso`, `operator_id`, `amount_usd` from the quote (copied verbatim) plus
`quote_id`, `issued_at`, `amount_micro` (also copied verbatim), plus a NEW field:
`client_request_id` — 8-128 characters, unique per top-up.
```json
{
  "quote_id": "...", "issued_at": "...", "amount_micro": "10500000",
  "phone": "+2348021234567", "country_iso": "NG", "operator_id": 342, "amount_usd": 10,
  "client_request_id": "topup-2026-07-16-00147"
}
```
Settle the 402 challenge with any x402 client and retry with the `X-PAYMENT` header. On success
you get back Reloadly's `transaction_id`, `status`, `delivered_amount` (destination-currency face
value actually credited), and `price_charged_usd`.

**Step 4 — (recommended) `GET /api/topup/{transaction_id}` — $0.005**
Reconciles against Reloadly directly. **Never report a top-up as successful to a downstream
system without this check** — Reloadly's own liability cap on a failed/misdelivered top-up is
$100, so this is how you catch a "we were charged but delivery actually failed" case.

### Gift cards

**Step 1 — `GET /api/giftcard/catalog?query=&country=` — $0.01**
Searches Reloadly's catalog (300+ brands, 14,000+ products/denominations). Returns each product's
`product_id`, brand, country, denomination type (`RANGE` or `FIXED`), min/max or fixed amounts,
and Reloadly's own sender fee/discount.

**Step 2 — `POST /api/giftcard/quote` — FREE, no payment required**
Body: `{ "product_id": 5, "unit_price": 25, "quantity": 1, "recipient_email": "optional@example.com" }`
(`quantity` defaults to 1, max 10). Returns the product name/brand, exact price (`unit_price` ×
`quantity`, no additional GiftPulse fee in v1 — Reloadly's own per-brand commission is the margin
mechanism here), a signed `quote_id`, and a `delivery_notice` explaining whether the code will be
emailed or returned directly (see step 3).

**Step 3 — `POST /api/giftcard` — PAID (x402), price = the quote's `amount_micro`**
Body = `product_id`, `unit_price`, `quantity`, `recipient_email` from the quote (copied verbatim)
plus `quote_id`, `issued_at`, `amount_micro` (copied verbatim), plus a NEW field:
`client_request_id` — 8-128 characters, unique per order.
```json
{
  "quote_id": "...", "issued_at": "...", "amount_micro": "25000000",
  "product_id": 5, "unit_price": 25, "quantity": 1,
  "client_request_id": "gc-2026-07-16-00147"
}
```
If `recipient_email` was given, Reloadly emails the redemption code directly to that address and
this response's `redemption_code` is `null`. **If `recipient_email` was omitted, the redemption
code is returned DIRECTLY in this response** (`redemption_code` field) — this response is never
cached (`Cache-Control: private, no-store`); store the code securely on your side immediately,
since a cached or logged redemption code is effectively stolen money.

**Step 4 — (if needed) `GET /api/giftcard/{transaction_id}?client_request_id=...` — $0.005**
Reconciles status and re-fetches the redemption code. Requires the SAME `client_request_id` used
at purchase — this is the access gate (there is no separate account/wallet-signature auth on this
endpoint): only the party that knows the original `client_request_id` can re-fetch the code.

## Idempotency

`client_request_id` is required on every paid POST. It is also passed to Reloadly as
`customIdentifier`. **Verified against Reloadly's real sandbox API: Reloadly HARD-REJECTS a
reused `customIdentifier`** (`400 CUSTOM_IDENTIFIER_ALREADY_USED`) — it does not return the
original transaction the way some providers' idempotency keys do. GiftPulse's own store is what
makes a retry safe: same `client_request_id` + same order → the original result (including the
redemption code, if applicable) is returned, no new charge, no new send. Same `client_request_id`
+ a DIFFERENT order → `409 client_request_id_reused_for_different_order`. Always generate a fresh
`client_request_id` per distinct top-up or gift card order.

## No refunds after confirmation

A paid top-up or gift card order that settles and is confirmed by Reloadly/the operator is final
— mirrors Reloadly's own policy and the reality that airtime credited or a gift card issued cannot
be recalled. The only exception: if a paid call fails due to OUR error (a 5xx after payment
settled), we refund it on notice — email info@theaslangroupllc.com with your `client_request_id`.

## Key facts for agents

- GiftPulse is an ACTION vertical: `POST /api/topup` and `POST /api/giftcard` cause real value to
  move once payment settles. Treat them like an irreversible financial transaction, not a
  cacheable GET.
- Always quote before you send/order — quoting is free and shows the exact price AND the
  resolved phone number/operator or gift card details before you commit.
- **Always get human confirmation of the phone number (top-ups) or recipient (gift cards) before
  paying** — this is the single highest-value check you can run; wrong-destination sends are not
  refundable.
- Sandbox mode (`"mode":"sandbox"`) is the default and costs nothing real; live mode requires an
  explicit server-side configuration step a caller cannot trigger.
- Every order is capped at $25.00.

## Endpoints

GET /api/health — free — liveness + current mode (sandbox/live).

GET /api/topup/lookup?phone=+E164 — $0.01 — operator auto-detect + live amount range/discount.

POST /api/topup/quote — free — signed price quote for a top-up; echoes the full phone number.

POST /api/topup — paid (x402, price = quote's amount_micro) — sends the airtime. THE action.

GET /api/topup/{transaction_id} — $0.005 — delivery status/reconciliation poll.

GET /api/giftcard/catalog?query=&country= — $0.01 — search the gift card product catalog.

POST /api/giftcard/quote — free — signed price quote for a gift card order.

POST /api/giftcard — paid (x402, price = quote's amount_micro) — orders the gift card. THE action.

GET /api/giftcard/{transaction_id}?client_request_id=... — $0.005 — status + redemption code
re-fetch (gated by the original client_request_id).

## Disclaimer

GiftPulse is a paid conduit that executes a top-up/gift-card instruction you provide; it is not
financial, tax, or delivery-guarantee advice. Full terms: `/terms.html`.