Hosted Payment Page

Hosted Payment Page

Version: 3.0.0

Why Use the Hosted Payment Page?

• Zero PCI burden — Card data never touches your servers, so you avoid SAQ-A or SAQ-A-EP compliance entirely.
• Fastest time to market — One API call generates a payment link. Redirect your customer and you're done.
• Full branding control — Customize colors, logos, and fields through your PayOrc dashboard before redirecting.
• Built-in security — 3D Secure 2.0, tokenization, fraud screening, and SSL are all handled for you.

Prerequisites

Before integrating, ensure you have:

1. An active PayOrc merchant account
2. An API key generated for the Hosted Solution channel
   • Navigate to Developers → API Keys → Add new API key → Select "Hosted Solution" in the Channel dropdown
3. Your merchant-key and merchant-secret credentials ready

Authentication

All API requests require two headers:

Flow Overview

Here is the complete step-by-step payment flow:

Step 1 — Create Order: Your server sends a POST request to the PayOrc API to create a payment order. You include order details (amount, currency, customer info, redirect URLs).

Step 2 — Receive Payment Link: PayOrc responds with a payment_link URL and an iframe_link URL. The payment link points to the hosted checkout page.

Step 3 — Redirect Customer: You redirect your customer to the payment_link. The customer enters their card details on PayOrc's secure page.

Step 4 — 3D Secure (if enabled): If 3D Secure is enabled for the transaction, the customer is redirected to their bank's authentication page, then brought back to PayOrc.

Step 5 — Transaction Processing: PayOrc processes the payment (authorization and/or capture depending on your capture_method setting).

Step 6 — Redirect to Merchant: Based on the outcome, the customer is redirected to your success, failure, or cancel URL with transaction details appended.

Step 7 — Server-Side Callback: PayOrc also sends a POST callback to your configured endpoint with the full transaction payload for server-side verification.

Step 1: Create Order

Make a POST request to the /orders/v1/create endpoint with your order details. This is the only call you need to initiate a hosted payment.

Endpoint:

POST https://api.payorc.com/orders/v1/create

Request Body

All fields are nested inside a top-level data object: { "data": { ... } }. The customer_details, order_details, billing_details, shipping_details, and urls objects are all required — a request missing any of them is rejected (e.g. Shipping details object missing). Individual fields marked "Yes" are required by the schema but may be passed as empty strings unless noted otherwise.

Code Examples

curl --location --globoff 'https://api.payorc.com/orders/v1/create' \
--header 'merchant-key: YOUR_MERCHANT_KEY' \
--header 'merchant-secret: YOUR_MERCHANT_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "action": "SALE",
        "class": "ECOM",
        "capture_method": "AUTOMATIC",
        "payment_token": "",
        "customer_details": {
            "m_customer_id": "CUST-10042",
            "name": "John Doe",
            "email": "[email protected]",
            "mobile": "9876543210",
            "code": "91"
        },
        "order_details": {
            "m_order_id": "ORD-2024-001",
            "amount": 150,
            "convenience_fee": 0,
            "quantity": 1,
            "currency": "AED",
            "description": "Annual subscription plan",
            "return_url": "https://your-site.com/return"
        },
        "billing_details": {
            "address_line1": "123 Business Park",
            "address_line2": "Unit 5B",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044"
        },
        "shipping_details": {
            "shipping_name": "John Doe",
            "shipping_email": "[email protected]",
            "shipping_code": "",
            "shipping_mobile": "",
            "address_line1": "123 Business Park",
            "address_line2": "Unit 5B",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044",
            "location_pin": "",
            "shipping_currency": "AED",
            "shipping_amount": 0
        },
        "items": [
            {
                "title": "Annual Subscription",
                "description": "12-month plan",
                "quantity": 1,
                "unit_price": "150.00",
                "discount_amount": "0.00",
                "reference_id": "SUB-ANNUAL",
                "is_refundable": true
            }
        ],
        "urls": {
            "success": "https://your-site.com/payment/success",
            "cancel": "https://your-site.com/payment/cancel",
            "failure": "https://your-site.com/payment/failure",
            "webhook_url": "https://your-site.com/webhook"
        },
        "parameters": [
            { "alpha": "" },
            { "beta": "" },
            { "gamma": "" },
            { "delta": "" },
            { "epsilon": "" }
        ],
        "custom_data": [
            { "alpha": "" },
            { "beta": "" },
            { "gamma": "" },
            { "delta": "" },
            { "epsilon": "" }
        ]
    }
}'

Step 2: Redirect to Payment Page

Once you receive a successful response, redirect the customer to the payment_link URL. This opens PayOrc's fully managed checkout page where the customer can enter their payment details.

The response also includes an iframe_link if you prefer to embed the checkout directly on your site (see the Iframe Integration page).

Step 3: Handle the Redirect

When the customer completes, cancels, or fails at the payment page, they are redirected back to one of the URLs you specified in the request.

The redirect URL includes query parameters with transaction details (see Post Final Response for the full field reference).

Response Fields

Example: Success Response

{
    "status": "SUCCESS",
    "status_code": "00",
    "message": "Order created",
    "p_order_id": 1000010240,
    "m_order_id": "ORD-2024-001",
    "p_request_id": 1000010200,
    "order_creation_date": "15/06/2023 12:20:27",
    "amount": "AED 150.00",
    "payment_link": "https://checkout.payorc.com/pay/abc123xyz",
    "iframe_link": "https://checkout.payorc.com/embed/abc123xyz"
}

Example: Error Response

{
    "status": "fail",
    "status_code": 401,
    "message": "Invalid merchant key and secret",
    "code": "401"
}

What Happens After the Customer Pays?

1. PayOrc processes the payment with the acquiring bank/PSP.
2. If 3D Secure was triggered, the authentication result is included in the authorization decision.
3. The customer is redirected to your success/failure/cancel URL with query parameters containing the transaction details.
4. PayOrc simultaneously sends a server-to-server POST callback to your configured endpoint with the full transaction payload.
5. Your application should verify the callback signature, update the order status, and fulfill the purchase.

Always use the server-side callback for order fulfillment — never rely solely on the client-side redirect. The redirect can be spoofed or lost due to network issues.