# 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** / **Confirm purchase** |
| Onramp / Privy | “Add money to your wallet” |
| redirectUrl | Just send them to the hosted page we return |

**Best single button for most shops:** **Pay with card**  
Under the hood that runs Fund (card → wallet), then your site calls Pay.

Optional second button: **Pay from wallet** (if they already funded).

---

## Merchant flow (2 steps)

```
1) FUND  — POST /api/crypto/fund
           Customer is redirected to redirectUrl (hosted Fund page + card widget)
           Order status: Pending → Processing when wallet is funded

2) PAY   — POST /api/crypto/pay
           After customer returns to your checkout, you settle to your merchant wallet
           Order status: Processing → Completed
```

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

---

## Auth (every Fund / Pay / Balance call)

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 (open in browser / redirect)
- `orderId` — platform order id (save for Pay)
- `fundId` — funding session id

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

---

## 2) After funding

Customer finishes the card widget. When status is funded, the Fund page shows  
**Return to checkout & Pay** → your `returnUrl`.

On that page, call **Pay**.

---

## 3) Pay

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

```json
{
  "email": "customer@example.com",
  "amount": 25,
  "orderId": 16362,
  "merchantOrderId": "YOUR-ORDER-123"
}
```

Prefer platform `orderId` from Fund. `merchantOrderId` is a fallback.

---

## 4) Balance (optional)

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

Use this to show “Pay from wallet” only when balance ≥ order amount.

---

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

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

We POST JSON when Fund/Pay status changes:

| Event | When |
|-------|------|
| `fund.pending` | Fund session created |
| `fund.processing` | Wallet funded (order → Processing) |
| `fund.failed` | Funding failed or cancelled |
| `pay.completed` | Pay settled to your wallet |
| `pay.failed` | Pay failed (e.g. insufficient balance) |

Headers:

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

Example body:

```json
{
  "event": "fund.processing",
  "fundId": "fund_…",
  "payId": null,
  "orderId": 16362,
  "merchantOrderId": "YOUR-ORDER-123",
  "email": "customer@example.com",
  "amount": 25.00,
  "currency": "USD",
  "status": "completed",
  "orderStatus": "Processing",
  "errorMessage": null,
  "txHash": "…",
  "remainingBalanceUsdc": null,
  "timestamp": "2026-09-12T05:00:00Z"
}
```

Use **Send test IPN** on the API Keys page to POST a sample `fund.pending`. Outbound IPNs and inbound onramp webhooks are stored in **Integration Logs** (`MerchantIpn` / `Onramper` / `Stripe`).

---

## Order status in merchant Transaction History

| Status | Meaning |
|--------|---------|
| Pending | Awaiting funding |
| Processing | Wallet funded — waiting for Pay |
| Completed | Paid to merchant |

---

## Pseudocode

```
on "Pay with card":
  fund = api.fund(email, amount, yourOrderId, returnUrl=yourCompletePage)
  redirect browser to fund.redirectUrl

on IPN fund.processing (or yourCompletePage):
  pay = api.pay(email, amount, orderId=fund.orderId)
  show success
```

---

## Links

- Demo checkout: https://ikash.biz/demo/checkout  
- Swagger: https://api.ikash.biz/onramper/swagger  
- Merchant portal: https://ikash.biz/Merchant/Index/Index  
- API keys: Merchant dashboard → API Keys  

Questions: info@ikash.biz