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.

Generate Auth Token

Purpose

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

The apiKey and secretKey are issued by iPOSpays. If you do not have these credentials, contact your Dejavoo representative or email support@dejavoo.io. These keys are required for authentication and must be used along with the appropriate scope, which defines what type of access the token will authorize (e.g., transactions, batch reports, or card lookups).

End Points

Post head request
{
  "apiKey": "your_api_key_here",           // Required: Your assigned API key
  "secretKey": "your_secret_key_here",     // Required: Your assigned secret key
  "scope": "" // Required: Specify the API scope you are using.
              // Use "PaymentTokenization" when calling the iPOS Transact API.
              // Use "BatchReport" for retrieving closed batch reports.
              // Use "CardLookUp" for card details lookup via the CardLookUp API.
}
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."
}

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

The generated token used for transactions remains valid for 24 hours. Make sure to refresh the token daily before initiating any transactions.

Post head request
{ 
  "refreshToken": true ,
  "token" : "eyJhbGciOiJSUzI1NiJ9.eyJzY29wZSI6InBheW1lbnRUb2tlbml6ZSIsInVuaXF1ZUlkIjoiNzQxYzFiM2YtMTUyYS0xMWYwLWI3YTMtMTZhOTc1NjBiMjc1IiwiaWF0IjoxNzQ0MjkxMzEzLCJleHAiOjE3NDQzNzc3MTN9.E2Rrf9D4ZvM9t-llUAPttVR2_paCxXnYW1rL0z1-g3DnekRsBJLlbT3efm0ecKnO6PZI1AXJNrMx3tM-0cjGvSOiT1-PeqRMSWib7c2yxqN-fkM9gYQlSpvwMPY5GZ5X2JJ2XAt5f4KwyzVsYoFRYutf2ADRj8f_gPFfouyrQH-v0EjGCe1qx1lr_IupXPDfjYzys9w1MNMqUTp9ZJEt8hav5NFFBddQf_Tf5sfynmhAP2DB_UgaINhS16KzQG3mpGzMk6NqWk8iCa2HbTUJBVJB7ZQmoaKsW95mUaXwSwR2w9pMUeM0ME1P-VHDMjQ9RbA86MDoHi1DUm-3OwJkvA"
}
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