{"_id":"@alphapay/react-native-checkout","_rev":"3-b01744c5174ee43b4c1cf49bff16e5d1","name":"@alphapay/react-native-checkout","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.1":{"name":"@alphapay/react-native-checkout","version":"1.0.1","keywords":["alphapay","react-native","checkout","payments","webview","hosted-checkout"],"author":{"name":"AlphaPay"},"license":"MIT","_id":"@alphapay/react-native-checkout@1.0.1","maintainers":[{"name":"alphapay","email":"alphapayoffice@gmail.com"}],"homepage":"https://github.com/alphapay/react-native-checkout#readme","bugs":{"url":"https://github.com/alphapay/react-native-checkout/issues"},"dist":{"shasum":"6d26b412099c75cda9f1aed180eacc69df6a9376","tarball":"https://registry.npmjs.org/@alphapay/react-native-checkout/-/react-native-checkout-1.0.1.tgz","fileCount":26,"integrity":"sha512-nQWTzG9P7OULJ7RZYdI8GCNIfiE5bYF2AuAjI+MWCSE2AQS2z8PVwPGaXdXwEHkoNzwE+54BMKICHP+K5sDaUg==","signatures":[{"sig":"MEUCIFH+2WIvkPGfzo4gRlQIErelOENoWKoH8I198urly8QaAiEArOdqERvLcahNeJ1RD3SfFuVm5OpmtzlFby5fPFbU12M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":40999},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"lint":"eslint \"src/**/*.{ts,tsx}\"","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"alphapay","email":"alphapayoffice@gmail.com"},"repository":{"url":"git+https://github.com/alphapay/react-native-checkout.git","type":"git"},"_npmVersion":"11.12.1","description":"React Native hosted checkout SDK for AlphaPay — WebView checkout with merchant-backend payment verification.","directories":{},"_nodeVersion":"22.12.0","_hasShrinkwrap":false,"devDependencies":{"react":"^18.3.1","eslint":"^8.57.1","typescript":"^5.6.3","@types/react":"^18.3.12","react-native":"^0.76.3","react-native-webview":"^13.12.2","@typescript-eslint/parser":"^8.15.0","eslint-plugin-react-hooks":"^5.0.0","@typescript-eslint/eslint-plugin":"^8.15.0"},"peerDependencies":{"react":">=17.0.0","react-native":">=0.71.0","react-native-webview":">=13.0.0"},"_npmOperationalInternal":{"tmp":"tmp/react-native-checkout_1.0.1_1774719194517_0.3975960538238701","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@alphapay/react-native-checkout","version":"1.0.2","keywords":["alphapay","react-native","checkout","payments","webview","hosted-checkout"],"author":{"name":"AlphaPay"},"license":"MIT","_id":"@alphapay/react-native-checkout@1.0.2","maintainers":[{"name":"alphapay","email":"alphapayoffice@gmail.com"}],"homepage":"https://github.com/alphapay/react-native-checkout#readme","bugs":{"url":"https://github.com/alphapay/react-native-checkout/issues"},"dist":{"shasum":"f1176b0be4518da81feb74e0bc490cb0650c0129","tarball":"https://registry.npmjs.org/@alphapay/react-native-checkout/-/react-native-checkout-1.0.2.tgz","fileCount":26,"integrity":"sha512-pLoBqOOewhra7+sBuUX3+bemW4ADnFxrHdXdLdVmIBWwhbvse65DGfga5cOXCuFqlU9Zt/f9atWwOIwOBC7LCw==","signatures":[{"sig":"MEQCICjAIaW68asaR3jTj0gQ5Pu33cWvaQ1FF3RbjLoBoy01AiBMQlzQ9vh2k6tLXzeH4fgBp3sScHNniYoRtRW9OQJSFA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51437},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"lint":"eslint \"src/**/*.{ts,tsx}\"","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"alphapay","email":"alphapayoffice@gmail.com"},"repository":{"url":"git+https://github.com/alphapay/react-native-checkout.git","type":"git"},"_npmVersion":"11.12.1","description":"React Native hosted checkout SDK for AlphaPay — WebView checkout with merchant-backend payment verification.","directories":{},"_nodeVersion":"22.12.0","_hasShrinkwrap":false,"devDependencies":{"react":"^18.3.1","eslint":"^8.57.1","typescript":"^5.6.3","@types/react":"^18.3.12","react-native":"^0.76.3","react-native-webview":"^13.12.2","@typescript-eslint/parser":"^8.15.0","eslint-plugin-react-hooks":"^5.0.0","@typescript-eslint/eslint-plugin":"^8.15.0"},"peerDependencies":{"react":">=17.0.0","react-native":">=0.71.0","react-native-webview":">=13.0.0"},"_npmOperationalInternal":{"tmp":"tmp/react-native-checkout_1.0.2_1774720376588_0.3156465497969132","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@alphapay/react-native-checkout","version":"1.0.3","description":"React Native hosted checkout SDK for AlphaPay — WebView checkout with merchant-backend payment verification.","license":"MIT","author":{"name":"AlphaPay"},"repository":{"type":"git","url":"git+https://github.com/alphapay/react-native-checkout.git"},"keywords":["alphapay","react-native","checkout","payments","webview","hosted-checkout"],"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","lint":"eslint \"src/**/*.{ts,tsx}\"","prepublishOnly":"npm run clean && npm run build"},"peerDependencies":{"react":">=17.0.0","react-native":">=0.71.0","react-native-webview":">=13.0.0"},"devDependencies":{"@types/react":"^18.3.12","@typescript-eslint/eslint-plugin":"^8.15.0","@typescript-eslint/parser":"^8.15.0","eslint":"^8.57.1","eslint-plugin-react-hooks":"^5.0.0","react":"^18.3.1","react-native":"^0.76.3","react-native-webview":"^13.12.2","typescript":"^5.6.3"},"_id":"@alphapay/react-native-checkout@1.0.3","bugs":{"url":"https://github.com/alphapay/react-native-checkout/issues"},"homepage":"https://github.com/alphapay/react-native-checkout#readme","_nodeVersion":"22.12.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-On0h8lhI2y3QdW327OsvB1rcmffbhZjNeymIiKcPgcHsNyzYgI/HT09pm+X9MEu/O58rUxu+lRiLSWjw77BySw==","shasum":"4b3a12f09f7d2220dda404680a997084165cd9ff","tarball":"https://registry.npmjs.org/@alphapay/react-native-checkout/-/react-native-checkout-1.0.3.tgz","fileCount":26,"unpackedSize":51419,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDcTDFwcFjbaRgQIzlw6bTDdVs1Pym29WaciQ5i7e7sKQIhANi1U/21dV8/NLd3N7Prlf0h22bU7g/y0k3t7B/ZxW40"}]},"_npmUser":{"name":"alphapay","email":"alphapayoffice@gmail.com"},"directories":{},"maintainers":[{"name":"alphapay","email":"alphapayoffice@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/react-native-checkout_1.0.3_1774720527928_0.17263286722069227"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-28T17:33:14.452Z","modified":"2026-03-28T17:55:28.200Z","1.0.1":"2026-03-28T17:33:14.668Z","1.0.2":"2026-03-28T17:52:56.731Z","1.0.3":"2026-03-28T17:55:28.079Z"},"bugs":{"url":"https://github.com/alphapay/react-native-checkout/issues"},"author":{"name":"AlphaPay"},"license":"MIT","homepage":"https://github.com/alphapay/react-native-checkout#readme","keywords":["alphapay","react-native","checkout","payments","webview","hosted-checkout"],"repository":{"type":"git","url":"git+https://github.com/alphapay/react-native-checkout.git"},"description":"React Native hosted checkout SDK for AlphaPay — WebView checkout with merchant-backend payment verification.","maintainers":[{"name":"alphapay","email":"alphapayoffice@gmail.com"}],"readme":"# @alphapay/react-native-checkout\n\nProduction-ready React Native **hosted checkout** for AlphaPay. The SDK opens your merchant-generated `checkoutUrl` in a full-screen modal [`WebView`](https://github.com/react-native-webview/react-native-webview), detects when the customer is redirected to your **callback URL**, then calls **your** `verifyPayment(callbackUrl)` so your backend can confirm the final payment status with AlphaPay.\n\n---\n\n## Table of contents\n\n1. [Overview](#overview)\n2. [Requirements](#requirements)\n3. [Installation](#installation)\n4. [Native setup (WebView)](#native-setup-webview)\n5. [Quick start](#quick-start)\n6. [Provider and hook](#provider-and-hook)\n7. [`openCheckout` parameters](#opencheckout-parameters)\n8. [`verifyPayment` contract](#verifypayment-contract)\n9. [Payment status shape (`AlphaPayPaymentStatus`)](#payment-status-shape-alphapaypaymentstatus)\n10. [Checkout result (`AlphaPayCheckoutResult`)](#checkout-result-alphapaycheckoutresult)\n11. [Handling results in TypeScript](#handling-results-in-typescript)\n12. [Additional exports](#additional-exports)\n13. [End-to-end flow](#end-to-end-flow)\n14. [Callback URL and prefix matching](#callback-url-and-prefix-matching)\n15. [Behavior notes](#behavior-notes)\n16. [Logging](#logging)\n17. [Security](#security)\n18. [Backend integration](#backend-integration)\n19. [Troubleshooting](#troubleshooting)\n20. [Example app](#example-app)\n21. [License](#license)\n\n---\n\n## Overview\n\n### What this SDK does\n\n- Presents AlphaPay’s hosted payment page inside a **modal** with a **full-screen** `WebView`.\n- Detects navigation to a URL whose string **starts with** your configured `callbackUrlPrefix` (see [Callback URL and prefix matching](#callback-url-and-prefix-matching)).\n- Shows **“Verifying payment…”** while `verifyPayment` runs.\n- Resolves `openCheckout` with a **typed** [`AlphaPayCheckoutResult`](#checkout-result-alphapaycheckoutresult): `success`, `failed`, or `cancelled`.\n- **`openCheckout` never rejects** — failures are represented as `status: 'failed'`.\n\n### What this SDK does **not** do\n\n- It does **not** store or use AlphaPay **secret** API keys in the app.\n- It does **not** call AlphaPay **invoice/generate** or **payment status** APIs from the device.\n- It does **not** treat a redirect alone as proof of payment — your **backend** must verify.\n\n---\n\n## Requirements\n\n- **React** ≥ 17\n- **React Native** ≥ 0.71\n- **react-native-webview** ≥ 13\n\n---\n\n## Installation\n\n```bash\nnpm install @alphapay/react-native-checkout react-native-webview\n```\n\n```bash\nyarn add @alphapay/react-native-checkout react-native-webview\n```\n\n```bash\npnpm add @alphapay/react-native-checkout react-native-webview\n```\n\nPeer dependencies (`react`, `react-native`, `react-native-webview`) must be present in your app; npm/yarn will warn if versions are missing or incompatible.\n\n---\n\n## Native setup (WebView)\n\nFollow the official [**react-native-webview** installation guide](https://github.com/react-native-webview/react-native-webview/blob/master/docs/Getting-Started.md) for your toolchain:\n\n- **Expo**: often `npx expo install react-native-webview` and configure plugins if needed.\n- **Bare React Native**: install the pod on iOS (`cd ios && pod install`) and rebuild both platforms.\n\nIf the WebView does not appear or crashes on first run, fix WebView/native setup before debugging this SDK.\n\n---\n\n## Quick start\n\n1. **Wrap** your app (or the subtree that needs checkout) with `AlphaPayCheckoutProvider`.\n2. Call **`useAlphaPayCheckout()`** to get **`openCheckout`**.\n3. From your pay button, **`await openCheckout({ ... })`** with `checkoutUrl`, `callbackUrlPrefix`, and `verifyPayment`.\n4. Switch on **`result.status`** (`success` | `failed` | `cancelled`).\n\nMinimal example:\n\n```tsx\nimport {\n  AlphaPayCheckoutProvider,\n  useAlphaPayCheckout,\n} from '@alphapay/react-native-checkout';\n\nfunction PayScreen() {\n  const { openCheckout } = useAlphaPayCheckout();\n\n  const pay = async () => {\n    const result = await openCheckout({\n      checkoutUrl: 'https://pay.alphapay.ae/your-invoice-path',\n      callbackUrlPrefix: 'myapp://alphapay/callback',\n      verifyPayment: async (callbackUrl) => {\n        const res = await fetch('https://api.mymerchant.com/v1/payments/verify', {\n          method: 'POST',\n          headers: { 'Content-Type': 'application/json', Authorization: 'Bearer <user-token>' },\n          body: JSON.stringify({ callbackUrl }),\n        });\n        if (!res.ok) throw new Error(`Verify HTTP ${res.status}`);\n        return res.json();\n      },\n    });\n\n    if (result.status === 'success') {\n      // Use result.data, result.callbackUrl\n    } else if (result.status === 'failed') {\n      // Use result.message, result.data, result.callbackUrl\n    } else {\n      // cancelled\n    }\n  };\n\n  return <Button title=\"Pay\" onPress={pay} />;\n}\n\nexport default function App() {\n  return (\n    <AlphaPayCheckoutProvider>\n      <PayScreen />\n    </AlphaPayCheckoutProvider>\n  );\n}\n```\n\n---\n\n## Provider and hook\n\n### `AlphaPayCheckoutProvider`\n\nRenders the checkout **modal** and holds internal state for the current session. Place it **above** any component that calls `useAlphaPayCheckout`.\n\n```tsx\nimport { AlphaPayCheckoutProvider } from '@alphapay/react-native-checkout';\n\n<AlphaPayCheckoutProvider>{children}</AlphaPayCheckoutProvider>\n```\n\nProps:\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `children` | `React.ReactNode` | Your app tree |\n\n### `useAlphaPayCheckout()`\n\nReturns:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `openCheckout` | `(params: AlphaPayCheckoutParams) => Promise<AlphaPayCheckoutResult>` | Opens the modal and runs the flow |\n\n**Important:** `useAlphaPayCheckout()` **throws** if used outside `AlphaPayCheckoutProvider`. Only call it from components under the provider.\n\n---\n\n## `openCheckout` parameters\n\n`AlphaPayCheckoutParams`:\n\n| Property | Type | Required | Description |\n|----------|------|----------|-------------|\n| `checkoutUrl` | `string` | Yes | Hosted payment URL returned by **your** backend after creating an invoice (AlphaPay hosted page). |\n| `callbackUrlPrefix` | `string` | Yes | Prefix used to detect the return URL. Matching is **case-insensitive** and uses **string prefix** (see [Callback URL](#callback-url-and-prefix-matching)). |\n| `verifyPayment` | `(callbackUrl: string) => Promise<AlphaPayPaymentStatus>` | Yes | Called **once** when a matching callback URL is seen. Must call **your** backend, which talks to AlphaPay with **server** credentials. |\n| `headers` | `Record<string, string>` | No | Optional HTTP headers for the **initial** `WebView` request to `checkoutUrl` (e.g. custom `User-Agent`). |\n| `showLogs` | `boolean` | No | If `true`, logs lines prefixed with `[AlphaPayCheckout]` to the console (useful in development). |\n\n### Concurrent sessions\n\nOnly **one** checkout session can be active at a time per provider. If `openCheckout` is called again while a session is already open, the second call **resolves immediately** with:\n\n```ts\n{ status: 'failed', message: 'Another checkout session is already in progress.' }\n```\n\n---\n\n## `verifyPayment` contract\n\nSignature:\n\n```ts\nverifyPayment: (callbackUrl: string) => Promise<AlphaPayPaymentStatus>;\n```\n\n- **`callbackUrl`**: The full URL the WebView attempted to load that matched `callbackUrlPrefix`. Your backend can parse query parameters (e.g. invoice id) or pass the full string to your API.\n- **Return value**: A `Promise` that resolves to [`AlphaPayPaymentStatus`](#payment-status-shape-alphapaypaymentstatus).\n- **Errors**: If the promise **rejects** or throws, the SDK treats the outcome as **`failed`** with a `message` derived from the error. The SDK does **not** surface uncaught exceptions from this function to the global handler for the checkout flow.\n\n### Pending payments\n\nIf you return `{ pending: true, ... }`, the SDK currently resolves checkout as **`failed`** with an explanatory `message` (not `success`). You may implement polling on your backend and/or app separately; see [Pending payments](#pending-payments-note) below.\n\n---\n\n## Payment status shape (`AlphaPayPaymentStatus`)\n\nYour backend should return a JSON object compatible with:\n\n```ts\nexport type AlphaPayPaymentStatus = {\n  success: boolean;\n  pending?: boolean;\n  invoiceId?: string;\n  invoiceReference?: string;\n  invoiceStatus?: string;\n  paymentId?: string;\n  transactionId?: string;\n  transactionStatus?: string;\n  paymentGateway?: string;\n  paidCurrency?: string;\n  paidCurrencyValue?: number;\n  cardBrand?: string;\n  cardIssuer?: string;\n  issuerCountry?: string;\n  cardMaskedNumber?: string;\n  customerName?: string;\n  customerEmail?: string;\n  message?: string;\n  raw?: unknown;\n};\n```\n\n| Field | Meaning |\n|-------|--------|\n| `success` | **Required** logical outcome from your verification. `true` means paid/confirmed per your backend rules. |\n| `pending` | If `true`, SDK treats checkout as **failed** (with message); use when status is not final. |\n| `invoiceId`, `invoiceReference`, … | Optional metadata for UI or analytics. |\n| `message` | Human-readable message; may appear in `failed` results. |\n| `raw` | Optional passthrough for debugging or future fields. |\n\n---\n\n## Checkout result (`AlphaPayCheckoutResult`)\n\nDiscriminated union on `status`:\n\n### `success`\n\n```ts\n{\n  status: 'success';\n  data: AlphaPayPaymentStatus;\n  callbackUrl: string;\n}\n```\n\n### `failed`\n\n```ts\n{\n  status: 'failed';\n  data?: AlphaPayPaymentStatus;\n  callbackUrl?: string;\n  message?: string;\n}\n```\n\nTypical causes:\n\n- WebView load or HTTP error\n- `verifyPayment` threw or rejected\n- `verifyPayment` returned `success: false`\n- `verifyPayment` returned `pending: true`\n- Second `openCheckout` while a session is active\n\n### `cancelled`\n\n```ts\n{\n  status: 'cancelled';\n  callbackUrl?: string;\n}\n```\n\nUser closed the modal **before** a terminal verification outcome. If the user closes **during** verification, the SDK still resolves **`cancelled`** and ignores late verification results.\n\n---\n\n## Handling results in TypeScript\n\nUse `status` as a discriminant:\n\n```tsx\nconst result = await openCheckout({ /* ... */ });\n\nswitch (result.status) {\n  case 'success':\n    console.log(result.data.invoiceId, result.callbackUrl);\n    break;\n  case 'failed':\n    console.error(result.message, result.data, result.callbackUrl);\n    break;\n  case 'cancelled':\n    console.log('User dismissed checkout');\n    break;\n}\n```\n\nOr narrow with `if`:\n\n```tsx\nif (result.status === 'success') {\n  const paid = result.data;\n  const url = result.callbackUrl;\n}\n```\n\n---\n\n## Additional exports\n\n### URL helpers (`utils/url`)\n\n| Function | Description |\n|----------|-------------|\n| `isMatchingCallbackUrl(url, callbackUrlPrefix): boolean` | `true` if `url` starts with `prefix`, compared **case-insensitively**. |\n| `getQueryParam(url, key): string \\| undefined` | Parses `url` with the `URL` API; returns a query param or `undefined` if invalid. |\n\nUseful if you build or parse callback URLs outside the modal (e.g. future deep-link handlers).\n\n### `logAlphaPay(showLogs, ...args)`\n\nInternal-style logger: prints `[AlphaPayCheckout]` only when `showLogs` is `true`. Normally you only set `showLogs` on `openCheckout`; exporting this is optional for tests or custom tooling.\n\n### `CheckoutModal`\n\nLow-level modal component used by the provider. Re-exported for advanced cases; most apps should use only `AlphaPayCheckoutProvider` and `useAlphaPayCheckout`.\n\n---\n\n## End-to-end flow\n\n1. **App → your backend** — Create invoice using AlphaPay **server-side** APIs.\n2. **Backend → app** — Returns **`checkoutUrl`** (and optional ids).\n3. **App → SDK** — `openCheckout({ checkoutUrl, callbackUrlPrefix, verifyPayment })`.\n4. **SDK → WebView** — Loads **`checkoutUrl`** (hosted AlphaPay page).\n5. **Customer** — Completes payment on AlphaPay.\n6. **AlphaPay → WebView** — Redirects to your **callback URL** (must match `callbackUrlPrefix`).\n7. **SDK** — Detects prefix match, shows **Verifying payment…**, calls **`verifyPayment(fullCallbackUrl)`** once.\n8. **App → your backend** — `verifyPayment` typically **POST**s `callbackUrl` (or parsed params) with your app auth.\n9. **Backend → AlphaPay** — Status / verify APIs using **secret** credentials (never in the app).\n10. **Backend → app** — JSON matching **`AlphaPayPaymentStatus`**.\n11. **SDK → app** — `openCheckout` **resolves** with **`AlphaPayCheckoutResult`** (`success` | `failed` | `cancelled`).\n\n---\n\n## Callback URL and prefix matching\n\n- Matching uses **`isMatchingCallbackUrl`**:  \n  `url.toLowerCase().startsWith(callbackUrlPrefix.toLowerCase())`.\n- Configure `callbackUrlPrefix` to match what AlphaPay redirects to (e.g. `https://merchant.example.com/pay/return` or `myapp://alphapay/callback`).\n- Use a **stable prefix** that only your return URLs use, so normal AlphaPay pages do not false-trigger.\n\n---\n\n## Behavior notes\n\n| Topic | Behavior |\n|-------|----------|\n| **Initial load** | Loading indicator until the page finishes loading; overlay also shows **Verifying payment…** during `verifyPayment`. |\n| **Callback detection** | Both `onNavigationStateChange` and `onShouldStartLoadWithRequest` inspect URLs; duplicate handling is guarded so **`verifyPayment` runs once** per session. |\n| **Custom schemes** | For callback URLs that are not `http(s)`, the WebView may not navigate successfully; the SDK intercepts the request and still runs `verifyPayment` with the callback URL. |\n| **WebView errors** | Load errors and HTTP errors resolve **`failed`** with a message. |\n| **Redirect as proof** | The SDK does **not** assume success on redirect; only **`verifyPayment`** outcome drives `success`. |\n\n### Pending payments note\n\nIf you need to support long-running or async settlement, combine:\n\n- This SDK’s **`failed` + pending message**, and/or  \n- Polling your backend after checkout closes, and/or  \n- **Webhooks** as the source of truth for fulfillment.\n\n---\n\n## Logging\n\nWhen `showLogs: true`, the SDK logs lines starting with **`[AlphaPayCheckout]`** (e.g. checkout opened, callback matched, errors, user closed). Disable in production unless you need diagnostics.\n\n---\n\n## Security\n\n| Do | Don’t |\n|----|--------|\n| Create invoices and call AlphaPay APIs **only on your server** | Put AlphaPay **secret** keys in the mobile app |\n| Return **`checkoutUrl`** to the app over HTTPS | Call **`invoice/generate`** or status APIs **from the app** |\n| Verify payment server-side and return a normalized status to the app | Trust redirect alone as proof of payment |\n| Use **webhooks** for fulfillment decisions when possible | Log sensitive payment data in production |\n\n---\n\n## Backend integration\n\n### 1. Create invoice (app → your API)\n\nYour mobile app calls **your** endpoint. Your server uses AlphaPay credentials to create an invoice and returns at least **`checkoutUrl`** (and optional ids).\n\nExample response your app might receive:\n\n```json\n{\n  \"checkoutUrl\": \"https://pay.alphapay.ae/1-84256-1774717209325\",\n  \"invoiceId\": \"1-84256-1774717209325\",\n  \"requestId\": \"689fa795-1729-4a2c-bfd0-f3b75ca89833\"\n}\n```\n\n### 2. Verify payment (SDK → your API via `verifyPayment`)\n\nAfter redirect, the SDK calls **`verifyPayment(fullCallbackUrl)`**. Your app should **POST** to your backend (with your user session / app token as appropriate). Your backend:\n\n1. Parses `callbackUrl` or related ids.\n2. Calls AlphaPay **status** APIs with **server** secrets.\n3. Returns JSON matching **`AlphaPayPaymentStatus`**.\n\nExample normalized verify response:\n\n```json\n{\n  \"success\": true,\n  \"invoiceId\": \"1040-51-17652502693\",\n  \"invoiceReference\": \"2ce5edf7e0bf4984b133ea1773a86a03\",\n  \"invoiceStatus\": \"Paid\",\n  \"paymentId\": \"a0cfe47e-7a20-4369-ad67-5a73f2025561\",\n  \"transactionId\": \"251209132819804\",\n  \"transactionStatus\": \"Success\",\n  \"paymentGateway\": \"Debit/Credit Cards\",\n  \"paidCurrency\": \"AED\",\n  \"paidCurrencyValue\": 9127.94,\n  \"cardBrand\": \"VISA\",\n  \"cardIssuer\": \"CREDIT LIBANAIS S.A.L.\",\n  \"issuerCountry\": \"LEBANON\",\n  \"cardMaskedNumber\": \"5366078******4046\",\n  \"customerName\": \"john doe\",\n  \"customerEmail\": \"john@gmail.com\",\n  \"message\": \"Operation Completed Successfully\"\n}\n```\n\n### Recommended architecture\n\n1. **Mobile app** — Gets `checkoutUrl` from your API; runs this SDK; calls your verify endpoint from `verifyPayment`.\n2. **Your backend** — Owns AlphaPay credentials, invoice creation, status checks, and optional webhook handlers.\n3. **Webhooks** — Use AlphaPay webhooks as the **authoritative** signal for shipping, entitlements, and reconciliation; use in-app verification for UX feedback.\n\n---\n\n## Troubleshooting\n\n| Issue | What to check |\n|-------|----------------|\n| **`useAlphaPayCheckout` throws** | Ensure a parent **`AlphaPayCheckoutProvider`** wraps your screen. |\n| **Checkout never calls `verifyPayment`** | **`callbackUrlPrefix`** must match the **start** of the redirect URL AlphaPay uses (scheme + path). Align with AlphaPay dashboard / integration docs. |\n| **`verifyPayment` always fails** | Network, auth token, backend route, and JSON shape (`success` boolean). |\n| **Blank WebView** | SSL/proxy, wrong `checkoutUrl`, or WebView not linked (revisit [Native setup](#native-setup-webview)). |\n| **Second pay does nothing / instant failed** | Only one session at a time; wait until the first `openCheckout` promise settles before opening again. |\n\n---\n\n## Example app\n\nThe [`example/`](./example/) folder contains a minimal **Expo** app: a **Pay** button, mocked `verifyPayment`, and on-screen JSON result. It uses a small **`data:`** HTML page that redirects to a demo callback URL so you can run the flow without a live AlphaPay session.\n\n```bash\ncd example\nnpm install\nnpx expo start\n```\n\nUse a real **`checkoutUrl`** from your backend when moving to staging/production.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}