For merchants integrating via custom systems - non-Shopify, non-WooCommerce

Getting Started

This guide covers the full integration lifecycle: creating orders, processing refunds, handling webhooks, understanding order statuses, and fetching reporting data via API.

Base URLs

Environment Base URL
Staging https://qa.happypay.co.za
Production https://happypay.co.za

<aside> 💡

Your merchantld and APIKey can be found by logging into your HappyPay merchant account. Note that your QA and Production accounts are separate - both need to be created and approved before use.

</aside>

Part 1

Orders, Refunds, Webhooks & Order Lifecycle

1. Creating Orders

Orders are created via the ServicesV1 API. On success you receive a redirect URL to send the customer to the HappyPay checkout flow.

Endpoint POST {baseUrl}/api/ServicesV1.asmx/createOrder Content-Type: application/json

Parameters

Parameter Type Required Description
id string Yes Your unique order reference (e.g. cart or order ID).
total float Yes Order total amount. Must be greater than 0 .
products array Yes List of product objects. At least one required. See product object below.
currency string Yes Currently only “ZAR” is supported.
successWebhook string Yes URL called when the order is successfully completed. You can append URL vars - we recommend including your orderld and a salt to verify the original URL.
failureWebhook string No* URL called when the order fails. Disabled by default - contact support to enable. Does not affect failReturnUrl flow.
successReturnUrl string Yes URL to redirect the customer to after successful payment.
failReturnUrl string Yes URL to redirect the customer to after failure or cancellation.
merchantId string Yes Your HappyPay merchant ID (GUID).
APIKey string Yes Your merchant API key.
test bool Yes true for test mode, false for live.

Product object fields

Field Type Description
name string Product name
price float Unit price
quantity int Quantity

Example request

POST {baseUrl}/api/ServicesV1.asmx/createOrder
Content-Type: application/json
{
    "id": "ORD-2024-001",
    "total": 599.99,
    "products": [
        { "name": "Widget A", "price": 299.99, "quantity": 1 },

        { "name": "Widget B", "price": 150.00, "quantity": 2 }
    ],
    "currency": "ZAR",
    "successWebhook": "<https://yoursite.com/webhooks/happypay/success>",
    "failureWebhook": "<https://yoursite.com/webhooks/happypay/failure>",
    "successReturnUrl": "<https://yoursite.com/order/success>",
    "failReturnUrl": "<https://yoursite.com/order/failed>",
    "merchantId": "81852c55-0665-4957-88a3-91e0e550c420",
    "test": false
}

Success response

{
    "d": {
        "redirectUrl":
"<https://happypay.co.za/login?orderId=ORD-2024-001&merchantId=81852c55>...",
        "success": true,
        "errorMessage": null,
        "orderId": "12345"
    }
}