Authenticate with the Hello Clever API

Learn how to include your app-id and secret-key on every Hello Clever API request, and when the v1 payment gateway link needs an additional access token.

Every request to the Hello Clever API, across the v1, v2, v3, Card, and Cashback APIs, is authenticated with two headers: app-id and secret-key. One endpoint, the v1 hosted payment gateway link, additionally requires a short-lived access token generated from those same credentials. This page shows you how to get your credentials and use them correctly.

Before you start

You need an active Hello Clever merchant account before you can generate credentials. Follow the Integration Keys guide to create a Payments Account and retrieve your app-id and secret-key.

Authenticate your requests

Include your app-id and secret-key as headers on every request:

app-id · string · required

Your application identifier, issued from the Hello Clever Merchant Dashboard.

secret-key · string · required

The secret key associated with your app-id. Never expose this in client-side code.

Example request

curl --request GET \
  --url https://api.cleverhub.co/api/v2/payins/payin_methods \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

This header pair authenticates every endpoint across the v1, v2, v3, Card, and Cashback APIs, with one exception described below.

Use the sandbox base URL and sandbox credentials when developing or testing. Switch to the production base URL and credentials only when you are ready to go live. See the API overview for the base URL of each API version.

Special case: v1 payment gateway link access token

Creating a hosted payment gateway link with POST /v1/payment_gateways/create_payment requires an additional access-token header. Generate one by calling the access token endpoint with your app-id and secret-key headers:

Request

curl --request GET \
  --url https://api-merchant.helloclever.co/api/v1/payment_gateways/access_token \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

Pass the returned value in the access-token header when you create the payment gateway link:

curl --request POST \
  --url https://api-merchant.helloclever.co/api/v1/payment_gateways/create_payment \
  --header 'access-token: eyJhbGciOi...' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'

expires_in is in seconds: the token is valid for 3600 seconds (1 hour). When it expires, request a new one and retry. You only need this token for the payment gateway link endpoint; every other v1 endpoint continues to use your app-id and secret-key headers directly. Refer to the v1 API reference for full details on the payment gateway link endpoints.

Security best practices

Never embed your secret-key in client-side code, mobile apps, or any publicly accessible location. It must remain on your server at all times.

• Store credentials in environment variables or a secrets manager, not in source code or configuration files checked into version control.
• Rotate your secret-key periodically to limit the blast radius of a potential leak.
• Use HTTPS for all API calls to ensure credentials are transmitted over an encrypted connection.
• Scope access by creating separate Payments Accounts (and therefore separate credentials) for different environments, currencies, or applications.
• Monitor for unexpected usage in the Merchant Dashboard to detect potential credential misuse early.
• Don’t confuse secret-key with your Webhook Secret Key. Your secret-key authenticates outgoing requests you make to the Hello Clever API. Your Webhook Secret Key is a separate credential Hello Clever uses to sign incoming webhook payloads sent to your server. See Webhooks for how to verify it.