Authentication

The Localpayment API uses OAuth 2.0 for authentication. To access protected resources, you need to obtain an access token and include it in the request using the Authorization header with the Bearer scheme.

Security

For both environments, it is imperative that all API requests adhere to the following security practices:

HTTPS Protocol: All communication with the Localpayment API must occur over HTTPS. This ensures that data transmitted between your server and our API is encrypted and protected from interception.
Server-Side Requests: API requests must originate from your secure server environment. Requests from client-side code (e.g., browser-based JavaScript) are strictly prohibited. This is crucial for protecting your API credentials and preventing unauthorized access.
IP Whitelisting: Your server's IP address must be added to the whitelist within the Localpayment dashboard to allow API calls. Without this step, requests to the API will be blocked for security reasons.

Adhering to these guidelines is essential for maintaining the security and integrity of your integration with the Localpayment API. Failure to comply may result in service disruption or security vulnerabilities.

Obtaining an Access Token

To generate an access token, send a request with the username and password provided by Localpayment to the authentication endpoint:

Access Token Request

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"
}

const url = 'https://api.stage.localpayment.com/api/token/';
const options = {
  method: 'POST',
  headers: {accept: 'application/json', 'content-type': 'application/json'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'

url = URI("https://api.stage.localpayment.com/api/token/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.stage.localpayment.com/api/token/', [
  'headers' => [
    'accept' => 'application/json',
    'content-type' => 'application/json',
  ],
]);

echo $response->getBody();

import requests

url = "https://api.stage.localpayment.com/api/token/"

headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.post(url, headers=headers)

print(response.text)

Access Token Response

A successful response will return a JSON object containing the access and refresh token.

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNTMxOTkyOSwianRpIjoiZWUxMDE3MTUwY2JhNGM1NTg0MjYyZmRkZTdiOThiNGQiLCJ1c2VyX2lkIjoxMDAwLCJzdXBlcnVzZXIiOnRydWUsImlzX3N0YWZmIjp0cnVlLCJybaCIsImV4cCI62xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkFMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZGUiOiJBNzaW9uTEwiLCJwZXJtaXcyI6W119.6siymomkQ72yMvHGU9sMCO4h-cxpNgQXor",
  "access": "eyJ0eXAiOiJKV1QiLCJhJIUzI1NiJ9.eyJ0b2tlbl90eXBlIbGciOijoiYWNjZXNzIiwiZXhwIjoxNzM1MjMzODI5LCJqdGkiOiJiMDRmNzQ3YWEjOCIsIn4Mjg0YjM0YmMwN2Y4ZjVkOWM0NWFVzZXJfaWQiOjEwMDAsInN1cGVydXNlciI6dHJ1ZSwiaXNfc3RhZmYiOnRy3VudHJpZXMiOljpbIkFsiQUxMIl0sImNvbXBhbnkiOiJBTEwiLCJjbGllbnRfY29kZSI6IkFMTCIsInBlcm1pc3Npb25zIjpdWUsInJvbGVzIMTCJdLlqEnH7GrECJjbbXX0.sWOLKFxCcXQkUcPvTjYceXBp39hDF3-Snc"
}

access: The access token to be used in API requests.
refresh: A token used to obtain a new access token once it expires.

Using the Access Token

Include the access token in the Authorization header of your API requests as a Bearer token:

Authorization: Bearer eyJ...

Token Expiration

Access tokens obtained from this endpoint have a limited lifespan of 5 minutes to ensure security. After this period, the token will no longer be valid for authenticating API requests.

Default Expiration: Access tokens generated through this endpoint typically expire after 5 minutes (300 seconds).

If an access token is expired or invalid, the API will return a 401 Unauthorized response:

{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid",
  "messages": [
    {
      "token_class": "AccessToken",
      "token_type": "access",
      "message": "Token is invalid or expired"
    }
  ]
}

In such case, request a new token using the refresh token or re-authenticate if necessary.

Refreshing the Access Token

Once the access token expires, you can use the refresh token to obtain a new one. Generate a token only when the previous one has expired, there is no need to generate a new one with each call.

The refresh token has a lifetime of 24 hours. After this time, you will need to authenticate again by obtaining a new access token.

Refresh token Request

Send a POST request to the refresh token endpoint sending the refresh token value:

curl --request POST \
  --url https://api.stage.localpayment.com/api/token/refresh/ \
  --header 'Accept: application/json, text/html' \
  --header 'Content-Type: application/json' \
  --data '{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNTMxOTkyOSwianRpIjoiZWUxMDE3MTUwY2JhNGM1NTg0MjYyZmRkZTdiOThiNGQiLCJ1c2VyX2lkIjoxMDAwLCJzdXBlcnVzZXIiOnRydWUsImlzX3N0YWZmIjp0cnVlLCJybaCIsImV4cCI62xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkFMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZGUiOiJBNzaW9uTEwiLCJwZXJtaXcyI6W119.6siymomkQ72yMvHGU9sMCO4h-cxpNgQXor"
}'

const url = 'https://api.stage.localpayment.com/api/token/refresh/';
const options = {
  method: 'POST',
  headers: {accept: 'application/json', 'content-type': 'application/json'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'

url = URI("https://api.stage.localpayment.com/api/token/refresh/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.stage.localpayment.com/api/token/refresh/', [
  'headers' => [
    'accept' => 'application/json',
    'content-type' => 'application/json',
  ],
]);

echo $response->getBody();

import requests

url = "https://api.stage.localpayment.com/api/token/refresh/"

headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.post(url, headers=headers)

print(response.text)

Refresh token Response

The new access token should be used for subsequent requests, and the new refresh token should be stored for future use.

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNTMxOTkyOSwianRpIjoiZWUxMDE3MTUwY2JhNGM1NTg0MjYyZmRkZTdiOThiNGQiLCJ1c2VyX2lkIjoxMDAwLCJzdXBlcnVzZXIiOnRydWUsImlzX3N0YWZmIjp0cnVlLCJybaCIsImV4cCI62xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkFMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZGUiOiJBNzaW9uTEwiLCJwZXJtaXcyI6W119.6siymomkQ72yMvHGU9sMCO4h-cxpNgQXor",
  "access": "eyJ0eXAiOiJKV1QiLCJhbeyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiGciOiJIUzI1NiJ9.ZXhwIjoxNzM1MjM1MTk1LCJqdGkiOiI3MzBiYTdiMzMyMGU0NWU2ODk4ZGRjNWVlODY1YzEyNSIsInVzZXJfaWQiOjEwMDAsdXNlciI6dHJ1ZSwiaXNfc3RInN1cGVyhZmYiOnRydWUsIm90cCI6MTExMTExLCJyb2xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkGUiOiJBTEwiLCJwZXJtaXNzaW9ucMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZyI6W119.peiX9q9Vw72UKs8LCE3C3VSq2vaQm4Gq962gsSTm4Bn0"
}

The new access token should be used for subsequent requests, and the new refresh token should be stored for future use.

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNTMxOTkyOSwianRpIjoiZWUxMDE3MTUwY2JhNGM1NTg0MjYyZmRkZTdiOThiNGQiLCJ1c2VyX2lkIjoxMDAwLCJzdXBlcnVzZXIiOnRydWUsImlzX3N0YWZmIjp0cnVlLCJybaCIsImV4cCI62xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkFMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZGUiOiJBNzaW9uTEwiLCJwZXJtaXcyI6W119.6siymomkQ72yMvHGU9sMCO4h-cxpNgQXor",
  "access": "eyJ0eXAiOiJKV1QiLCJhbeyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiGciOiJIUzI1NiJ9.ZXhwIjoxNzM1MjM1MTk1LCJqdGkiOiI3MzBiYTdiMzMyMGU0NWU2ODk4ZGRjNWVlODY1YzEyNSIsInVzZXJfaWQiOjEwMDAsdXNlciI6dHJ1ZSwiaXNfc3RInN1cGVyhZmYiOnRydWUsIm90cCI6MTExMTExLCJyb2xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkGUiOiJBTEwiLCJwZXJtaXNzaW9ucMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZyI6W119.peiX9q9Vw72UKs8LCE3C3VSq2vaQm4Gq962gsSTm4Bn0"
}