Payments hub API (for the One backend)
One Pay collects every payment through a single Omnipay merchant account.
The hub records, for each payment, which business (sub-merchant) it belongs to,
keeps a ledger of what each business is owed, and pays them out. The One
backend uses this API to register businesses and to start payments for them.
Everything else — activating a business, setting its fee, approving payouts —
happens on the dashboard at /admin.
Base URL: https://<payment-api-host>/v1/hub
Signing requests
Every request is signed with the same HMAC scheme as the rest of /v1
(src/middleware/hmac.ts). The key id and secret are one entry of
OMNIPAY_HMAC_CALLERS on this service (kid:secret); keep the secret in the
One backend's .env.
Authorization: HMAC <kid>:<base64 signature>
X-Hmac-Timestamp: <unix seconds> (must be within 5 minutes)
Content-Type: application/json (when there is a body)
Idempotency-Key: <uuid> (optional, POST/PUT only)
signature = base64( HMAC-SHA256( secret,
METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY_DIGEST ) )
BODY_DIGEST = base64( SHA-256( raw body bytes ) ), or "" when there is no body
PATH = the path only, without the query string
Send the exact bytes you signed. Re-encoding the JSON after signing breaks the signature.
// app/Services/PaymentHubClient.php (sketch)
public function request(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('payment_hub.secret'), true));
$res = Http::withHeaders([
'Authorization' => 'HMAC ' . config('payment_hub.kid') . ':' . $sig,
'X-Hmac-Timestamp' => $ts,
])
->withBody($raw, 'application/json')
->send($method, config('payment_hub.url') . $path);
return $res->json();
}
Money
Amounts are integer centavos in fields ending _minor (15050 = ₱150.50),
with a decimal string alongside for display. When creating a payment you may
send amount_minor (integer) or amount (string, at most 2 decimals) — not
both. Anything ambiguous ("1.234", negatives, exponents) is rejected rather
than rounded. Currency is PHP.
Sub-merchants
Register or update a business — PUT /v1/hub/sub-merchants
Keyed by province_code + business_id (the business's id in the One
backend). 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": "0b6f…",
"province_code": "0354",
"business_id": 4242,
"name": "Kapampangan Kakanin",
"status": "pending",
"can_take_payments": false,
"fee_bps": 350,
"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
pendingand cannot take payments until an admin checks it and activates it on the dashboard. The API cannot setstatus, fees or payout minimums; sending them is a400. - Changing the bank account of an active business sends it back to
pending(reverted_to_pending: true) until an admin checks 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 are.
Look one up
GET /v1/hub/sub-merchants/{id}GET /v1/hub/businesses/{province_code}/{business_id}— by the One backend's own ids
Balance — GET /v1/hub/sub-merchants/{id}/balance
{ "sub_merchant_id": "0b6f…", "currency": "PHP",
"owed_minor": 96500, "owed": "965.00", "available_for_payout_minor": 96500 }
Their payments — GET /v1/hub/sub-merchants/{id}/payments?status=paid&limit=50&offset=0
Payments
Start a payment — POST /v1/hub/payments
{
"province_code": "0354",
"business_id": 4242,
"amount": "150.50",
"caller_ref": "ORDER-1001",
"description": "2 boxes of tibok-tibok",
"metadata": { "order_id": 1001 }
}
Identify the business with sub_merchant_id, or province_code +
business_id. channel defaults to hopp (Omnipay's hosted payment page);
qr is refused until Omnipay issues the Collection API token.
caller_ref is your order id. Sending the same caller_ref again returns the
same payment (200) instead of creating a second one, so retries are safe.
The same caller_ref with a different business or amount is a 409.
201:
{
"payment": {
"reference": "OP7K2M9Q4R8T1V6X",
"sub_merchant_id": "0b6f…",
"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",
"caller_ref": "ORDER-1001",
"created_at": "…",
"paid_at": null
},
"created": true
}
Send the customer to payment_url. The reference is what ties the money to
this business: it goes to Omnipay as the order number. Omnipay's credit
notification does not echo it back yet, so until it does, staff confirm each
hosted-page credit against its reference on the dashboard (Omnipay events →
Needs matching). QR payments will match automatically by VIN.
Check a payment — GET /v1/hub/payments/{reference}
status is one of:
| status | meaning |
|---|---|
pending |
waiting for the customer to pay |
paid |
money arrived and was credited to the business (fee_minor, net_minor set) |
review |
money arrived but something is off (wrong amount, arrived late); staff decide on the dashboard |
expired, cancelled, failed |
no money will be credited |
Poll this after the customer returns from the payment page. Treat only paid
as paid.
Errors
{ "error": "sub_merchant_inactive", "message": "sub-merchant is pending; only active sub-merchants can take payments" }
| HTTP | error |
when |
|---|---|---|
| 400 | invalid_request (with fields), invalid_amount, invalid_json, invalid_sub_merchant, invalid_payment |
bad input |
| 401 | missing_hmac_authorization, hmac_signature_mismatch, hmac_timestamp_skew, … |
signing |
| 404 | not_found, sub_merchant_not_found |
unknown id or reference |
| 409 | caller_ref_conflict |
same order id, different business or amount |
| 422 | sub_merchant_inactive, channel_unavailable |
business not active; channel not set up |
Not in this API, on purpose
Activating or suspending a business, fees, payout minimums, and anything that
moves money out (payout requests and approvals) are dashboard-only. Through
/v1/hub a key can register businesses and start payments, but cannot redirect
or release anyone's money.
The older /v1/payout and /v1/settle routes are a different matter: they
accept the same HMAC keys and do send transfers. Until keys are scoped to the
routes they need, keep every key in OMNIPAY_HMAC_CALLERS as secret as the
money itself.