API Reference

One API to accept payments via Paymob (MENA) and Stripe (global). Consistent request and response format regardless of provider.

Quickstart

Get your API key

Create a Stripe charge

Pass your API key as a Bearer token. Amount is in the smallest currency unit (cents / piastres).

curl -X POST https://api.kriedysystems.net/v1/charges \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "usd",
    "provider": "stripe",
    "source": "pm_card_visa"
  }'

Create a Paymob charge

Paymob requires customer details. You receive an iframeUrl to redirect your customer to for payment.

curl -X POST https://api.kriedysystems.net/v1/charges \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "EGP",
    "provider": "paymob",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+201234567890"
  }'

Authentication

All requests require an API key in the Authorization header.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

sk_test_...

Test mode — no real money, no provider charges.

sk_live_...

Live mode — real charges, production providers.

Get your key from the Keys page. Keys are shown only once at creation — store them securely.

Errors

All errors return a consistent JSON body:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "amount must be a positive integer"
}

400

Validation error

401

Invalid API key

429

Quota exceeded

502

Provider error

Charges

POST/v1/chargesCreate a charge

Request body

{
  "amount":      10000,        // required — smallest unit (cents/piastres)
  "currency":    "EGP",        // required — ISO 4217
  "provider":    "paymob",     // "stripe" | "paymob"  (default: "stripe")

  // Stripe only
  "source":      "pm_xxxxx",   // Stripe payment method ID

  // Paymob only
  "first_name":  "John",       // required for paymob
  "last_name":   "Doe",        // required for paymob
  "email":       "j@x.com",    // required for paymob
  "phone":       "+201234567890", // required for paymob

  // Optional
  "description": "Order #123",
  "metadata":    { "orderId": "123" }
}

Response · 201

{
  "id":         "ch_01JKXYZ...",
  "object":     "charge",
  "amount":     10000,
  "currency":   "EGP",
  "status":     "PENDING",       // PENDING | SUCCEEDED | FAILED
  "provider":   "paymob",
  "providerId": "paymob_order_id",
  "iframeUrl":  "https://accept.paymob.com/api/acceptance/iframes/...",
  "createdAt":  "2026-03-14T12:00:00.000Z"
}

GET/v1/charges/:idRetrieve a charge

Response · 200

{
  "id":        "ch_01JKXYZ...",
  "object":    "charge",
  "amount":    10000,
  "currency":  "EGP",
  "status":    "SUCCEEDED",
  "provider":  "paymob",
  "refunds":   []
}

GET/v1/chargesList charges

Query params

?limit=20          // default 20, max 100
?offset=0          // for pagination
?provider=paymob   // filter by provider
?status=SUCCEEDED  // filter by status

Response · 200

{
  "object": "list",
  "data":   [ ...charges ],
  "total":  42,
  "limit":  20,
  "offset": 0
}

Paymob payment flow

Paymob requires a hosted payment page. After creating a charge you receive an iframeUrl — redirect your customer there to complete payment. Kriedy Pay handles the 3-step Paymob auth/order/key flow internally.

Create charge

POST /v1/charges with provider: "paymob"

Redirect customer

Send them to the iframeUrl in the response

Receive webhook

We notify you when payment succeeds or fails

Note on status

A Paymob charge is created with status PENDING. It moves to SUCCEEDED or FAILED via webhook after the customer completes (or abandons) the hosted page.

Refunds

POST/v1/refundsCreate a refund

Request body

{
  "charge_id": "ch_01JKXYZ...", // required
  "amount":    5000,             // omit for full refund
  "reason":    "requested_by_customer"
}

Response · 201

{
  "id":         "re_01JKXYZ...",
  "object":     "refund",
  "chargeId":   "ch_01JKXYZ...",
  "amount":     5000,
  "providerId": "re_stripe_..."
}

Webhooks

Kriedy Pay receives webhooks from Paymob and normalises them into a single format. Configure your Paymob integration callback URL to:

https://api.kriedysystems.net/v1/webhooks/paymob

Paymob callback payload (normalised)

{
  "type":      "charge.succeeded",  // charge.failed | charge.refunded
  "chargeId":  "ch_01JKXYZ...",
  "provider":  "paymob",
  "amount":    10000,
  "currency":  "EGP",
  "createdAt": "2026-03-14T12:00:00.000Z"
}

Webhook authenticity is verified via HMAC-SHA512 using your Paymob HMAC secret. Requests with invalid signatures are rejected with 401.

Usage

GET/v1/usageCurrent month usage

{
  "object":    "usage",
  "month":     "2026-03",
  "tier":      "starter",
  "used":      1247,
  "limit":     10000,
  "remaining": 8753,
  "resetAt":   "2026-04-01T00:00:00.000Z"
}

Need help?

Can't find what you're looking for? We respond within 24 hours.

contact@kriedysystems.com →