HTP Developer

Integrate

Sign in with HTP

Log users in with OpenID Connect and get the sub you charge and pay.

Payments identify users only by their OIDC sub. Integrate Sign in with HTP first and store each user's sub.

Endpoints

Use discovery to configure your OIDC library:

http
GET /.well-known/openid-configuration
Purpose Path
Authorization /oauth2/authorize
Token /oauth2/token
User info /oauth2/userinfo
JWKS /oauth2/jwks
Revoke /oauth2/revoke

Authorization code flow with PKCE S256 (required for SPA/native, recommended for web). ID tokens are signed RS256. Client authentication: client_secret_basic (recommended), client_secret_post, or none for public clients.

Scopes

Scope Claims
openid (required) sub
profile name, given_name, family_name, nickname, picture, gender, birthdate, updated_at
email email, email_verified — needs review
phone phone_number, phone_number_verified — needs review
offline_access Returns a refresh_token

Open platform apps get openid profile offline_access by default.

Flow

http
GET /oauth2/authorize
    ?response_type=code
    &client_id=<client_id>
    &redirect_uri=https%3A%2F%2Fshop.example.com%2Fauth%2Fhtp%2Fcallback
    &scope=openid%20profile%20offline_access
    &state=<state>
    &nonce=<nonce>
    &code_challenge=<code_challenge>
    &code_challenge_method=S256

On the callback, check state and iss, then exchange the code (valid once, for 5 minutes):

bash
curl -X POST /oauth2/token \
  -u "<client_id>:<client_secret>" \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=https://shop.example.com/auth/htp/callback \
  -d code_verifier=<code_verifier>

Validate the id_token (signature from JWKS, iss, aud = your client_id, exp, nonce), then read sub.

The sub is pairwise

  • All apps of one developer receive the same sub for a user, so you can share users across your apps.
  • Different developers get different subs for the same person — users cannot be correlated across developers.
  • The sub never changes. Store it with your user record and pass it as payer_sub / payee_sub.

Users can revoke access

In the HTP App, users can remove your app under Authorized apps. After that, refresh tokens and userinfo stop working and you can no longer charge or pay that user (USER_NOT_AUTHORIZED) until they sign in again.

Sandbox apps

Before your app is published, only you and its test users can sign in; anyone else gets access_denied. The login screen marks unreviewed apps to users.

← PreviousOrders & reconciliationNext →Authentication