Authentication

1. Obtain Your API Credentials

Before starting the integration, you need to have the following two core parameters ready. In our API requests, these correspond to the appid and secret fields:

• API Key (appid): Your unique merchant identifier.
• API Secret (secret): The confidential key used for authentication. Never share or expose this key.

📥

How to get your credentials?

1. Email Notification: Once your API access is activated, the system will automatically send an official email containing your API Key and API Secret to your registered email address.
2. Merchant Dashboard: You can log into the [DogPay Merchant Dashboard] -> [API Management] page at any time to view your current API Key. For security reasons, your API Secret can be manually reset on this page.

2. Generate an Access Token

Exchange your credentials for an access_token by calling the authentication endpoint.

• Endpoint: POST /open-api/v1/auth/access_token
• Grant Type: Must be set to client_credential

# Example Request
curl -X POST "[https://prod.wavepool.global/open-api/v1/auth/access_token](https://prod.wavepool.global/open-api/v1/auth/access_token)" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type": "client_credential",
           "appid": "your_API_Key",
           "secret": "your_API_Secret"
         }'

3. Using the Token

Once you have the token, include it in the Authorization header for all subsequent HTTP requests:

⏳ Token Lifecycle & Expiration

Understanding how to manage your token's lifecycle is crucial for building a stable integration:

Validity Period

• Expiration: Tokens are valid for 2 hours (7200 seconds) from the moment they are issued.
• No Refresh Tokens: This API does not use refresh tokens. Once a token expires, you simply repeat the steps above to acquire a new one.

💡

Developer Best Practices

• Cache your Token: Store the token on your server/backend cache. Do not request a new token for every single API call, as this may trigger rate limiting.
• Proactive Refresh: We highly recommend fetching a new token roughly 5–10 minutes before the current one expires to ensure zero-downtime for your service.
• Error Handling: If an API call returns a 401 Unauthorized error, it means your token is invalid or expired. Your application should be programmed to automatically trigger the token acquisition logic and retry the request.

⚠️ Security Precautions

• No Client-Side Calls: Never hardcode your API Secret in client-side applications (such as mobile apps, browser extensions, or frontend code). The token exchange logic must strictly take place on your backend server.
• Environment Isolation: Ensure you are using the correct API Key for the corresponding environment (Sandbox vs. Production) to avoid data corruption.