Authentication Overview

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.

OAuth 2.0

Industry-standard Bearer token authentication

Short-lived Tokens

60-minute access tokens for enhanced security


Security Requirements

🔒

Critical Security Requirements

Follow these practices to ensure secure API integration.

HTTPS Encryption

All API communication must use HTTPS to protect data in transit

Server-Side Only

API requests must originate from secure server environments only

IP Whitelisting

Configure IP whitelisting in dashboard to authorize API calls

Secure Credential Storage

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:

Access Token

60 minutes

Used for API requests

Short lifetime for security

Refresh Token

120 minutes

Used to obtain new access tokens

Long lifetime for convenience

Token Lifecycle

  1. Get tokens: Request an access and refresh token pair with Get Access Token.
  2. Reuse the access token: Send the same access token in every request while it is valid.
  3. Renew on expiry: When the access token expires or you receive a 401 Unauthorized response, request a new pair with Get Access Token.
  4. 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

One Token Pair per Integration

Keep a single token pair per user and integration, shared across all your processes and workers.

Replace the Full Pair

After every token request or refresh, store both the new access token and the new refresh token.

Avoid Parallel Logins

Don't request tokens in parallel with the same user. Each new token request invalidates earlier refresh tokens.

Don't Retry a Failed Refresh

If a refresh returns 401, request a new token with Get Access Token instead of retrying the same refresh token.


Error Handling

401 Unauthorized

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.

401 Unauthorized

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.