Localpayment uses OAuth 2.0 Bearer token authentication to secure API access. All API requests require a valid access token included in the Authorization header. This guide provides an overview of authentication concepts and security requirements.
Secure authentication is fundamental to API integration. Localpayment's token-based authentication ensures only authorized requests can access your account data and process transactions.
Industry-standard Bearer token authentication
60-minute access tokens for enhanced security
Security Requirements
Critical Security Requirements
Follow these practices to ensure secure API integration.
All API communication must use HTTPS to protect data in transit
API requests must originate from secure server environments only
Configure IP whitelisting in dashboard to authorize API calls
Use environment variables or secret management systems
Authentication Endpoints
Manage your API authentication using these dedicated endpoints:
Quick Example
Generate Token:
curl --request POST \
--url https://api.stage.localpayment.com/api/token/ \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"username": "[email protected]",
"password": "<PASSWORD>"
}
'Use Token:
curl --request POST \
--url https://api.stage.localpayment.com/api/validation/document \
--header 'Authorization: Bearer <your_access_token>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"country": "ARG",
"document": {
"id": "1791234561009",
"type": "RUC"
}
}
'Token Expiration
Localpayment uses short-lived tokens for enhanced security:
60 minutes
Used for API requests
Short lifetime for security
120 minutes
Used to obtain new access tokens
Long lifetime for convenience
Token Lifecycle
- Get tokens: Request an access and refresh token pair with Get Access Token.
- Reuse the access token: Send the same access token in every request while it is valid.
- Renew on expiry: When the access token expires or you receive a 401 Unauthorized response, request a new pair with Get Access Token.
- Replace the stored pair: Store both new tokens and discard the previous ones.
Using the refresh endpoint
The Refresh Access Token endpoint remains available if your integration already uses it. Each successful refresh returns a new token pair, and the refresh token you sent stops working.
A new Get Access Token request also invalidates the refresh tokens issued before it for the same user and integration.
Token Management Best Practices
Keep a single token pair per user and integration, shared across all your processes and workers.
After every token request or refresh, store both the new access token and the new refresh token.
Don't request tokens in parallel with the same user. Each new token request invalidates earlier refresh tokens.
If a refresh returns 401, request a new token with Get Access Token instead of retrying the same refresh token.
Error Handling
Invalid or expired token
Solution: Request a new token with Get Access Token. If a refresh returns this error, don't retry the same refresh token.
IP not whitelisted
Get Access Token returns "Invalid IP for user. Please validate that 203.0.113.10 is whitelisted in your account settings."
Solution: Add your server IP to the whitelist in the dashboard.
