# iKash Crypto Checkout — Merchant Integration Guide

**Live demo:** https://ikash.biz/demo/checkout  
**API docs:** https://api.ikash.biz/onramper/swagger  

This guide is for merchants who want customers to **add money with a card**, then **pay your store** from a wallet. Settlement is immediate. Crypto Pay does not reverse like a card chargeback.

---

## What the customer sees (recommended labels)

| Avoid (too technical) | Prefer |
|-----------------------|--------|
| Fund / Pay / USDC | **Pay with card** |
| Onramper / Privy | “Add money” / “Confirm payment” |
| redirectUrl | Just send them to the hosted page we return |

**Best single button for most shops:** **Pay with card**  
Under the hood: Fund (card → wallet) → hosted **Confirm payment** (email code) → USDC to you.

---

## Merchant flow (Fund only)

```
1) FUND  — POST /api/crypto/fund
           Redirect customer to redirectUrl (hosted Fund + Stripe card/KYC)
           Order: Pending → Processing when wallet is funded

2) CUSTOMER — After Stripe, auto-continues to ConfirmPay on ikash.biz
           Enters email OTP to authorize, then pays the merchant
           Order: Processing → Completed
           You receive IPN pay.completed

3) returnUrl — Customer returns to your site (we append payId, orderId, status)
```

**Do not call a Pay API** for this checkout. Wait for IPN (or poll order status).

You never hold card data. Stripe handles the card UI on our Fund page.

---

## Auth (Fund / Balance)

Headers:

- `X-Api-Key` — your public key (`pk_test_…` / `pk_live_…`)
- `X-Timestamp` — Unix seconds (within 5 minutes)
- `X-Signature` — lowercase hex HMAC-SHA256 of:

```
{timestamp}\n{METHOD}\n{pathWithQuery}\n{rawBody}
```

Secret = your `sk_test_…` / `sk_live_…`  
GET Balance: body is empty string `""`.

Helper script: `scripts/sign-and-call-onramper.sh`

---

## 1) Fund

`POST https://api.ikash.biz/api/crypto/fund`

```json
{
  "email": "customer@example.com",
  "amount": 25,
  "currency": "USD",
  "orderId": "YOUR-ORDER-123",
  "returnUrl": "https://yoursite.com/checkout/complete"
}
```

Important response fields:

- `redirectUrl` — send the customer here (Fund + Stripe)
- `payConfirmUrl` — hosted confirm page (used after funding; customer is sent here automatically)
- `orderId` — platform order id
- `fundId` — funding session id

Network is fixed by the platform (default Polygon). Do not send a `network` field.

---

## 2) After funding

Customer finishes Stripe. Our Fund page sends them to **Confirm payment**:

1. Email one-time code (authorize)
2. **Pay merchant** — USDC settles to your wallet
3. Redirect to your `returnUrl` with `payId`, `orderId`, `status=completed`

---

## 3) Balance (optional)

`GET https://api.ikash.biz/api/crypto/balance?email=customer@example.com`

Use this to decide whether to show “already has wallet balance” UX in your own UI.

---

## 4) Merchant IPN (signed callbacks — no polling)

Configure **IPN URL** + **IPN secret** under Merchant → API Keys (same UI as card payments).

Events include:

- `fund.pending` / `fund.processing` / `fund.failed`
- `pay.completed` / `pay.failed` / `pay.refunded`

Headers:

- `X-Ipn-Timestamp`
- `X-Ipn-Signature` — lowercase hex HMAC-SHA256 of `{timestamp}\n{body}` with your IPN secret

Use **Send test IPN** on the API Keys page. Outbound IPNs are in Integration Logs.

---

## 5) Refunds

Merchants refund completed on-chain pays from **Transaction History** (amount + notes), or via your ops process. Listen for `pay.refunded`.

---

## Pseudocode

```
fund = POST /api/crypto/fund { email, amount, currency, orderId, returnUrl }
redirect customer → fund.redirectUrl

# customer: Stripe → ConfirmPay (OTP) → Pay
# your server:
on IPN pay.completed:
  mark order paid / fulfill
```

---

## Links

- Demo checkout: https://ikash.biz/demo/checkout  
- Swagger: https://api.ikash.biz/onramper/swagger