Authentication

Pincode APIs use OAuth 2.0 to authenticate clients when they are accessing any resources.
The client is expected to interact with /token endpoint:

1. The Client makes a POST request to the OAuth Server
2. The OAuth Server issues the Access Token immediately and responds to the client
3. The Client caches the token
4. The Client is expected to use this token as authentication header
5. Upon receiving a 401/412 status code (i.e. token/session expired) the client is expected to hit the /token endpoint, with the refresh_token to obtain a new token.

OAuth Endpoints:

Staging: https://stg-identitymanager.phonepe.com/
Production: https://identitymanager.phonepe.com/

Token Fetch

To get a valid token for making any Pincode API call, you will have to follow the steps mentioned below

Resource: POST /olympus/im/v1/oauth/token

Parameters for the API

Parameter	Type	Description
client_id	String	Received via mail from PhonePe
client_secret	String	Received via mail from PhonePe
grant_type	String	client_credentials (This static value needs to be sent)

Sample request:

BashPython

curl --request POST \
--url 'https://identitymanager.phonepe.com/olympus/im/v1/oauth/token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'client_secret=test&client_id=testid&grant_type=client_credentials'

import requests
url = 'https://identitymanager.phonepe.com/olympus/im/v1/oauth/token'
headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/x-www-form-urlencoded',
}
data = {
    'client_secret': 'test',
    'client_id': 'testid',
    'grant_type': 'client_credentials',
}
response = requests.post(url, headers=headers, data=data)

Response:

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "O-Bearer",
  "expires_in": 86400,
  "expires_at": 1719167970316,
  "issued_at": 1719167883916
}

Field Explanations:

Field	Type	Description
access_token	String	token to be used in the next set of API calls
refresh_token	String	token to be used during refresh flows
expires_in	Integer	seconds after which the token will expire
expires_at	Long	epoch timestamp in milliseconds when the token will expire
issued_at	Long	epoch timestamp when the token was issued

Token Refresh

The access_token issued in the previous call are short lived (less than a day). Upon sending an expired token to any Pincode API, you will receive a 401/412 HTTP status response.
After receiving a 401/412 status code (i.e. token/session expired) hit the /token endpoint again to get the latest token.

Tip

This API can be called proactively (before the expiry: expires_at field indicates the same) to avoid latency spikes of refresh.

Resource: POST /olympus/im/v1/oauth/token

Parameter	Type	Description
client_id	String	Received via mail from PhonePe
client_secret	String	Received via mail from PhonePe
grant_type	String	refresh_token (This static value needs to be sent)
token	String	Value of access_token received in the fetch token response
refresh_token	String	Value of refresh_token received in the fetch token response

Sample Request:

BashPython

curl --request POST \
--url 'https://identitymanager.phonepe.com/olympus/im/v1/oauth/token \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'client_secret=test&client_id=testid&grant_type=client_credentials&token=1231239skdjhf28dh&refresh_token=123ndy21e1jjndk'

import requests

url = 'https://identitymanager.phonepe.com/olympus/im/v1/oauth/token'
headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/x-www-form-urlencoded',
}
data = {
    'client_secret': 'test',
    'client_id': 'testid',
    'grant_type': 'client_credentials',
    'token': '1231239skdjhf28dh',
    'refresh_token': '123ndy21e1jjndk'
}
response = requests.post(url, headers=headers, data=data)

Response will be the same as mentioned before.

Receiving Client Details:

After validating your request, you will receive an email from the Pincode team with the required details

Requests to Pincode:

The token received from the previous section, is to be used in headers for every single API call made to Pincode.
This is how you can make a request to Pincode, for the rest of the APIs mentioned in the document.:

BashPython

curl --request POST \
--url 'https://<pincode_endpoint>/<api_path>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization:<token_type> <token>' \ // Note that token_type will something like O-Bearer
--data '<payload_json>'

import requests

url = f'https://{pincode_endpoint}/{api_path}'
headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}
data = payload
response = requests.post(url, headers=headers, data=data)