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/hubAPI 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, orsuspended. A user can sign in whatever the status; apending/suspendedbusiness 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: