API: Authorization
- gurveer.parmar
- 1 Authorize
- 1.1.1 BASE URI
- 1.2 Authorization
- 1.2.1 HTTPS GET
- 1.2.2 URI Parameters
- 2 Grant
- 2.1.1 BASE URI
- 2.2 Authorization code grant
- 2.2.1 HTTPS POST
- 2.2.2 URI Parameters
- 2.2.3 Response Attributes
- 2.3 Client Credentials Grant
- 2.3.1 HTTPS POST
- 2.3.2 URI Parameters
- 2.3.3 Response Attributes
- 2.4 Refresh token grant
- 2.4.1 HTTPS POST
- 2.4.2 Response Attributes
- 3 Revoke
- 3.1.1 BASE URI
- 3.2 Revoke token
- 3.2.1 HTTPS DELETE
Authorize
Use your Client ID and Client Secret, along with a Basic Token in your header, to get Bearer Token needed for the header of all requests to the Customer, Plan and Transaction Services
BASE URI
https://auth.payfirma.com/oauth
Authorization
This flow generates a one-time authorization code used to obtain the OAuth access token. The authorization code is obtained by using an authorization server as an intermediary between the client (you) and the resource owner (your Merchants).
HTTPS GET
/authorize{?response_type,client_id,redirect_uri}
URI Parameters
response_type required | Value must be set to ‘code’. |
client_id required | The client identifier issued to the client during the registration process. |
redirect_uri required | URL to redirect back to after completing its interaction with the resource owner. The redirection endpoint URI must be an absolute URI. |
Example Request:
curl --include \
--header "Content-Type: application/x-www-form-urlencoded" \
"https://auth.payfirma.com/oauth/authorize?response_type="code"&client_id="aaabbbere05a7986b850b1933d91f33399"&redirect_uri="https:///www.example.com""Example Response Body:
{
'Location': 'https:///www.example.com&code=Xdfsdf82F',
}Grant
Use the authorization code from each of your merchants to get access credentials.
BASE URI
https://auth.payfirma.com/oauth
Authorization code grant
The authorization code grant type is used to obtain both access tokens and refresh tokens by presenting a one-time authorization code obtained from Payfirma’s authorization server during the authorization request.
HTTPS POST
/token{?grant_type,code,redirect_uri,state}
URI Parameters
grant_type REQUIRED | Value must be set to ‘authorization_code’. |
code REQUIRED | Short-lived and one-time authorization code, received from Payfirma’s authorization server. |
redirect_uri | URL to redirect back to after completing its interaction with the resource owner. The redirection endpoint URI must be an absolute URI. |
state | RECOMMENDED. An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery |
Response Attributes
access_token string | A Payfirma access token is a JWT format string representing an authorization issued to the client (you) from the user (the Merchant) to access their protected Payfirma resources. |
token_type string | General identifier for the OAuth token. |
refresh_token string | Refresh token is issued to the client by Payfirma authorization server and is used to obtain a new access token when the current access token becomes invalid or expires. The refresh token never expires and can be used only once. It becomes invalid when the access token is revoked. |
expires_in number | The lifetime in seconds of the access token. The default setting for the access token default is to expire in 20 minutes (1200 seconds). |
merchant_id string | Unique identifier for the merchant. |
scope string | The list of different services that have been authorized for access. |
Example Request:
curl --include \
--request POST \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Authorization: Basic "ZmM0N2E0ZGMxZWMzODFjMzIxZjk4MzEyZmUwNDQ0YzA6NjI3YWE3NTE1MzNiMW1234567890123=" \
"https://auth.payfirma.com/oauth/token?grant_type=authorization_code&code=Grf5pV&redirect_uri=https%3A%2F%2Fwww.example.com&state=xyzABC123"Example Response Body:
{
'access_token': 'eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU',
'token_type': 'Bearer',
'refresh_token': '955d8714-f1d6-49d6-830a-2d221631a2b3',
'expires_in': 1199,
'merchant_id': '01234abcde',
'scope': 'invoice ecom',
}Client Credentials Grant
The client credentials grant uses client id and client secret as an authorization grant when the authorization scope is limited to the protected resources under the control of the client. Client credentials are used as an authorization grant typically when the client is acting on its own behalf (the client is also the resource owner)
HTTPS POST
/token{?grant_type,client_id,client_secret}
URI Parameters
grant_type REQUIRED | Value must be set to refresh_token. |
client_id REQUIRED | The client identifier issued to the client during the registration process. |
client_secret REQUIRED | The client secret issued to the client during the registration process. |
Response Attributes
access_token string | A Payfirma access token is a JWT format string representing an authorization issued to the client (you) from the user (the Merchant) to access their protected Payfirma resources. |
token_type string | General identifier for the OAuth token. |
expires_in number | The lifetime in seconds of the access token. The default setting for the access token default is to expire in 20 minutes (1200 seconds). |
merchant_id string | Unique identifier for the merchant. |
scope string | The list of different services that have been authorized for access. |
Example Request:
curl --include \
--request POST \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Authorization: Basic ZmM0N2E0ZGMxZWMzODFjMzIxZjk4MzEyZmUwNDQ0YzA6NjI3YWE3NTE1MzNiMW1234567890123==" \
"https://auth.payfirma.com/oauth/token?grant_type=client_credentials&client_id=UGF5ZmlybWEgdGVzdCAwOSBjbGllbnQgSUQ%3D&client_secret=Q2xpZW50IHNlY3JldCBmb3IgUGF5ZmlybWEgdGVzdCAwOQ%3D%3D"Example Response Body:
{
'access_token': 'eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU',
'token_type': 'Bearer',
'expires_in': 1199,
'merchant_id': '01234abcde',
'scope': 'invoice ecom',
}Refresh token grant
The client can request a new access token by authenticating with the Payfirma authorization server and then presenting the refresh token.
HTTPS POST
/token{?grant_type,refresh_token,client_id,client_secret}
URI PARAMETERS |
|
|---|---|
grant_type REQUIRED | Value must be set to refresh_token. |
refresh_token REQUIRED | Refresh token is issued to the client by Payfirma authorization server and is used to obtain a new access token when the current access token becomes invalid or expires. The refresh token never expires and can be used only once. It becomes invalid when the access token is revoked. |
client_id REQUIRED | The client identifier issued to the client during the registration process. |
client_secret REQUIRED | The client secret issued to the client during the registration process. |
Response Attributes |
|
|---|---|
access_token string | A Payfirma access token is a JWT format string representing an authorization issued to the client (you) from the user (the Merchant) to access their protected Payfirma resources. |
token_type string | General identifier for the OAuth token. |
refresh_token string | Refresh token is issued to the client by Payfirma authorization server and is used to obtain a new access token when the current access token becomes invalid or expires. The refresh token never expires and can be used only once. It becomes invalid when the access token is revoked. |
expires_in number | The lifetime in seconds of the access token. The default setting for the access token default is to expire in 20 minutes (1200 seconds). |
merchant_id string | Unique identifier for the merchant. |
scope string | The list of different services that have been authorized for access. |
Example Request:
curl --include \
--request POST \
--header "Content-Type: application/x-www-form-urlencoded" \
"https://auth.payfirma.com/oauth/token?grant_type=refresh_token&refresh_token=41c128f2-b2e2-4d85-9443-b6e37d02a482&client_id=UGF5ZmlybWEgdGVzdCAwOSBjbGllbnQgSUQ%3D&client_secret=Q2xpZW50IHNlY3JldCBmb3IgUGF5ZmlybWEgdGVzdCAwOQ%3D%3D"Example Response Body:
{
'access_token': 'eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU',
'token_type': 'Bearer',
'refresh_token': '955d8714-f1d6-49d6-830a-2d221631a2b3',
'expires_in': 1199,
'merchant_id': '01234abcde',
'scope': 'invoice ecom',
}Revoke
Invalidate an authorization code
BASE URI
https://auth.payfirma.com/oauth
Revoke token
A revocation request will invalidate the token passed through the authorization header, revoking both the access token and refresh token.
HTTPS DELETE
/revoke_token