How to register your own HitPay OAuth app
Register an OAuth app with HitPay and connect it to Tenklo
This guide shows you how to register your own app with HitPay to obtain your OAuth credentials (client id & secret). These are required to let your users grant your app access to their HitPay business.
Sign in to the HitPay dashboard
Sign in to the HitPay dashboard with an account that is an Owner or Admin of the business that will own the app.
To test against HitPay's sandbox, repeat this guide in the HitPay sandbox dashboard. Sandbox apps have their own client ID and secret, so create a separate Tenklo integration for them and select sandbox.hit-pay.com as the environment when connecting. The same applies to staging: use the HitPay staging dashboard and select staging.hit-pay.com.
- Go to Payments -> Developers and open the App Builder tab.
- Click New App.
- Fill in the App Name and optionally the Developer website and an icon.
- Under Redirect URIs, add the Tenklo callback URL:
https://api.tenklo.dev/oauth/callback. - Choose the Availability: Private limits the app to your own business, Public lets other HitPay businesses connect.
- Click Create.
Copy the Client ID and the Client Secret. The secret is only shown once; if you lose it, use Regenerate Secret on the app.
When configuring the integration in Tenklo, add the scopes your app needs. Available scopes are business:read, payments, commerce, and customer, plus their granular variants (e.g. payments:read, payments:refund). A parent scope such as payments also grants all of its payments:* children.
New apps can use business:read, payments, and commerce (and their children). HitPay silently drops any other scope the app hasn't been granted, so request access to customer scopes from HitPay before relying on them.
Pre-set the environment (recommended)
Your credentials only work with one HitPay environment, so set it when you create the connect session instead of asking users to pick it. The Connect UI then hides the Environment field:
{
"integrations_config_defaults": {
"<INTEGRATION-ID>": {
"connection_config": {
"environment": "hit-pay.com"
}
}
}
}Use hit-pay.com for production, sandbox.hit-pay.com for sandbox, or staging.hit-pay.com for staging, matching the credentials of <INTEGRATION-ID>.
Follow the Quickstart to connect your first account.
Good to know
- Each Tenklo integration holds one set of credentials. Use one integration per HitPay environment, and choose the matching environment when connecting.
- Only business Owners and Admins can authorize a connection. During authorization, the user picks which business to connect.
- Access and refresh tokens are valid for one year. Each refresh issues a new refresh token.
For more details, see the HitPay OAuth documentation.