One Pay Developer docs

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 set status, fee_bps, fee_fixed_minor, or payout minimums — sending those fields is a 400.
  • 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), with complete: true once 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's id (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]" }
}
  • channel defaults to hopp (Omnipay's hosted payment page — QR Ph + GCash). qr is refused until Omnipay issues the Collection API token; mock is development-only.
  • caller_ref is 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 absolute https:// URL. On our hosted QR page (qr channel) 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 the hopp channel the return is handled by Omnipay's hosted page, not this parameter.)
  • metadata is free-form (under 4000 characters of JSON). If it carries an email, 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.
  • reference is 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_ref makes retries safe. Resending the same caller_ref returns 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 with 409 caller_ref_conflict.
  • A payment expires after 20 minutes unpaid. Resending its caller_ref returns the same expired payment, so a retry needs a new one: add an attempt number, like ORDER-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 shows fee_minor (the fee taken) and net_minor (what was added to the business's balance).
  • net accrues 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

  1. One Pay issues you a kid + secret and (for a direct partner) a test business.
  2. 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.
  3. Poll GET /v1/hub/payments/{reference} until it reaches paid with the right net_minor.
  4. Test the retry: resend the same caller_ref → same reference, no second charge; a different amount with the same caller_ref → 409.

Go-live checklist

  • Business activated (verified + bank on file) — can_take_payments: true.
  • Production base_url, kid, secret installed server-side only.
  • Create → redirect → poll-to-paid verified 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).