Authorization

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 'client_credentials'.

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

Last updated