{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"7ff6414d-f6f1-4d0c-9fc9-66841d4d7300","name":"HealthPay PG Merchant API","description":"# HealthPay Payment Gateway Merchant API Documentation\n\n**Version:** 1.0 \n**Audience:** Merchant developers, technical teams, and integration partners \n**Source:** HealthPay Merchant API Postman collection \n**Last updated:** 23 September 2026\n\n---\n\n# 1\\. Introduction\n\n## 1.1 What is HealthPay?\n\nHealthPay provides a merchant-facing API for creating payment orders and checkout links and for managing related payment operations such as refunds, invoices, subscriptions, balances, settlements, and card-session tokenization.\n\nThe supplied collection separates the API into two HealthPay services:\n\n| Service | Base URL | Used for |\n| --- | --- | --- |\n| Gateway | `https://gateway.pg.healthpay.com.eg` | Orders and card sessions |\n| Dashboard/API | `https://dashboard.healthpay.com.eg` | Checkout links, refunds, invoices, subscriptions, balance and settlements |\n\nThe collection description states that order creation/checkout is split between these services and that the merchant should configure an API key before running requests.\n\n## 1.2 What a merchant can do\n\nThe supplied API collection covers:\n\n- Create a payment order\n- Retrieve an order by UUID\n- Retrieve an order by internal ID\n- Cancel an order\n- Generate a checkout URL\n- List refund requests\n- Request a full or partial refund\n- Retrieve a refund\n- List invoices\n- Create a draft invoice\n- Retrieve an invoice\n- Send an invoice\n- Download an invoice PDF\n- Void an invoice\n- Delete a draft invoice\n- List subscriptions\n- Create a subscription\n- Pause a subscription\n- Resume a subscription\n- Cancel a subscription\n- Retrieve the current ledger balance\n- Retrieve settlement history\n- Create a card-iframe session\n \n\n## 1.3 Recommended integration path\n\nFor a standard payment:\n\n``` text\nMerchant System\n |\n | 1. Create Order\n v\nHealthPay Gateway\n |\n | 2. Return order UUID\n v\nMerchant System\n |\n | 3. Create Checkout URL\n v\nHealthPay\n |\n | 4. Return checkout URL\n v\nMerchant\n |\n | 5. Redirect customer\n v\nCustomer\n |\n | 6. Pay\n v\nHealthPay Checkout\n |\n +-- --> Merchant notification URL (if configured)\n |\n v\nMerchant System\n |\n | 7. Verify order status\n v\nHealthPay\n\n ```\n\nThe collection explicitly demonstrates creating an order, storing its UUID, creating a checkout URL from that UUID, and looking the order up again after payment.\n\n---\n\n# 2\\. Getting Started\n\n## 2.1 Prerequisites\n\nBefore integrating, the merchant needs:\n\n1. A HealthPay merchant account.\n2. A HealthPay API key.\n3. A server-side application capable of making HTTPS requests.\n4. A publicly reachable notification/webhook URL if the merchant uses the `notificationUrl` field.\n5. A browser/client application if the merchant uses the checkout page or card iframe.\n \n\nThe collection states that the test API key is obtained from:\n\n**Dashboard → Developer → API keys**\n\n## 2.2 API credentials\n\nThe collection uses:\n\n``` http\nAuthorization: Bearer YOUR_API_KEY\n\n ```\n\nThe Postman collection defines a collection-level Bearer authentication token whose value is `{{api_key}}`.\n\n### Never expose the API key\n\nThe API key should be kept server-side.\n\nDo not:\n\n- Put the API key in browser JavaScript.\n- Put the API key inside a mobile application.\n- Commit the API key to Git.\n- Send the API key to customers.\n- Put the API key in publicly accessible frontend code.\n \n\nThe supplied collection does not define API-key rotation, scopes, expiration, or permissions. These should be confirmed by HealthPay before being documented as supported behavior.\n\n## 2.3 Base URLs\n\n### Gateway API\n\n``` text\nhttps://gateway.pg.healthpay.com.eg\n\n ```\n\nUsed by the supplied collection for:\n\n``` text\nPOST /v1/orders\nGET /v1/orders/uuid/{order_uuid}\nGET /v1/orders/{order_id}\nPOST /v1/orders/{order_id}/cancel\nPOST /v1/card-sessions\n\n ```\n\n### Dashboard API\n\n``` text\nhttps://dashboard.healthpay.com.eg\n\n ```\n\nUsed by the supplied collection for:\n\n``` text\nPOST /api/v1/orders/{order_uuid}/checkout-url\nGET /api/v1/refunds\nPOST /api/v1/refunds\nGET /api/v1/refunds/{refund_id}\nGET /api/v1/invoices\nPOST /api/v1/invoices\nGET /api/v1/invoices/{invoice_uuid}\nPOST /api/v1/invoices/{invoice_uuid}/send\nGET /api/v1/invoices/{invoice_uuid}/pdf\nPOST /api/v1/invoices/{invoice_uuid}/void\nDELETE /api/v1/invoices/{invoice_uuid}\nGET /api/v1/subscriptions\nPOST /api/v1/subscriptions\nPOST /api/v1/subscriptions/{subscription_uuid}/pause\nPOST /api/v1/subscriptions/{subscription_uuid}/resume\nPOST /api/v1/subscriptions/{subscription_uuid}/cancel\nGET /api/v1/balance\nGET /api/v1/settlements\n\n ```\n\n## 2.4 Common headers\n\nFor JSON requests:\n\n``` http\nAuthorization: Bearer YOUR_API_KEY\nContent-Type: application/json\n\n ```\n\nGET requests in the supplied collection do not define a `Content-Type` header.\n\n## 2.5 Your first request\n\nStart with **Create Order**.\n\n``` bash\ncurl -X POST \"https://gateway.pg.healthpay.com.eg/v1/orders\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"environment\": \"test\",\n \"reference\": \"ORDER-10001\",\n \"amount\": 100,\n \"currency\": \"EGP\",\n \"apiOperation\": \"PAY\",\n \"notificationUrl\": \"https://merchant.example.com/webhooks/healthpay\",\n \"city\": \"CAIRO\",\n \"country\": \"EGY\",\n \"street\": \"12 Tahrir Street\"\n }'\n\n ```\n\nThe collection expects a successful response to contain a string `uuid`.\n\n---\n\n# 3\\. Integration Flow\n\n## 3.1 Standard payment flow\n\n### Step 1 — Create an order\n\nCall:\n\n``` http\nPOST /v1/orders\n\n ```\n\nSave the returned order UUID.\n\n### Step 2 — Create the checkout URL\n\nCall:\n\n``` http\nPOST /api/v1/orders/{order_uuid}/checkout-url\n\n ```\n\nThe response contains `checkoutUrl`.\n\n### Step 3 — Send the customer to checkout\n\nOpen the returned checkout URL in the customer's browser.\n\n### Step 4 — Customer pays\n\nThe customer completes payment on the HealthPay checkout page.\n\n### Step 5 — Determine the final payment status\n\nThe collection provides:\n\n``` http\nGET /v1/orders/uuid/{order_uuid}\n\n ```\n\nThe collection description specifically says to run this again after paying through the checkout URL to see the order status change to a success/failure state.\n\n### Step 6 — Process the result\n\nThe merchant should only fulfill the order after its own integration has confirmed the final HealthPay order/payment state.\n\n> The exact complete list of order statuses and their meanings is not defined in the supplied collection and must be confirmed from the API implementation before being published as a fixed status table. \n \n\n---\n\n# 4\\. Orders API\n\n## 4.1 Create Order\n\n### Endpoint\n\n``` http\nPOST https://gateway.pg.healthpay.com.eg/v1/orders\n\n ```\n\n### Authentication\n\nBearer API key.\n\n### Request body\n\nThe supplied collection demonstrates:\n\n``` json\n{\n \"environment\": \"test\",\n \"reference\": \"POSTMAN-TEST-001\",\n \"amount\": 100,\n \"currency\": \"EGP\",\n \"apiOperation\": \"PAY\",\n \"notificationUrl\": \"https://example.com/webhooks/healthpay\",\n \"city\": \"CAIRO\",\n \"country\": \"EGY\",\n \"street\": \"12 Tahrir Street\"\n}\n\n ```\n\n### Fields\n\n| Field | Example | Description |\n| --- | --- | --- |\n| `environment` | `test` | Environment value demonstrated by the collection |\n| `reference` | `POSTMAN-TEST-001` | Merchant's order/reference value |\n| `amount` | `100` | Payment amount |\n| `currency` | `EGP` | Currency |\n| `apiOperation` | `PAY` | Operation demonstrated by the collection |\n| `notificationUrl` | HTTPS URL | Merchant notification endpoint |\n| `city` | `CAIRO` | Customer/order location information |\n| `country` | `EGY` | Country |\n| `street` | `12 Tahrir Street` | Street |\n\nThe collection does not specify which fields are formally mandatory, field-length limits, accepted currencies, or amount precision rules. Those should be confirmed from the API implementation.\n\n### Successful response\n\nThe Postman test expects HTTP `200` or `201` and requires:\n\n``` json\n{\n \"uuid\": \"...\"\n}\n\n ```\n\nThe UUID is saved as the collection variable `order_uuid`.\n\n## 4.2 Look up order by UUID\n\n### Endpoint\n\n``` http\nGET https://gateway.pg.healthpay.com.eg/v1/orders/uuid/{order_uuid}\n\n ```\n\nExample:\n\n``` bash\ncurl \"https://gateway.pg.healthpay.com.eg/v1/orders/uuid/ORDER-UUID\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n\n ```\n\nThe supplied collection expects HTTP `200`.\n\nUse this endpoint when the merchant has the HealthPay order UUID.\n\n## 4.3 Look up order by ID\n\n### Endpoint\n\n``` http\nGET https://gateway.pg.healthpay.com.eg/v1/orders/{order_id}\n\n ```\n\nThe collection extracts `_id` from the UUID lookup response and stores it as `order_id`.\n\nUse the ID endpoint when the merchant has the internal order ID.\n\n## 4.4 Cancel order\n\n### Endpoint\n\n``` http\nPOST https://gateway.pg.healthpay.com.eg/v1/orders/{order_id}/cancel\n\n ```\n\n### Request\n\n``` json\n{\n \"reason\": \"Customer cancelled the order\"\n}\n\n ```\n\nThe collection notes that cancellation is refused if the order is already paid or mid-flight.\n\nUse cancellation only for an order that should no longer proceed to payment.\n\n---\n\n# 5\\. Checkout API\n\n## 5.1 Get Checkout URL\n\n### Endpoint\n\n``` http\nPOST https://dashboard.healthpay.com.eg/api/v1/orders/{order_uuid}/checkout-url\n\n ```\n\n### Request\n\n``` json\n{\n \"customer_name\": \"Test Customer\",\n \"customer_email\": \"test@example.com\",\n \"customer_mobile\": \"+201001234567\"\n}\n\n ```\n\n### Response\n\nThe supplied Postman test expects HTTP `200` and a string:\n\n``` json\n{\n \"checkoutUrl\": \"...\"\n}\n\n ```\n\nThe collection stores the value in `checkout_url`.\n\n## 5.2 Customer checkout\n\nAfter receiving `checkoutUrl`, redirect or open the customer in that URL.\n\nExample server-side response:\n\n``` text\nCreate order\n ↓\nCreate checkout URL\n ↓\nReceive checkoutUrl\n ↓\nRedirect customer to checkoutUrl\n\n ```\n\n## 5.3 Checkout test cards\n\nThe supplied collection provides these test cards:\n\n| Card | Expiry | CVV | Expected result |\n| --- | --- | --- | --- |\n| `4111 1111 1111 1111` | `12/26` | `123` | Visa — success |\n| `4111 1111 1111 1112` | `12/26` | `123` | Visa — hard decline |\n| `5123 4567 8901 2346` | `12/25` | `123` | Mastercard — success |\n| `5078 0362 3198 5581` | `05/25` | `632` | Meeza — success |\n\nThese values are test credentials supplied by the collection and must not be used for production transactions.\n\n> The supplied collection contains expiry dates that are now historical relative to the document date. Confirm whether the sandbox still accepts these exact cards before publishing them as currently valid test credentials. \n \n\n---\n\n# 6\\. Webhooks / Notifications\n\n## 6.1 Notification URL\n\nThe order request supports:\n\n``` json\n{\n \"notificationUrl\": \"https://merchant.example.com/webhooks/healthpay\"\n}\n\n ```\n\nThe field is demonstrated in the Create Order request.\n\n## 6.2 Merchant endpoint requirements\n\nThe merchant's endpoint should:\n\n1. Be reachable by HealthPay.\n2. Use HTTPS in production.\n3. Accept the notification request.\n4. Validate the received data.\n5. Locate the corresponding merchant order.\n6. Verify the current HealthPay order/payment state.\n7. Make processing idempotent.\n8. Return an appropriate HTTP response.\n \n\n## 6.3 Important limitation\n\nThe supplied collection does **not** define:\n\n- Webhook payload schema\n- Webhook event names\n- Signature header\n- Signature algorithm\n- Retry schedule\n- Retry count\n- Delivery timeout\n- Whether notifications are sent once or repeatedly\n- Expected merchant response body\n- Event ordering guarantees\n \n\nTherefore these items should not be guessed. They must be confirmed from the HealthPay webhook implementation before merchants rely on them.\n\n## 6.4 Recommended payment verification\n\nA notification should not by itself be treated as proof of a successful payment unless the notification contract explicitly guarantees that behavior.\n\nThe collection provides an order lookup endpoint that can be used to retrieve the current order state:\n\n``` http\nGET /v1/orders/uuid/{order_uuid}\n\n ```\n\nThe merchant integration should use the documented HealthPay status as the source for fulfillment.\n\n---\n\n# 7\\. Refunds\n\n## 7.1 List refund requests\n\n``` http\nGET https://dashboard.healthpay.com.eg/api/v1/refunds\n\n ```\n\nReturns the merchant's refund requests according to the API's response contract.\n\nPagination/filter parameters are not defined in the supplied collection.\n\n## 7.2 Request a refund\n\n``` http\nPOST https://dashboard.healthpay.com.eg/api/v1/refunds\n\n ```\n\n### Full refund\n\n``` json\n{\n \"order_uuid\": \"{{order_uuid}}\",\n \"reason\": \"Customer requested refund\"\n}\n\n ```\n\nThe collection explicitly states that omitting `amount` requests a full refund.\n\n### Partial refund\n\nThe collection states that an `amount` may be supplied for a partial refund, but does not provide a sample payload. A likely structure is:\n\n``` json\n{\n \"order_uuid\": \"ORDER-UUID\",\n \"amount\": 50,\n \"reason\": \"Partial refund\"\n}\n\n ```\n\n> Confirm the exact partial-refund field type and rules before publishing this example as a guaranteed contract. \n \n\n## 7.3 Refund prerequisites\n\nThe collection states that the order must be settled/paid before requesting a refund.\n\nThe request is queued for admin review.\n\nThe collection says the refund can be approved from:\n\n**Admin → Refunds → Refund Requests**\n\n## 7.4 Look up refund\n\n``` http\nGET https://dashboard.healthpay.com.eg/api/v1/refunds/{refund_id}\n\n ```\n\nThe refund ID is returned by the refund request and stored in the Postman variable `refund_id`.\n\n## 7.5 Refund lifecycle\n\n``` text\nPaid Order\n ↓\nRefund Request\n ↓\nPending Review\n ↓\nAdmin Approval\n ↓\nRefund Processing\n ↓\nFinal Refund Result\n\n ```\n\nThe collection only explicitly documents the review/approval stage. Exact refund status values are not supplied.\n\n---\n\n# 8\\. Invoices\n\n## 8.1 List invoices\n\n``` http\nGET https://dashboard.healthpay.com.eg/api/v1/invoices\n\n ```\n\n## 8.2 Create draft invoice\n\n``` http\nPOST https://dashboard.healthpay.com.eg/api/v1/invoices\n\n ```\n\n### Example\n\n``` json\n{\n \"customer_name\": \"Test Customer\",\n \"customer_email\": \"test@example.com\",\n \"currency\": \"EGP\",\n \"due_date\": \"2026-10-01\",\n \"items\": [\n {\n \"description\": \"Consultation\",\n \"quantity\": 1,\n \"unit_price\": 500\n }\n ]\n}\n\n ```\n\nThe response's `uuid` is saved as `invoice_uuid`.\n\n## 8.3 Invoice fields\n\n| Field | Example | Purpose |\n| --- | --- | --- |\n| `customer_name` | `Test Customer` | Customer name |\n| `customer_email` | `test@example.com` | Customer email |\n| `currency` | `EGP` | Invoice currency |\n| `due_date` | `2026-10-01` | Invoice due date |\n| `items` | array | Invoice line items |\n| `items[].description` | `Consultation` | Item description |\n| `items[].quantity` | `1` | Quantity |\n| `items[].unit_price` | `500` | Unit price |\n\nThe collection does not define validation rules or maximum values for these fields.\n\n## 8.4 Look up invoice\n\n``` http\nGET https://dashboard.healthpay.com.eg/api/v1/invoices/{invoice_uuid}\n\n ```\n\n## 8.5 Send invoice\n\n``` http\nPOST https://dashboard.healthpay.com.eg/api/v1/invoices/{invoice_uuid}/send\n\n ```\n\nThe request changes the invoice into a payable state according to the endpoint name and collection organization.\n\n## 8.6 Download invoice PDF\n\n``` http\nGET https://dashboard.healthpay.com.eg/api/v1/invoices/{invoice_uuid}/pdf\n\n ```\n\nThe response is expected to represent/download the invoice PDF.\n\n## 8.7 Void invoice\n\n``` http\nPOST https://dashboard.healthpay.com.eg/api/v1/invoices/{invoice_uuid}/void\n\n ```\n\nThe collection states that voiding is blocked once the invoice has been paid.\n\n## 8.8 Delete draft invoice\n\n``` http\nDELETE https://dashboard.healthpay.com.eg/api/v1/invoices/{invoice_uuid}\n\n ```\n\nThe collection states that deletion works only for a draft that has not been sent.\n\n## 8.9 Invoice lifecycle\n\n``` text\nDraft\n |\n +-- --> Delete\n |\n v\nSend\n |\n v\nPayable\n |\n v\nPaid\nDraft/Payable\n |\n v\nVoid\n\n ```\n\nThe exact API status values are not supplied by the collection.\n\n---\n\n# 9\\. Subscriptions\n\n## 9.1 List subscriptions\n\n``` http\nGET https://dashboard.healthpay.com.eg/api/v1/subscriptions\n\n ```\n\n## 9.2 Create subscription\n\n``` http\nPOST https://dashboard.healthpay.com.eg/api/v1/subscriptions\n\n ```\n\n### Example\n\n``` json\n{\n \"customer_name\": \"Test Customer\",\n \"customer_email\": \"test@example.com\",\n \"currency\": \"EGP\",\n \"interval_unit\": \"month\",\n \"interval_count\": 1,\n \"due_days\": 7,\n \"items\": [\n {\n \"description\": \"Monthly plan\",\n \"quantity\": 1,\n \"unit_price\": 300\n }\n ]\n}\n\n ```\n\nThe response's `uuid` is stored as `subscription_uuid`.\n\n## 9.3 Subscription behavior\n\nThe collection description states:\n\n> A normal invoice is automatically generated and sent every billing cycle; no card is charged silently. \n \n\nTherefore the documented flow is invoice-based rather than silent automatic card charging.\n\n## 9.4 Billing interval\n\nThe example uses:\n\n``` json\n{\n \"interval_unit\": \"month\",\n \"interval_count\": 1\n}\n\n ```\n\nThe collection does not define the complete set of accepted `interval_unit` values. Confirm supported units before documenting them as exhaustive.\n\n## 9.5 Due days\n\n``` json\n{\n \"due_days\": 7\n}\n\n ```\n\nThe example indicates a seven-day due period.\n\nThe collection does not define whether zero/negative values are accepted or the maximum value.\n\n## 9.6 Pause subscription\n\n``` http\nPOST /api/v1/subscriptions/{subscription_uuid}/pause\n\n ```\n\n## 9.7 Resume subscription\n\n``` http\nPOST /api/v1/subscriptions/{subscription_uuid}/resume\n\n ```\n\n## 9.8 Cancel subscription\n\n``` http\nPOST /api/v1/subscriptions/{subscription_uuid}/cancel\n\n ```\n\n## 9.9 Subscription lifecycle\n\n``` text\nCreated\n |\n v\nActive\n / \\\n / \\\nPause Cancel\n |\n v\nPaused\n |\n v\nResume\n |\n v\nActive\n\n ```\n\nThe exact status values are not specified by the supplied collection.\n\n---\n\n# 10\\. Balance & Settlements\n\n## 10.1 Current ledger balance\n\n``` http\nGET https://dashboard.healthpay.com.eg/api/v1/balance\n\n ```\n\nThis is a read-only endpoint according to the collection.\n\nUse it to retrieve the current merchant ledger balance.\n\n## 10.2 Settlement history\n\n``` http\nGET https://dashboard.healthpay.com.eg/api/v1/settlements\n\n ```\n\nThis is also read-only.\n\nUse it to retrieve settlement batch history.\n\n## 10.3 Settlement information\n\nThe collection does not define:\n\n- Settlement status values\n- Settlement frequency\n- Settlement schedule\n- Minimum settlement amount\n- Bank-account information\n- Fees\n- Settlement currency rules\n- Pagination\n- Settlement response schema\n \n\nThese must be documented from the actual API response/implementation before being promised to merchants.\n\n---\n\n# 11\\. Card Sessions\n\n## 11.1 What is a card session?\n\nThe card-session API creates a short-lived/session token intended for use by the HealthPay card iframe.\n\n## 11.2 Create card iframe session\n\n``` http\nPOST https://gateway.pg.healthpay.com.eg/v1/card-sessions\n\n ```\n\n### Request\n\n``` json\n{\n \"origin\": \"https://your-store.example.com\"\n}\n\n ```\n\nThe collection requires the origin to be the exact HTTPS origin that will host the iframe.\n\nIt must contain:\n\n``` text\nscheme + host\n\n ```\n\nand no path.\n\nExample:\n\n``` text\nhttps://shop.example.com\n\n ```\n\nNot:\n\n``` text\nhttps://shop.example.com/checkout\n\n ```\n\n## 11.3 Response\n\nThe collection expects HTTP `201` and a string:\n\n``` json\n{\n \"token\": \"...\"\n}\n\n ```\n\nThe token is stored in the Postman variable `card_session_token`.\n\n## 11.4 Embed the card iframe\n\nThe collection provides this structure:\n\n``` html\n
src=\"https://card-iframe.healthpay.com.eg/?merchant_id=YOUR_MERCHANT_ID&customer_id=test-customer-1#session=YOUR_SESSION_TOKEN\">\n
</iframe>\n

Replace:

with the merchant/customer/session values.

11.5 Tokenization result

The collection states that the browser should listen for:

window.addEventListener('message', (event) => {\n
    if (event.data?.type === 'healthpay.card.tokenized') {\n
        // Read the tokenized card information from event.data\n
    }\n
});\n

The exact event.data schema is not defined in the supplied collection.

11.6 Important browser limitation

The collection explicitly notes that Postman cannot perform the browser iframe / postMessage handshake.

Therefore card tokenization must be tested in an actual browser environment.

12. Error Handling

12.1 HTTP status codes

The collection explicitly expects the following successful response codes for some operations:

OperationExpected code in collection
Create order
200 or 201
Look up order
200
Get checkout URL
200
Create card session
201

Other endpoint-specific status codes are not defined in the collection.

12.2 Merchant error handling

For every API request:

  1. Check the HTTP status code.
  2. Parse the JSON response when applicable.
  3. Log the request correlation/reference information available to your application.
  4. Do not expose the API key in logs.
  5. Do not treat every non-2xx response as a permanent failure.
  6. For payment operations, verify the final order status before fulfilling the customer's order.

12.3 Error response format

The supplied collection does not provide a standard HealthPay error response example.

Therefore the following should be confirmed before publishing:

{\n
  \"error\": \"...\",\n
  \"message\": \"...\",\n
  \"code\": \"...\",\n
  \"details\": {}\n
}\n

The above is only an illustrative structure and is not a HealthPay contract.

13. Security

13.1 API key

Keep the API key on the merchant backend.

Example:

Customer Browser\n
       |\n
       | no HealthPay secret\n
       v\n
Merchant Backend\n
       |\n
       | Authorization: Bearer API_KEY\n
       v\n
HealthPay API\n

13.2 HTTPS

All supplied HealthPay API base URLs use HTTPS.

Merchant notification endpoints should also use HTTPS in production.

13.3 Card data

The supplied card-session flow is designed around a HealthPay-hosted card iframe.

The collection specifically describes using the iframe and receiving a tokenization event rather than directly collecting card details in Postman.

Merchants should not store or process raw card data unless their approved integration and compliance scope explicitly permits it.

13.4 Webhook security

The supplied collection does not document webhook signatures or verification.

Do not invent a signature-validation algorithm. Obtain the official HealthPay webhook security specification before implementing it.

13.5 PCI considerations

The Postman collection alone does not define HealthPay's PCI responsibilities, merchant PCI scope, SAQ requirements, or compliance obligations.

These must be supplied separately in the merchant onboarding/compliance documentation.

14. Testing

14.1 Test environment

The Create Order example uses:

{\n
  \"environment\": \"test\"\n
}\n

The collection description identifies the API key as a test key obtained from:

Dashboard → Developer → API keys

14.2 Recommended test plan

Test 1 — Create order

Expected:

Test 2 — Retrieve order

Call:

GET /v1/orders/uuid/{order_uuid}\n

Expected:

Test 3 — Generate checkout

Call:

POST /api/v1/orders/{order_uuid}/checkout-url\n

Expected:

Test 4 — Successful payment

Open the checkout URL and use a valid sandbox test card.

Test 5 — Verify payment

Retrieve the order again and confirm its final status.

Test 6 — Failed payment

Use the documented hard-decline test card and verify that the merchant does not fulfill the order.

Test 7 — Refund

After a successful/settled payment:

  1. Create a refund request.
  2. Record the returned refund ID.
  3. Check the refund.
  4. Complete the configured approval process.
  5. Verify the final refund result.

Test 8 — Invoice

Test:

Create draft\n
    ↓\n
Get invoice\n
    ↓\n
Send invoice\n
    ↓\n
Download PDF\n

Also test:

Create draft\n
    ↓\n
Delete draft\n

and:

Create/send invoice\n
    ↓\n
Void when allowed\n

Test 9 — Subscription

Test:

Create\n
  ↓\n
Pause\n
  ↓\n
Resume\n
  ↓\n
Cancel\n

Test 10 — Card session

Test:

Create session\n
    ↓\n
Embed iframe\n
    ↓\n
Enter test card\n
    ↓\n
Receive postMessage tokenization event\n

15. Production / Go-Live

15.1 Production readiness checklist

Before going live, the merchant should verify:

Credentials

Server

Orders

Checkout

Notifications

Refunds

Invoices

Subscriptions

Settlement

Card tokenization

15.2 Production URLs

The supplied collection provides the following URLs but does not separately identify production versus sandbox base URLs:

https://gateway.pg.healthpay.com.eg\n
https://dashboard.healthpay.com.eg\n

Confirm with HealthPay whether these are the final production endpoints and whether separate sandbox endpoints exist.

16. Troubleshooting

16.1 401 / authentication failure

Check:

Correct:

Authorization: Bearer YOUR_API_KEY\n

16.2 Order creation fails

Check:

16.3 Checkout URL is not generated

Check:

  1. The order UUID is correct.
  2. The order exists.
  3. The API key is correct.
  4. The request is sent to the Dashboard API, not the Gateway URL.
  5. Customer information is valid.

Correct endpoint:

https://dashboard.healthpay.com.eg/api/v1/orders/{order_uuid}/checkout-url\n

16.4 Payment appears successful but merchant order is not updated

Do not rely only on the browser redirect.

Use:

GET /v1/orders/uuid/{order_uuid}\n

and compare the current HealthPay order state with the merchant's stored state.

Also verify the notification endpoint if one is configured.

16.5 Cancellation fails

The collection explicitly says cancellation is refused when the order is already paid or mid-flight.

Use cancellation only for an eligible order.

16.6 Refund request fails

Confirm that:

16.7 Invoice cannot be deleted

The collection states that deletion only works for an unsent draft.

16.8 Invoice cannot be voided

The collection states that voiding is blocked after payment.

16.9 Card iframe does not work

Check:

Example origin:

https://shop.example.com\n

Not:

https://shop.example.com/checkout\n

16.10 Postman card-session testing does not complete

This is expected from the collection documentation: Postman cannot perform the browser iframe and postMessage handshake.

Use a browser-based test page hosted on the same origin used to create the card session.

17. Postman Collection

The supplied Postman collection contains these folders:

1. Orders (gateway-pg)\n
   ├── Create order\n
   ├── Look up order by uuid\n
   ├── Look up order by id\n
   └── Cancel order\n
2. Checkout (pg-lrvl)\n
   └── Get checkout URL\n
3. Refunds (pg-lrvl)\n
   ├── List refund requests\n
   ├── Request a refund\n
   └── Look up a refund\n
4. Invoices (pg-lrvl)\n
   ├── List invoices\n
   ├── Create a draft invoice\n
   ├── Look up an invoice\n
   ├── Send invoice\n
   ├── Download invoice PDF\n
   ├── Void invoice\n
   └── Delete draft invoice\n
5. Subscriptions (pg-lrvl)\n
   ├── List subscriptions\n
   ├── Create a subscription\n
   ├── Pause subscription\n
   ├── Resume subscription\n
   └── Cancel subscription\n
6. Balance & Settlements (pg-lrvl, read-only)\n
   ├── Current ledger balance\n
   └── Settlement batch history\n
7. Card Sessions (gateway-pg)\n
   └── Create card-iframe session\n

The collection also automatically stores intermediate values such as order UUID, order ID, checkout URL, refund ID, invoice UUID, subscription UUID, and card session token.

18. Complete Merchant Integration Example

18.1 Backend

Customer\n
   |\n
   | Buy product\n
   v\n
Merchant Website\n
   |\n
   | Create HealthPay order\n
   v\n
Merchant Backend\n
   |\n
   | POST /v1/orders\n
   v\n
HealthPay\n
   |\n
   | uuid\n
   v\n
Merchant Backend\n
   |\n
   | POST /api/v1/orders/{uuid}/checkout-url\n
   v\n
HealthPay\n
   |\n
   | checkoutUrl\n
   v\n
Merchant Backend\n
   |\n
   | redirect\n
   v\n
Customer\n
   |\n
   | payment\n
   v\n
HealthPay Checkout\n
   |\n
   +----</comment> notificationUrl\n
   |\n
   v\n
Merchant Backend\n
   |\n
   | GET /v1/orders/uuid/{uuid}\n
   v\n
HealthPay\n
   |\n
   | final status\n
   v\n
Merchant Backend\n
   |\n
   | fulfill order\n
   v\n
Customer\n

18.2 Example pseudo-code

// 1. Create order\n
const order = await healthpay.createOrder({\n
    environment: \"test\",\n
    reference: merchantOrderReference,\n
    amount: orderAmount,\n
    currency: \"EGP\",\n
    apiOperation: \"PAY\",\n
    notificationUrl: webhookUrl\n
});\n
// 2. Create checkout URL\n
const checkout = await healthpay.createCheckoutUrl(order.uuid, {\n
    customer_name: customer.name,\n
    customer_email: customer.email,\n
    customer_mobile: customer.mobile\n
});\n
// 3. Redirect customer\n
return redirect(checkout.checkoutUrl);\n

After payment:

// Never fulfill solely because the customer returned to your site.\n
// Verify the HealthPay order state.\n
const order = await healthpay.getOrderByUuid(orderUuid);\n
if (isConfirmedSuccessful(order)) {\n
    fulfillMerchantOrder();\n
}\n

isConfirmedSuccessful() must use the actual documented HealthPay status values once those values are confirmed.

19. API Reference Summary

MethodEndpointPurpose
POST
/v1/orders
Create order
GET
/v1/orders/uuid/{order_uuid}
Get order by UUID
GET
/v1/orders/{order_id}
Get order by ID
POST
/v1/orders/{order_id}/cancel
Cancel order
POST
/api/v1/orders/{order_uuid}/checkout-url
Create checkout URL
GET
/api/v1/refunds
List refunds
POST
/api/v1/refunds
Request refund
GET
/api/v1/refunds/{refund_id}
Get refund
GET
/api/v1/invoices
List invoices
POST
/api/v1/invoices
Create invoice
GET
/api/v1/invoices/{invoice_uuid}
Get invoice
POST
/api/v1/invoices/{invoice_uuid}/send
Send invoice
GET
/api/v1/invoices/{invoice_uuid}/pdf
Download PDF
POST
/api/v1/invoices/{invoice_uuid}/void
Void invoice
DELETE
/api/v1/invoices/{invoice_uuid}
Delete draft
GET
/api/v1/subscriptions
List subscriptions
POST
/api/v1/subscriptions
Create subscription
POST
/api/v1/subscriptions/{subscription_uuid}/pause
Pause
POST
/api/v1/subscriptions/{subscription_uuid}/resume
Resume
POST
/api/v1/subscriptions/{subscription_uuid}/cancel
Cancel
GET
/api/v1/balance
Current balance
GET
/api/v1/settlements
Settlement history
POST
/v1/card-sessions
Create card session

20. Information That Must Be Confirmed Before Publishing as Final API Contract

The supplied Postman collection is enough to document the available operations and basic integration flows, but the following are not defined in it:

  1. Complete response schemas for every endpoint.
  2. Complete order status list.
  3. Complete refund status list.
  4. Complete invoice status list.
  5. Complete subscription status list.
  6. Complete settlement status list.
  7. Error response schema.
  8. Error code catalog.
  9. Required/optional status of every request field.
  10. Field validation rules and maximum lengths.
  11. Amount precision/unit rules.
  12. Pagination parameters and response format.
  13. Rate limits.
  14. API key scopes/permissions.
  15. API key expiration/rotation behavior.
  16. Webhook payload schema.
  17. Webhook event names.
  18. Webhook signature/authentication.
  19. Webhook retries and timeout behavior.
  20. Idempotency mechanism.
  21. Production/sandbox endpoint separation.
  22. Production test procedure.
  23. Exact card-tokenization event payload.
  24. Supported subscription interval units.
  25. Refund approval/processing status transitions.
  26. Settlement schedule and fee behavior.

These should be obtained from the API implementation or official HealthPay backend specification before being presented to merchants as guaranteed behavior.

21. Merchant Support Philosophy

A merchant should be able to complete the following without contacting HealthPay engineering:

Get credentials\n
      ↓\n
Configure API\n
      ↓\n
Create order\n
      ↓\n
Create checkout\n
      ↓\n
Test payment\n
      ↓\n
Verify payment\n
      ↓\n
Configure notifications\n
      ↓\n
Handle failures\n
      ↓\n
Request refund\n
      ↓\n
Use invoices\n
      ↓\n
Use subscriptions\n
      ↓\n
Check balance\n
      ↓\n
Check settlements\n
      ↓\n
Integrate card sessions\n
      ↓\n
Complete production checklist\n

If a merchant reaches a point where they need engineering assistance for one of these standard flows, the documentation should contain either a concrete example, a troubleshooting procedure, or an explicit explanation of the missing requirement.

Appendix A — Postman Variables

VariablePurpose
base_gateway
Gateway API base URL
base_dashboard
Dashboard API base URL
api_key
Bearer API key
order_uuid
Current order UUID
order_id
Current internal order ID
checkout_url
Generated checkout URL
refund_id
Current refund ID
invoice_uuid
Current invoice UUID
subscription_uuid
Current subscription UUID
card_session_origin
Browser origin used for card session
card_session_token
Generated card session token

Appendix B — Recommended Merchant Data Mapping

A merchant should normally maintain its own mapping between its resources and HealthPay resources.

Example:

Merchant Order\n
    |\n
    +-- merchant_reference\n
    |\n
    +-- healthpay_order_uuid\n
    |\n
    +-- healthpay_order_id\n
    |\n
    +-- amount\n
    |\n
    +-- currency\n
    |\n
    +-- current_payment_status\n
    |\n
    +-- checkout_url\n
    |\n
    +-- created_at\n
    |\n
    +-- updated_at\n

For refunds:

Merchant Refund\n
    |\n
    +-- merchant_order_reference\n
    +-- healthpay_order_uuid\n
    +-- healthpay_refund_id\n
    +-- amount\n
    +-- reason\n
    +-- status\n

The exact status values should be populated from the confirmed HealthPay API contract.

Appendix C — Support Request Checklist

If technical support is required, the merchant should provide:

Never send an API key or other secret in a support ticket.

\n\n ```","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"22876315","team":4123568,"collectionId":"7ff6414d-f6f1-4d0c-9fc9-66841d4d7300","publishedId":"2sBYB2rTNP","public":true,"publicUrl":"https://documenter-api.postman.tech/view/22876315/2sBYB2rTNP","privateUrl":"https://go.postman.co/documentation/22876315-7ff6414d-f6f1-4d0c-9fc9-66841d4d7300","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"148f8c"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/0dd41118-e6fa-4445-a14f-6ec4fb0f51e4/aHBfbG9nby5wbmc=","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"148f8c"}},{"name":"light","logo":"https://content.pstmn.io/0dd41118-e6fa-4445-a14f-6ec4fb0f51e4/aHBfbG9nby5wbmc=","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"148f8c"}}]}},"version":"8.12.6","publishDate":"2026-09-23T13:19:21.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/0dd41118-e6fa-4445-a14f-6ec4fb0f51e4/aHBfbG9nby5wbmc=","logoDark":"https://content.pstmn.io/0dd41118-e6fa-4445-a14f-6ec4fb0f51e4/aHBfbG9nby5wbmc="}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/62d2ec3ca99a5503fdbd0029fff6be065510b970c9708ee21bd6c4abfc00a044","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sBYB2rTNP"}