Getting Started with PayOrc

Getting Started with PayOrc

This guide walks you through the complete PayOrc integration process — from obtaining your API credentials to processing your first payment. By the end, you'll have a working payment flow that your customers can use to pay securely. n

Prerequisites

Before you begin, make sure you have everything you need:

1. PayOrc Merchant Account — Sign up at merchant.payorc.com. You'll need a verified merchant account to access the API.
2. API Keys — Generate from Developers → API Keys → Add new API key in your dashboard. These keys authenticate every request you make.
3. Server Environment — A backend server capable of making HTTP requests (Node.js, PHP, Python, or any language with HTTP support).
4. SSL Certificate — Required for webhook endpoints. All webhook URLs must use HTTPS.

Note: Never make API calls from client-side code. Always use a backend server to protect your merchant credentials from being exposed.

Step 1: Get Your API Keys

Your API keys are the foundation of the integration. They authenticate every request and link transactions to your merchant account.

Navigate to Developers → API Keys → Add new API key in your PayOrc Merchant Dashboard.

PayOrc provides different API keys for different integration channels:

Each key pair consists of a merchant-key and a merchant-secret. You'll pass these as HTTP headers with every API request.

Warning: Keep your API keys secure. Never expose them in client-side code, public repositories, or version control systems. If you suspect a key has been compromised, revoke it immediately from your dashboard and generate a new one.

Step 2: Understand the Integration Flow

Before writing any code, it's important to understand how the payment flow works. PayOrc uses a hosted payment page model, meaning your customers enter their card details on a PayOrc-hosted page — reducing your PCI compliance burden.

Here's how the flow works from start to finish:

1. Your server creates an order by calling the PayOrc API with the payment amount, currency, and customer details.
2. PayOrc returns a payment link — a unique URL for this specific transaction.
3. You redirect the customer to the PayOrc payment page using that link.
4. The customer enters their card details on the secure, PCI-compliant PayOrc payment page.
5. PayOrc processes the payment — this may include 3D Secure authentication if required by the card issuer.
6. PayOrc redirects the customer back to your success, cancel, or failure URL with the transaction result.
7. PayOrc sends a webhook to your server with the final payment status (this is the most reliable way to confirm payment).
8. You update your order in your database based on the webhook data.

Note: The webhook (step 7) is the most reliable source of payment status. The redirect (step 6) can be used for immediate UI feedback, but always verify payment status via the webhook.

Step 3: Create Your First Order

Use the Payment Request API to create an order and obtain a payment link. This is the core of the PayOrc integration — every payment starts with this call.

The API endpoint is:

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

You'll need to send two custom headers for authentication:

• merchant-key — Your merchant key
• merchant-secret — Your merchant secret

Below are complete examples in 5 languages. Each example creates a test order for 100 AED with the full required body (customer_details, order_details, billing_details, shipping_details, urls including webhook_url, plus parameters, custom_data, and items).

curl --location '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": {
        "class": "ECOM",
        "action": "SALE",
        "capture_method": "",
        "payment_token": "",
        "customer_details": {
            "m_customer_id": "CUST-001",
            "name": "John Doe",
            "email": "[email protected]",
            "mobile": "971501234567",
            "code": "971"
        },
        "order_details": {
            "m_order_id": "ORDER_001",
            "amount": 100,
            "quantity": 1,
            "convenience_fee": 0,
            "currency": "AED",
            "description": "Test payment",
            "return_url": ""
        },
        "billing_details": {
            "address_line1": "123 Main Street",
            "address_line2": "",
            "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 Main Street",
            "address_line2": "",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044",
            "location_pin": "",
            "shipping_currency": "AED",
            "shipping_amount": 0
        },
        "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": ""
            }
        ],
        "items": [
            {
                "title": "Premium Plan",
                "description": "Monthly subscription",
                "quantity": 1,
                "unit_price": "100.00",
                "discount_amount": "0.00",
                "reference_id": "SKU-001",
                "image_url": "",
                "product_url": "",
                "gender": "",
                "category": "Subscription",
                "color": "",
                "product_material": "",
                "size_type": "",
                "size": "",
                "brand": "PayOrc",
                "is_refundable": true
            }
        ]
    }
}'

Understanding the Request Parameters

See the full field reference in Payment Request API.

Warning: The m_order_id must be unique for every order. Reusing order IDs will cause errors. Use a UUID or database auto-increment ID for reliability.

Step 4: Handle the Redirect Response

After the customer completes (or fails) payment on the PayOrc payment page, they are redirected back to the URL you specified in the urls parameter. The transaction details are appended as query parameters to the redirect URL.

Understanding which URL to handle and what data you receive is critical for keeping your order status in sync.

Redirect URLs explained:

Callback parameters:

Note: The redirect response is good for immediate user feedback, but it's not the most reliable source of truth. Customers may close their browser before the redirect completes, or the request could be intercepted. Always use webhooks (Step 5) for authoritative payment status updates.

Step 5: Set Up Webhooks

Webhooks are the most important part of the integration. They ensure your server receives payment notifications even if the customer closes their browser, loses internet connectivity, or the redirect fails for any reason.

When a payment status changes (authorization, capture, refund, failure), PayOrc sends an HTTP POST request to your webhook URL with the transaction details.

To set up webhooks:

1. Enable webhooks in your PayOrc merchant dashboard
2. Set your webhook URL — this must be a publicly accessible HTTPS endpoint
3. Configure a notification secret — used to verify that incoming webhooks are genuinely from PayOrc
4. Handle the webhook — parse the request body, verify the secret, and update your database

Here's a complete webhook handler implementation:

# You can test your webhook endpoint locally using ngrok:
# ngrok http 3000
# Then set the ngrok URL as your webhook URL in the dashboard

# Test webhook with curl:
curl -X POST 'https://your-site.com/webhook/payorc' \
--header 'Content-Type: application/json' \
--header 'notification-secret: {your-notification-secret}' \
--data '{
    "action": "AUTH",
    "status": "SUCCESS",
    "p_order_id": "PO123",
    "m_order_id": "ORDER_001",
    "transaction_id": "TXN456",
    "amount": "100",
    "currency": "AED"
}'

Warning: Always validate the notification-secret header before processing a webhook. Without this verification, an attacker could send fake payment notifications to your endpoint. Never skip this step in production.

Note: Respond with a 200 status code within a reasonable time. If your server returns an error or times out, PayOrc will retry the webhook delivery.

Step 6: Manage Payments

After a payment is authorized, you may need to perform additional actions like capturing the funds, issuing a refund, or voiding the transaction. These operations are done through the Manage Payment API.

Available actions:

All three actions use the same endpoint: POST /orders/transaction

Here's how to perform each action:

# Capture an authorized payment
curl --location 'https://api.payorc.com/orders/api/v1/transaction' \
--header 'merchant-key: {your-merchant-key}' \
--header 'merchant-secret: {your-merchant-secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "CAPTURE",
    "transaction_id": "1000010118",
    "amount": {
        "currencyCode": "AED",
        "value": 100.00
    },
    "reason": "Order shipped - full capture"
}'

# Refund a captured payment
curl --location 'https://api.payorc.com/orders/api/v1/transaction' \
--header 'merchant-key: {your-merchant-key}' \
--header 'merchant-secret: {your-merchant-secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "REFUND",
    "transaction_id": "1000010118",
    "amount": {
        "currencyCode": "AED",
        "value": 100.00
    },
    "reason": ""
}'

# Void an authorized payment (before capture)
curl --location 'https://api.payorc.com/orders/api/v1/transaction' \
--header 'merchant-key: {your-merchant-key}' \
--header 'merchant-secret: {your-merchant-secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "VOID",
    "transaction_id": "1000010118",
    "amount": {
        "currencyCode": "AED",
        "value": 100.00
    },
    "reason": ""
}'

Note: You can issue partial refunds by specifying an amount less than the original transaction amount. The amount field in refund requests determines how much to return to the customer.

Step 7: Test with Test Cards

PayOrc provides test card numbers that simulate different payment scenarios. Use these to verify your integration works correctly before going live.

Test card numbers:

For all test cards, use:

• Expiry Date: Any future date (e.g., 12/28)
• CVV: Any 3 digits (e.g., 123)
• Cardholder Name: Any name

Note: Always use test API keys during development. Switch to live API keys only after you've thoroughly tested all payment flows, including success, failure, and 3D Secure scenarios.

Warning: Test cards only work in the sandbox environment. They will not process real payments. When you switch to live API keys, you must use real cards (with real money) for final verification.

Step 8: Go Live

You're almost there! Before processing real payments, follow this checklist to ensure a smooth launch:

1. Switch to live API keys — Replace your test merchant-key and merchant-secret with the live credentials from your dashboard.
2. Update webhook URLs — Make sure your webhook endpoints are pointing to your production servers, not your local development environment.
3. Verify HTTPS — Confirm all webhook URLs use valid SSL certificates. PayOrc will not send webhooks to HTTP endpoints.
4. Test all payment flows — Process a few real transactions (even small amounts) to verify everything works end-to-end.
5. Check webhook delivery — Monitor your server logs and the PayOrc dashboard to confirm webhooks are being received and processed.
6. Monitor transaction success rates — Keep an eye on the analytics dashboard to catch any issues early.
7. Set up error alerting — Configure alerts for failed webhooks or payment processing errors so you can respond quickly.

Warning: Don't skip live testing with real cards. Even if your sandbox testing went perfectly, production environments can have different configurations. Always do a final verification with a small real transaction before going fully live.

API Reference

For complete endpoint documentation and detailed parameter descriptions, see:

• Payment Request API — Create orders and obtain payment links
• Capture — Capture authorized payments
• Refund — Refund captured payments
• Void — Cancel authorized payments before capture
• Webhooks — Real-time payment notifications

Support

If you run into issues during integration, reach out to us:

• Email: [email protected]
• Dashboard: merchant.payorc.com
• API Status: Check the PayOrc status page for any ongoing incidents