JewelPay Integrator Documentation

1. Open the Developers page and register as a JewelPay Integrator.
2. Upload your KYC identity information, ID front and selfie in Settings before registering or using the API.
3. Create an application. It starts in Sandbox with its own Integration ID and Encryption Key.
4. Build and test against the sandbox values below — no real money moves.
5. Upload your signed contract. Live access requires JewelForex countersigning and review; approved payout limits are a separate requirement.

Every request carries two headers. Keep the Encryption Key secret — anyone holding it can request money through your application.

X-Integration-Id: JPI_XXXXXXXXXXXX
X-Encryption-Key: jpk_live_••••••••••••••••

Rotate the pair from your dashboard at any time; the old pair stops working immediately.

POST https://jewelforex.app/api/public/jewelpay/prompt
Content-Type: application/json
X-Integration-Id: JPI_XXXXXXXXXXXX
X-Encryption-Key: jpk_live_...

{
  "payer": "ryan@example.com",     // JewelForex username or email
  "amount_cents": 2500,             // $25.00
  "description": "Order #10422",
  "idempotency_key": "subscription-10422"
}

{
  "ok": true,
  "prompt": {
    "reference": "JPP-LZ8K2M-4QT7",
    "status": "pending",
    "amount_cents": 2500,
    "payer_fee_cents": 175,
    "net_cents": 2500,
    "expires_at": "2026-01-01T12:05:00.000Z",
    "sandbox": false
  }
}

The payer approves the prompt with their existing payment controls. It expires after five minutes. A retry must use the same key and details; changed details return a conflict. Live API credentials cannot create test confirmations.

GET https://jewelforex.app/api/public/jewelpay/prompt?reference=JPP-LZ8K2M-4QT7
X-Integration-Id: JPI_XXXXXXXXXXXX
X-Encryption-Key: jpk_live_...

Statuses are pending, paid, cancelled and expired. A paid prompt returns a Transaction ID (the payer's reference) and a Payment ID (yours).

1. Your server (never the browser) holds the Integration ID and Encryption Key.
2. Customer chooses “Pay with JewelForex” and enters their JewelForex username or email.
3. Server calls POST /api/public/jewelpay/prompt with a unique idempotency_key per order (e.g. sub-USERID-PLAN-PERIOD).
4. Show “Approve the request in your JewelForex app” and poll GET /api/public/jewelpay/prompt?reference=… every 3–5 seconds for up to five minutes.
5. Activate the subscription only when status is paid; store the Payment ID as your receipt reference. On cancelled or expired, grant nothing and let the customer retry.
6. Both sides get a receipt: the payer in JewelForex, and you via the Payment ID.

Your app must be Live, its owner must have completed KYC, and the payer must have a JewelForex account. Sandbox keys only work with sandbox test values. This describes JewelForex’s supported API; PlanetChat or any other partner must implement and enable its own checkout before customers can use it.

JewelPay charges 5% + $0.50 per payment, carried by the payer by default. Collected funds sit in your application balance; settle them into your JewelForex wallet from the dashboard, then cash out through your country's rails.

For paying your own users — for example creator cash-outs from PlanetChat into a JewelForex Wallet — submit a funded, automatic wallet credit. Creators enter their JewelForex username, full name and address; they do not need to sign into the receiving wallet again. Identity checks on the receiving account still apply. Automatic payouts remain disabled until transaction and daily limits are approved for your application.

POST https://jewelforex.app/api/public/jewelpay/payout
X-Integration-Id: JPI_XXXXXXXXXXXX
X-Encryption-Key: jpk_live_...

{
  "recipient": "creator_username",     // exact JewelForex username
  "recipient_name": "Creator Full Name",
  "recipient_address": "Street, city, country",
  "amount_cents": 5000,                 // $50.00
  "note": "PlanetChat creator cash-out #1042",
  "idempotency_key": "planetchat-cashout-1042"
}

Send the same idempotency_key on a retry and you get the original request back instead of a duplicate. Changed details with the same key return HTTP 409. Your application must be Live and hold enough available balance. The credit, application debit, receipt and audit entry are committed together, or none are. Read status with GET /api/public/jewelpay/payout?id=REQUEST_UUID; read the shared receipt withGET /api/public/jewelpay/payout?receipt=RECEIPT_UUID, using the same headers.

Only a returned paid status confirms the wallet credit. PlanetChat must store the receipt reference before marking earnings paid, and must not debit earnings twice on retries. No receipt or payment is simulated. The API reports limit, identity and insufficient-funds failures explicitly.

Subscription access must similarly be granted only after reading paid with sandbox: false from the authenticated payment-status endpoint. Never trust a browser redirect as payment proof.

The payer’s Tap & Pay page supports QR links, request QRs and compatible NFC tags. Scanning or tapping only fills details; it does not approve a debit. These tools do not replace integration authentication or the authenticated payment-status check.

Automatic weekly/monthly payments are payer-authorised member transfers. They are not an integrator subscription mandate: your app’s pay-by-prompt renewals still require the payer to approve each prompt. Do not infer payment from a shared QR, browser redirect, scheduled date or notification.

• 401 — missing or wrong Integration ID / Encryption Key.
• 403 — the application is suspended.
• 400 — the payer could not be found, or the amount is outside $1.00–$10,000.00.

TV subscriptions, electricity meters, internet accounts and other services can use Business Codes with merchant-defined required customer fields. A merchant must supply its authorised service connection; registration alone cannot activate external services.

Connect a merchant-owned Live integrator app through JewelForex review. Automated service connections start disabled. The merchant runs its own server worker and polls the authenticated service API; no arbitrary merchant URL is fetched by JewelForex.

GET /api/public/jewelpay/services
POST /api/public/jewelpay/services
X-Integration-Id: YOUR_INTEGRATION_ID
X-Encryption-Key: YOUR_PRIVATE_KEY

{ "action": "claim", "order_id": "ORDER_UUID" }
// Returns a claim token plus paid amount, currency, service and customer fields.
// Use order_id as the merchant's persistent provider idempotency key.

{ "action": "confirm", "order_id": "ORDER_UUID",
  "claim_token": "CLAIM_UUID", "status": "fulfilled",
  "provider_reference": "ACTUAL_PROVIDER_REFERENCE",
  "result": { "message": "Subscription activated", "token": "OPTIONAL_ELECTRICITY_TOKEN" } }

GET /api/public/jewelpay/services?id=ORDER_UUID

Only the connected integration can claim or confirm its orders. Confirm fulfilled only after your biller reports activation; accepted/pending is not success. Use failed with a real provider reference for rejected activation. Uncertain outcomes must be queried with the biller before retrying; never blindly issue the service twice. Claims become retryable after ten minutes. Identical final confirmations are idempotent; conflicting ones are refused. Reversed payments cannot be fulfilled. Customers see activation status/token separately from their payment receipt.

Available APIs also cover payment prompts, funded wallet credits, app-owned receipt/status reads and merchant service confirmations. Broker funding and arbitrary biller APIs are not currently enabled.

Email support@jewelforex.app or call +263 716 913 622 (calls only). Ava, our assistant, answers integration questions by email around the clock.

• October 2026 — Sandbox tester. Every new application starts in Sandbox. Send test pay-by-prompt requests from the Sandbox tab in your developer dashboard using the test numbers and amounts listed there; no real money moves.
• Multi-currency wallets. Payers can hold many currencies in one JewelForex account. Prompts still settle in USD; payers swap at a locked rate first.
• Wallet URL. The payer wallet now lives at /wallet. Old /monetization links redirect automatically.