One Pay Developer docs

One Pay — Merchant Login API

A JSON, token-based login for merchant portal users — the people who run a business on One Pay. A mobile app or a custom (non-hosted) dashboard signs a user in with their email and password and receives a Bearer token, which it sends on every later request.

This is the programmatic counterpart to the hosted portal at https://pay.pod.com.ph/portal. It uses the same accounts and the same lockout, but returns JSON and a token instead of setting a browser cookie.

Base URL https://pay.pod.com.ph/v1/merchant
Auth Authorization: Bearer <token> (from login)
Content type application/json
Token lifetime 30 days, unless revoked by logout or a password reset

These are merchant users, not the /v1/hub API keys. Hub keys (HMAC) are for a store's backend to create payments; this login is for a person using an app. See SUBMERCHANT-INTEGRATION.md for the hub API.


How a user gets an account

Accounts are created by One Pay staff, not self-service. An admin invites a person from the merchant's dashboard page; the person receives a one-time set-password link (valid 72 hours) and chooses their password. After that they can sign in through this API or the hosted portal. "Forgot password" is available on the hosted portal (/portal/forgot).


1. Log in — POST /v1/merchant/login

POST /v1/merchant/login
Content-Type: application/json

{ "email": "[email protected]", "password": "their-password" }

200 OK — a token and who it belongs to:

{
  "token": "P7mR…opaque…s9",
  "token_type": "Bearer",
  "expires_at": "2026-10-29T08:15:00.000Z",
  "expires_in": 2592000,
  "user":  { "id": "9c…", "name": "Isabel Manalo", "email": "[email protected]" },
  "sub_merchant": {
    "id": "99f45a3f-699c-4851-8c95-ae91d91eab2e",
    "name": "Tibok-Tibok ni Lola Ising",
    "status": "active",
    "fee_bps": 200,
    "fee_fixed_minor": 0,
    "currency": "PHP"
  }
}
  • token — store it securely (Keychain / Keystore / secure storage), never in plain local storage or a logfile. Treat it like a password: anyone holding it is signed in as that user until it expires or is revoked.
  • expires_at / expires_in — when the token stops working (ISO-8601, and seconds from now). Re-run login to get a fresh one.
  • sub_merchant.status — active, pending, or suspended. A user can sign in whatever the status; a pending/suspended business just can't take new payments yet.

Errors

HTTP error when
400 invalid_request body isn't JSON, or email/password missing
401 invalid_credentials wrong email or password, or the account isn't set up
429 too_many_attempts too many tries from this IP — wait 15 minutes

The 401 message is deliberately the same for a wrong password and an unknown email, so the endpoint can't be used to discover who has an account. After 5 wrong passwords in a row an account is locked for 15 minutes.


2. The signed-in user — GET /v1/merchant/me

Send the token to confirm it's valid and read the current user + business.

GET /v1/merchant/me
Authorization: Bearer P7mR…s9

200 OK

{
  "user": { "id": "9c…", "name": "Isabel Manalo", "email": "[email protected]" },
  "sub_merchant": { "id": "99f4…", "name": "Tibok-Tibok ni Lola Ising", "status": "active", "fee_bps": 200, "fee_fixed_minor": 0, "currency": "PHP" },
  "token": { "expires_at": "2026-10-29T08:15:00.000Z" }
}

401 invalid_token — the token is missing, expired, or revoked. Send the user back to the login screen.


3. Log out — POST /v1/merchant/logout

Revokes this token immediately (other devices' tokens keep working).

POST /v1/merchant/logout
Authorization: Bearer P7mR…s9

200 OK → { "ok": true }


Token lifecycle

  • A token lives 30 days from login, then stops working.
  • Logout revokes the token used.
  • A password reset (through the hosted portal) revokes every token and browser session that user has — so a compromised password can be shut down everywhere at once.
  • There is no refresh token yet: when a token nears expires_at, ask the user to sign in again. (Tell us if you need silent refresh and we'll add it.)

Security

  • HTTPS only. The base URL is https:// — never send credentials or tokens over plain HTTP.
  • Store the token in secure storage, not in a place other apps or logs can read.
  • This endpoint is not HMAC-signed (it is the login); the token is the only credential the other calls need.
  • Standard rate-limiting and lockout apply (see the login errors above).

Quick start (curl)

# 1) log in
TOKEN=$(curl -s https://pay.pod.com.ph/v1/merchant/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"…"}' | jq -r .token)

# 2) use the token
curl -s https://pay.pod.com.ph/v1/merchant/me \
  -H "Authorization: Bearer $TOKEN"

# 3) log out
curl -s -X POST https://pay.pod.com.ph/v1/merchant/logout \
  -H "Authorization: Bearer $TOKEN"

Error format

Every error is JSON: { "error": "<code>", "message": "<human-readable>" }. Switch on error (stable), show message (may change).

Contact

Integration support: . Tell us the platform (iOS / Android / web) and whether you need extra data endpoints (balance, payments, payouts) exposed to the token — those aren't part of this login API yet.