Authentication

TropiPay's API distinguishes between two main authentication contexts depending on the action to be performed:

1. Application-Level Authentication (Server-to-Server): Used for operations your application performs on its own behalf. This is the most common method and uses an API key and secret to obtain a bearer token. This flow is ideal for automated processes running on your backend.

2. User-Level Authentication: Required for actions that need explicit consent from a user, such as operations involving their personal balance or biometric confirmations. This flow typically involves redirecting the user to TropiPay to authorize the action.

This document primarily focuses on Application-Level Authentication.

TropiPay uses API keys to authenticate server-to-server requests. You can view and manage your API keys in the TropiPay Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Bearer Authentication. Provide your API key as the bearer token value.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Base URL

https://sandbox.tropipay.me/api/v3

Request Format

• All endpoints accept and return data in JSON format
• Dates are in ISO 8601 format (UTC)
• Amounts are in cents (100 = $1.00)
• Content-Type: application/json

Required Headers

Content-Type: application/json
Authorization: Bearer <access_token>
X-Device-Id: <device_id>  // Optional, required for biometric operations

Obtain Access Token

To authenticate with the TropiPay API, you first need to obtain an access token using your application credentials.

Request

POST/access/token

curl -X POST https://sandbox.tropipay.me/api/v3/access/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials"
  }'

Parameters

Parameter	Type	Required	Description
client_id	string	Yes	Your application's client ID
client_secret	string	Yes	Your application's client secret
grant_type	string	Yes	Must be client_credentials

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJ5b3VyX2NsaWVudF9pZCIsImlhdCI6MTYzOTc0NDgwMCwiZXhwIjoxNjM5ODMxMjAwfQ.example_signature",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "read write"
}

Response Parameters

Parameter	Type	Description
access_token	string	The access token to use for API requests
token_type	string	Always "Bearer"
expires_in	integer	Token expiration time in seconds
scope	string	Granted permissions

Using the Access Token

Include the access token in the Authorization header of all API requests:

curl -X GET https://sandbox.tropipay.me/api/v3/users/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Error Responses

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credentials",
    "message": "Invalid client credentials"
  }
}

Security Best Practices

• Keep your API keys secure and never expose them in client-side code
• Use HTTPS for all API requests
• Rotate your API keys regularly
• Monitor your API usage for unusual activity
• Store credentials securely using environment variables or secure vaults

Rate Limiting

API requests are subject to rate limiting. If you exceed the rate limit, you'll receive a 429 Too Many Requests response. The response will include headers indicating your current rate limit status:

• X-RateLimit-Limit: The maximum number of requests allowed per time window
• X-RateLimit-Remaining: The number of requests remaining in the current time window
• X-RateLimit-Reset: The time when the rate limit resets (Unix timestamp)