One Pay Developer docs

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 pending and cannot take payments until an admin checks it and activates it on the dashboard. The API cannot set status, fees or payout minimums; sending them is a 400.
  • 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.