iPOSpays Authentication Token API

iPOSpays Authentication Token API Guide

This guide explains how to generate and refresh an authentication token used to securely interact with iPOSpays APIs. The token must be included in the request header when calling any protected endpoints such as payments, refunds, or transaction status APIs.

Supported APIs

This API can be used to generate and refresh an authentication token in:

  1. Transact API (opens in a new tab) (V3 End Point)

  2. Batch Report (opens in a new tab)

  3. Recurring Payments API (opens in a new tab)

  4. Merchant Onboarding API (opens in a new tab)

Generate Auth Token

Purpose

Use this endpoint to generate a new JWT-based access token using your API Key, Secret Key, and Scope.

End Points

How to Generate API and Secret Keys

The apiKey and secretKey can be generated from the iPOSpays portal using an ISO, Agent Office, and Merchant Admin account. These keys are required for authentication.

Watch This Video for a Visual Walkthrough of the Steps

Steps to Generate Keys on iPOSpays

The steps to generate the keys remain the same for all three users: ISO, Agent Office, and Merchant Admin

  1. Log in to the iPOSpays portal using an ISO Admin account

  2. Go to: Settings → Generate API & Secret Key

  3. Under the Generate Keys section:

    • Click Generate Keys

    • Click the Copy icon to copy the keys

    • Secret Key is masked by default

  4. Click Reset Secret Key if you wish to regenerate the Secret Key

  1. Use the generated API and Secret Key for API authentication

API Access Details

API access is role-based and determined by the generated API Key and Secret Key. Different scopes are available for Merchant-level and ISO-level credentials.

Merchant-level API Key and Secret Key:

  • Supported scopes: PaymentTokenization, Recurring, BatchReport

ISO-level API Key and Secret Key:

  • Supported scope: ExternalApi, PaymentTokenization, Recurring, BatchReport

Agent Office Admin-level API Key and Secret Key:

  • Supported scope: ExternalApi

Scope Descriptions

  • PaymentTokenization – Access to iPOS Transact (v3) APIs and transaction status APIs

  • Recurring – Access to recurring payment functionality

  • BatchReport – Access to closed batch reports

  • ExternalApi – Access to merchant onboarding APIs

Sample Header Request

{
  "apiKey": "your_api_key_here",           // Required: Your assigned API key
  "secretKey": "your_secret_key_here",     // Required: Your assigned secret key
  "jwtTokenExpiryMinutes" : 1000 -> user can set expiry time of the token by their own, Integer Value, expiry value should not be more than 24 hours and minimum value should not be less than 30 minutes
}
Response 
{
  "responseCode": "00",
  "responseMessage": "Success",
  "createdDt": "1749532846158",
  "token": "eyJhbGciOiJSUzI1NiJ9.eyJzY29wZSI6InBheW1lbnRUb2tlbml6ZSIsInVuaXF1ZUlkIjoiNzQxYzFiM2YtMTUyYS0xMWYwLWI3YTMtMTZhOTc1NjBiMjc1IiwiaWF0IjoxNzQ0ODA3NzAyLCJleHAiOjE3NDQ4OTQxMDJ9.WUXSxe3e4fMY43qmkVC5wpzzpnj78G590E-tG9O1yZD7RhCu2L2giQOSb6qrfpH6w11iP-n2_ZfpZXu0He66Rge-6FyjKAW0wE5Dz-VLrFsZWxSHaIQLMbm900BPqNo_hBhstfESbO_UA-4uQItfBF5lg8PD1cDhS5K5N6tp1yFOEEflQOUysxvven8rLcg2XnimWJDaH-d-i6-tN9RgFgZCj-ZgAfqW4U3NH3MjcvlCASA-mTTnkJ_PvNBC9HRXBl862-Tgzb9AvZVYgc8qypIWD3QkROpwUmlXoCHfIQFlyQFSPp9rcHiFXy73RrMTppmDMzgsPWpzNKAuXpw4bw"
}

Auth Token Error Responses

{
  "errorCode": "AUTH_ERR_001",
  "errorMessage": "API Key is required."
}
 
{
  "errorCode": "AUTH_ERR_002",
  "errorMessage": "Secret Key is required."
}
 
{
  "errorCode": "AUTH_ERR_003",
  "errorMessage": "Scope is required."
}
 
{
  "errorCode": "AUTH_ERR_004",
  "errorMessage": "Invalid Credentials, Please Contact Support Team."
}
 
{
  "errorCode": "AUTH_ERR_005",
  "errorMessage": "Invalid scope provided. Please use a valid scope."
}
 
{
  "errorCode": "AUTH_ERR_011",
  "errorMessage": "Minimum expiry time cannot be less than 30 minutes."
}
 
{
  "errorCode": "AUTH_ERR_012",
  "errorMessage": "Maximum expiry time cannot be more than 24 hours."
}

Refresh Auth Token

Purpose

Use this endpoint to refresh your existing token before it expires. Tokens typically have a short lifespan for security purposes.

End Points

Post head request

{ 
  "refreshToken": true ,
  "token" : "eyJhbGciOiJSUzI1NiJ9.eyJzY29wZSI6InBheW1lbnRUb2tlbml6ZSIsInVuaXF1ZUlkIjoiNzQxYzFiM2YtMTUyYS0xMWYwLWI3YTMtMTZhOTc1NjBiMjc1IiwiaWF0IjoxNzQ0MjkxMzEzLCJleHAiOjE3NDQzNzc3MTN9.E2Rrf9D4ZvM9t-llUAPttVR2_paCxXnYW1rL0z1-g3DnekRsBJLlbT3efm0ecKnO6PZI1AXJNrMx3tM-0cjGvSOiT1-PeqRMSWib7c2yxqN-fkM9gYQlSpvwMPY5GZ5X2JJ2XAt5f4KwyzVsYoFRYutf2ADRj8f_gPFfouyrQH-v0EjGCe1qx1lr_IupXPDfjYzys9w1MNMqUTp9ZJEt8hav5NFFBddQf_Tf5sfynmhAP2DB_UgaINhS16KzQG3mpGzMk6NqWk8iCa2HbTUJBVJB7ZQmoaKsW95mUaXwSwR2w9pMUeM0ME1P-VHDMjQ9RbA86MDoHi1DUm-3OwJkvA"
}
Sample Success Response
{
  "responseCode": "00",
  "responseMessage": "Success",
  "createdDt": "1749532846158",
  "token": "eyJhbGciOiJSUzI1NiJ9.eyJzY29wZSI6InBheW1lbnRUb2tlbml6ZSIsInVuaXF1ZUlkIjoiNzQxYzFiM2YtMTUyYS0xMWYwLWI3YTMtMTZhOTc1NjBiMjc1IiwiaWF0IjoxNzQ0ODA4MDg1LCJleHAiOjE3NDQ4OTQ0ODV9.APh5_tkBTT62dK783mzIVVdvXJxaYySGU20ZwWNBwu9lIGZ6hJ-zXEXCuPg6cTjbOSZViu3OEvsGvlrEN_nrnqgNIqYRIXmgtz6VS4BVp5yfP_XrMviO1F184AZIK_UlC598O_nKYMcjg-1wTaQQY7By4SCO0RFVXeN4YFm7X4YOAz8g3-Y9LCTpNXKftjEl8RbTkkWsKQjGFuNhTcnrJFSmY0AnPban8v4SUtGdH7nKWXsXwrV4HCJ6AipWcJ1XULwm521VDyYw4Y-ldGJ7kciOi-Oho7sDNDi0HeHwTuCQvSj2SfRRNXiXDhDDveU6-Sw3DJOQRre8LYNtabRzdg"
}

Refresh Token Error Responses

{
  "errorCode": "AUTH_ERR_006",
  "errorMessage": "Invalid Token, Please try with a Valid Token."
}
 
{
  "errorCode": "AUTH_ERR_007",
  "errorMessage": "Invalid Token, Please try with a Valid Token."
}
 
{
  "errorCode": "AUTH_ERR_008",
  "errorMessage": "Invalid Signature."
}
 
{
  "errorCode": "AUTH_ERR_009",
  "errorMessage" :  "Refresh Token needs to be true in the Header."
}

  • Always keep your API Key and Secret Key confidential.

  • Ensure tokens are refreshed before expiration to avoid authentication errors.

  • Use only authorized scopes based on your integration level (e.g., PaymentTokenization).

Error Codes and Messages