OAuth2 apps

OAuth2 lets a third-party app act on behalf of a Payer user, with the user's explicit consent and never more access than they granted. Payer runs a standard authorization-code flow with PKCE, and issues rotating refresh tokens.

Use OAuth when your app serves other people's Payer accounts. If you only need your own data, a personal access token is simpler; if you're a merchant taking payments, use a secret key.

Endpoints

The consent screen sits on its own domain, so the authorization endpoint is not on api.payer.app like the rest. Most OAuth libraries can configure themselves from the discovery document (RFC 8414) rather than from hardcoded URLs.

Registering an app

A merchant admin registers an app from the Developers page in the dashboard. Registration returns a client_id (prefixed oauthapp_) and, for confidential apps, a client_secret shown once.

The flow

1. App → generates code_verifier + code_challenge (S256)
2. App → sends the user to Payer's consent screen
3. User → approves; Payer redirects back with ?code=...&state=...
4. App → POST /oauth/token with the code + code_verifier
5. Payer → returns access_token (oat_) + refresh_token (ort_)

1 · Send the user to consent

Redirect the user to Payer's hosted authorization screen with a PKCE challenge:

https://connect.payer.app/authorize

Send it these query parameters:

response_type=code
client_id=oauthapp_...
redirect_uri=https://yourapp.com/callback
scope=balances:read transactions:read
state=<opaque csrf value>
code_challenge=<base64url(sha256(verifier))>
code_challenge_method=S256

The user reviews the requested scopes and approves or denies. Payer redirects back to your redirect_uri with ?code=...&state=... on approval, or ?error=access_denied&state=... on denial. Authorization codes are single-use and expire after 5 minutes.

2 · Exchange the code for tokens

POST /oauth/token

Authenticate the client with HTTP Basic (client_id:client_secret) or with client_id/client_secret in the body. Public apps send client_id and the code_verifier only.

curl https://api.payer.app/oauth/token \
  -u "oauthapp_...:<client_secret>" \
  -d "grant_type=authorization_code" \
  -d "code=<code from the redirect>" \
  -d "code_verifier=<original verifier>" \
  -d "redirect_uri=https://yourapp.com/callback"

{
  "access_token": "oat_...",
  "refresh_token": "ort_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "balances:read transactions:read"
}

Use the access token as a bearer token against /graphql, exactly like a PAT. It can read whatever scopes the user consented to:

curl https://api.payer.app/graphql \
  -H "Authorization: Bearer oat_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"query { balance { available } }"}'

3 · Refresh the access token

Access tokens live 1 hour. When one expires, exchange the refresh token for a new pair. Refresh is rotating: the presented refresh token and its access token are revoked, and a fresh pair is returned. Store the new refresh token; the old one is now dead.

curl https://api.payer.app/oauth/token \
  -u "oauthapp_...:<client_secret>" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=ort_..."

Refresh tokens live 60 days. If a used authorization code or a rotated refresh token is replayed, Payer revokes the whole chain issued for it, so a stolen token can't be quietly reused alongside the legitimate one.

4 · Revoke a token

POST /oauth/revoke

curl https://api.payer.app/oauth/revoke \
  -u "oauthapp_...:<client_secret>" \
  -d "token=ort_..."

Revocation always returns 200 with an empty body, never revealing whether the token existed, and revokes the token together with its linked pair.

Token summary

Errors

The token and revoke endpoints return RFC 6749 error bodies:

{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid or has expired."
}

Try it live

The playground below runs the whole flow from your browser: it builds the PKCE challenge, sends you to the real consent screen, takes the code back, and exchanges it for tokens you can then spend against /graphql. Nothing is proxied through this site, and everything you paste stays in this browser tab.

Two things to do first:

1. 1.Register an app on the Developers page in the dashboard.
2. 2.Add https://payer.mv/developers/docs/oauth to that app's redirect URIs. Redirect URIs are exact-match, and the playground shows you the value to copy.

Test and Live

An OAuth app belongs to one environment. Register it with the dashboard in sandbox mode and it exists in Test; register it in live mode and it exists in Live. The same client id is never valid in both, so the playground's Environment switch moves the consent screen and the token endpoint together:

Test runs against sandbox data with its own users and balances. In Live the consent screen signs in a real Payer user and grants real scopes, so start there with the read scopes only.