JewelForex

JewelPay Integrator Documentation

Accept JewelForex payments from your own app with a single prompt on the payer's device — they approve with their password plus their Authorization Code or device unlock, exactly as they do inside JewelForex.

Open your dashboard
Powered byJewelPay

1. Getting started

  1. Open the Developers page and register as a JewelPay Integrator.
  2. Create an application. It starts in Sandbox with its own Integration ID and Encryption Key.
  3. Build and test against the sandbox values below — no real money moves.
  4. Upload your signed contract. Once countersigned, your application switches to Live.

2. Authentication

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.

3. Request a payment (pay by prompt)

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"
}
{
  "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 prompt appears on the payer's device instantly and expires after five minutes.

4. Check the result

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).

5. Fees and settlement

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.

6. Sandbox test values

Test cards

  • 4242 4242 4242 4242 — Always approves
  • 4000 0000 0000 0002 — Always declines

Test numbers

  • +263 771 111 111 — Approves after 3 seconds
  • +263 772 222 222 — Payer declines the prompt
  • +263 773 333 333 — Prompt times out

Test amounts

  • $1.00 – $500.00 — Normal sandbox flow
  • $999.00 — Simulates insufficient balance

7. Errors

  • 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.

8. Support

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