One Pay — Sub-merchant Integration Guide
How to accept online payments through One Pay and have each payment attributed and settled to the right business (a sub-merchant).
One Pay collects every payment through a single Omnipay merchant account. For each payment, the hub records which business it belongs to, keeps a ledger of what that business is owed, and settles it to their bank account. Your integration does three things: register a business, start a payment for it, and check when that payment is paid. Everything that moves or releases money — activating a business, setting its fee, approving payouts — is done by One Pay staff on the dashboard, never through this API.
| You (the integrator) | One Pay |
|---|---|
| Register the business as a sub-merchant | Verify it and activate it (dashboard) |
| Start a payment for an order | Return a ready-to-pay checkout URL |
| Send the customer to that URL | Run the GCash / QR Ph checkout, confirm the money |
Poll the payment until it's paid |
Take the agreed fee, credit the business's balance |
Fulfil the order once it's paid |
Settle the balance to the business's bank account |
You never handle card or account numbers, and you don't integrate GCash, QR Ph, or the bank rails yourself.
1. Base URL
Production https://pay.pod.com.ph/v1/hub
All endpoints below are relative to that base. Currency is always PHP.
2. Authenticating requests
Every request is signed with HMAC-SHA256. One Pay issues you a key
id (kid) and a secret; keep the secret on your server only — never in browser
or mobile code, and never in a git repo.
Send these headers:
Authorization: HMAC <kid>:<base64 signature>
X-Hmac-Timestamp: <unix seconds> (must be within 5 minutes of now)
Content-Type: application/json (when there is a body)
Idempotency-Key: <uuid> (optional; makes a POST retry safe)
The signature is computed over a canonical string:
signature = base64( HMAC-SHA256( secret, METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY_DIGEST ) )
BODY_DIGEST = base64( SHA-256( raw request body bytes ) ) — or "" for GET / no body
PATH = the path only, e.g. "/v1/hub/payments" (no query string)
Sign the exact bytes you send. If you re-serialize the JSON after signing, the signature won't match.
PHP (Laravel)
function hubRequest(string $method, string $path, ?array $body = null): array {
$raw = $body === null ? '' : json_encode($body, JSON_UNESCAPED_SLASHES);
$ts = (string) time();
$digest = $raw === '' ? '' : base64_encode(hash('sha256', $raw, true));
$sig = base64_encode(hash_hmac('sha256', "$method\n$path\n$ts\n$digest", config('onepay.secret'), true));
return Http::withHeaders([
'Authorization' => 'HMAC ' . config('onepay.kid') . ':' . $sig,
'X-Hmac-Timestamp' => $ts,
])->withBody($raw, 'application/json')
->send($method, config('onepay.base_url') . $path)
->json();
}
Node / TypeScript
import { createHash, createHmac } from "node:crypto";
async function hubRequest(method: string, path: string, body?: unknown) {
const raw = body === undefined ? "" : JSON.stringify(body);
const ts = String(Math.floor(Date.now() / 1000));
const digest = raw === "" ? "" : createHash("sha256").update(raw).digest("base64");
const sig = createHmac("sha256", process.env.ONEPAY_SECRET!)
.update(`${method}\n${path}\n${ts}\n${digest}`).digest("base64");
const res = await fetch(`${process.env.ONEPAY_BASE_URL}${path}`, {
method,
headers: {
Authorization: `HMAC ${process.env.ONEPAY_KID}:${sig}`,
"X-Hmac-Timestamp": ts,
...(raw ? { "Content-Type": "application/json" } : {}),
},
body: raw || undefined,
});
return res.json();
}
3. Money format
Amounts are integer centavos in fields ending _minor (15050 = ₱150.50),
with a decimal string alongside for display. When creating a payment, send
either amount_minor (integer) or amount (string, at most 2 decimals)
— never both. Ambiguous values ("1.234", negatives, exponents) are rejected,
never rounded.
4. The payment flow
1. Customer checks out on your store.
2. Your backend → POST /v1/hub/payments → returns { reference, payment_url }
3. Redirect the customer to payment_url.
4. Customer pays with GCash or QR Ph on the One Pay checkout.
5. Customer returns to your site.
6. Your backend → GET /v1/hub/payments/{reference} → poll until status = "paid"
7. Fulfil the order.
Register (and activate) a business once, up front — steps below.
5. Sub-merchant endpoints
5.1 Register or update a business — PUT /v1/hub/sub-merchants
A business is keyed by province_code (4 digits) + business_id (its id in your
system). The first call creates it; later calls update the fields you
send and leave the rest alone. Send null to clear a field.
{
"province_code": "0354",
"business_id": 4242,
"name": "Kapampangan Kakanin",
"legal_name": null,
"contact_name": "Maria Dizon",
"contact_email": "[email protected]",
"contact_phone": "+63 912 345 6789",
"bank_name": "BPI",
"bank_code": "BPI",
"account_name": "Maria Dizon",
"account_number": "1234-5678-90"
}
201 when created, 200 when updated:
{
"sub_merchant": {
"id": "0b6f2c1e-…",
"province_code": "0354",
"business_id": 4242,
"name": "Kapampangan Kakanin",
"status": "pending",
"can_take_payments": false,
"contact_name": "Maria Dizon",
"contact_email": "[email protected]",
"contact_phone": "+63 912 345 6789",
"fee_bps": 0,
"fee_fixed_minor": 0,
"bank": {
"bank_name": "BPI", "bank_code": "BPI", "account_name": "Maria Dizon",
"account_number_last4": "7890", "complete": true
},
"created_at": "…", "updated_at": "…"
},
"created": true,
"reverted_to_pending": false
}
Rules that protect the money:
- A new business is always
status: "pending"and can't take payments until One Pay staff verify it and activate it on the dashboard. This API cannot setstatus,fee_bps,fee_fixed_minor, or payout minimums — sending those fields is a400. - Changing the bank account of an active business sends it back to
pending(reverted_to_pending: true) until staff re-check the new account. Re-sending the same details changes nothing. - The full account number is stored encrypted and never returned — only the
last 4 digits (
account_number_last4), withcomplete: trueonce bank code, account name and number are all on file. - Set
contact_email— it's where the business receives activation, payout and receipt emails.
5.2 Look up a business
GET /v1/hub/sub-merchants/{id}— by the hub'sid(UUID)GET /v1/hub/businesses/{province_code}/{business_id}— by your own ids
Both return { "sub_merchant": { … } } (same shape as above), or 404
not_found if it isn't registered.
5.3 Balance — GET /v1/hub/sub-merchants/{id}/balance
What's been collected for the business and not yet paid out.
{
"sub_merchant_id": "0b6f2c1e-…",
"currency": "PHP",
"owed_minor": 96500,
"owed": "965.00",
"available_for_payout_minor": 96500
}
5.4 Their payments — GET /v1/hub/sub-merchants/{id}/payments
Query params: status (one of pending, paid, failed, expired,
cancelled, review), limit (1–200, default 50), offset (default 0).
Newest first.
{ "payments": [ { "reference": "OP7K2M9Q4R8T1V6X", "status": "paid", … } ], "limit": 50, "offset": 0 }
6. Payment endpoints
6.1 Start a payment — POST /v1/hub/payments
Identify the business with sub_merchant_id, or province_code +
business_id. Give exactly one of amount_minor or amount.
{
"province_code": "0354",
"business_id": 4242,
"amount": "150.50",
"channel": "hopp",
"caller_ref": "ORDER-1001",
"description": "2 boxes of tibok-tibok",
"return_url": "https://yourstore.com/thank-you?order=1001",
"metadata": { "order_id": 1001, "email": "[email protected]" }
}
channeldefaults tohopp(Omnipay's hosted payment page — QR Ph + GCash).qris refused until Omnipay issues the Collection API token;mockis development-only.caller_refis your order id and your safety net — see idempotency below.return_url(optional) is where the shopper is sent back after paying — your thank-you / order page. It must be an absolutehttps://URL. On our hosted QR page (qrchannel) we redirect there on success and append the reference and status, e.g.…/thank-you?order=1001&ref=OP7K2M9Q4R8T1V6X&status=paid. Still confirm the payment with the status call — never trust the redirect alone. (For thehoppchannel the return is handled by Omnipay's hosted page, not this parameter.)metadatais free-form (under 4000 characters of JSON). If it carries anemail, the payer also gets a receipt.
201 on first create (200 if you resend the same caller_ref):
{
"payment": {
"reference": "OP7K2M9Q4R8T1V6X",
"sub_merchant_id": "0b6f2c1e-…",
"status": "pending",
"channel": "hopp",
"currency": "PHP",
"amount_minor": 15050,
"amount": "150.50",
"paid_amount_minor": null,
"fee_minor": null,
"net_minor": null,
"payment_url": "https://…&orderNo=OP7K2M9Q4R8T1V6X&amount=150.50&displayMode=B",
"return_url": "https://yourstore.com/thank-you?order=1001",
"caller_ref": "ORDER-1001",
"description": "2 boxes of tibok-tibok",
"metadata": { "order_id": 1001 },
"created_at": "…",
"paid_at": null
},
"created": true
}
- Redirect the customer to
payment_url. referenceis what ties the money to this business — it goes to Omnipay as the order number. Store it on your order; it's how the payment is found later.caller_refmakes retries safe. Resending the samecaller_refreturns the same payment instead of creating a second one, so a double-click or a network retry never charges twice. Reusing it for a different business or amount is rejected with409 caller_ref_conflict.- A payment expires after 20 minutes unpaid. Resending its
caller_refreturns the sameexpiredpayment, so a retry needs a new one: add an attempt number, likeORDER-1001-2.
6.2 Check a payment — GET /v1/hub/payments/{reference}
Poll this after the customer returns (and/or on a schedule for pending orders).
{ "payment": { "reference": "OP7K2M9Q4R8T1V6X", "status": "paid",
"amount_minor": 15050, "fee_minor": 526, "net_minor": 14524, "paid_at": "…" } }
| status | meaning | what you do |
|---|---|---|
pending |
waiting for the customer to pay | keep the order unpaid; keep polling |
paid |
money received and credited to the business (fee_minor, net_minor set) |
fulfil the order |
review |
money arrived but something's off (wrong amount / late); staff resolve it, then it becomes paid |
hold |
expired |
not paid within 20 minutes (the Omnipay payment page allows 15) | let the customer try again with a new caller_ref, e.g. ORDER-1001-2. Keep checking the old one for a while: if its money still arrives late, it turns paid. |
cancelled / failed |
no money will come | let the customer try again (new payment, new caller_ref) |
Treat only paid as paid. Never fulfil on the redirect back alone — always
confirm with this call.
7. Fees & settlement
- The business's fee (
fee_bps= basis points,fee_fixed_minor= a fixed amount) is agreed at onboarding and set by One Pay staff — not through this API. Each paid payment showsfee_minor(the fee taken) andnet_minor(what was added to the business's balance). netaccrues to the business's balance; watch it with the balance endpoint (§5.3).- Settlement to the bank account is handled by One Pay on the agreed schedule — there's no payout API here. Bank-account changes re-verify the account before the next payout (§5.1).
8. Errors
Errors are JSON: { "error": "<code>", "message": "<human text>" }, sometimes
with a fields array for validation.
{ "error": "sub_merchant_inactive", "message": "sub-merchant is pending; only active sub-merchants can take payments" }
| HTTP | error |
meaning |
|---|---|---|
| 400 | invalid_request (with fields), invalid_amount, invalid_json |
bad input |
| 401 | missing_hmac_authorization, hmac_signature_mismatch, hmac_timestamp_skew, unknown_hmac_kid |
signing problem — check the secret, the clock, and the canonical string |
| 404 | not_found, sub_merchant_not_found |
unknown id or reference |
| 409 | caller_ref_conflict |
same order id reused with a different business or amount |
| 422 | sub_merchant_inactive, channel_unavailable |
business not active yet, or channel not enabled |
Retries: GETs are always safe. For POST /payments, reusing the same
caller_ref (or sending an Idempotency-Key) makes a retry safe.
9. What this API can't do (on purpose)
Activating or suspending a business, setting fees or payout minimums, and
anything that moves money out (payout requests and approvals) are
dashboard-only decisions made by a person. Through /v1/hub a key can
register businesses and start payments, but it can never redirect or release
anyone's money, or change commercial terms.
10. Testing & go-live
- One Pay issues you a
kid+ secret and (for a direct partner) a test business. - Register a business, have staff activate it, then create a payment for a small
amount, open
payment_url, and pay it in the test environment. - Poll
GET /v1/hub/payments/{reference}until it reachespaidwith the rightnet_minor. - Test the retry: resend the same
caller_ref→ samereference, no second charge; a different amount with the samecaller_ref→409.
Go-live checklist
- Business activated (verified + bank on file) —
can_take_payments: true. - Production
base_url,kid,secretinstalled server-side only. - Create → redirect → poll-to-
paidverified end-to-end. - You fulfil only on
status = paid, never on the redirect alone. -
caller_ref= your order id on every payment (idempotency). - Your server clock is NTP-synced (the 5-minute signature window).
See also: HUB-API.md — the same endpoints as an internal
reference for the One backend. The hosted-page callback that actually credits a
payment is documented separately in the one repo
(docs/OMNIPAY-HOPP-INTEGRATION.md).