Guides

Authentication with OAuth2

Quick intro to OAuth

To access the PayFit API, you must first make sure that you have signed up as a PayFit partner.

The PayFit API relies on the OAuth 2.0 protocol and the Bearer authentication scheme, both proven industry standards. They allow you to grant a third-party application, such as PayFit, access to your information stored on another site, without ever sharing your password.

The OAuth2 flows grants you a token, which represents the access authorization between the two services. The token has a limited set of authorizations, and you can revoke it at any time.

As such, OAuth2 is a secure and convenient way to share your information between two services.

Generating an access token with the OAuth flow

Generating an access token with the oAuth flow is a multi-step process that requires a user to grant access to your app, which then exchanges an authorization code for an access token.

There are 4 steps, described below:

  1. Create a button to grant access.
  2. Redirect the user with a verification code.
  3. Exchange the verification code for an access token.
  4. Store the token and corresponding company_id.

Step 1: Create a button to grant access

On your website, create a link to PayFit where a PayFit admin user can approve access to their information on PayFit.

The link should include the following GET parameters:

  • client_id: the client ID given by PayFit when the partnership was established
  • redirect_uri: encoded URL submitted when the partnership was established. The user will be returned to this URL with the code parameter set to the authorization code if they accept the integration.
  • response_type: the string "code"
  • state: unique string to be passed back upon completion (optional). This should be used to avoid forgery attacks by passing in a value that's unique to the user being authenticated and checking it when the authorization process is complete.
  • scope: a list of OAuth scopes separated by spaces indicating the parts of the PayFit API the app wants to access. ⚠️ Warning : for security purposes, PayFit whitelist possible scopes for every partner (this is the list of scopes that were requested during partnership request), please make sure the scopes you request in this link are in the whitelist you asked for PayFit, otherwise the flow won't work !

The link should look like this:

<a href="https://oauth.payfit.com/authorize?redirect_uri=https%3A%2F%2Fmy-awesome-website.com%2Foauth&client_id=<your_client_id>&response_type=code&scope=<your_app_scopes>">Integration with PayFit </a>

When clicking on that link, the user will be prompted to log in to their PayFit admin account and authorize the integration with your application for their company (or one of their companies).

After the user accepts, PayFit will generate an authorization code.

Step 2: Redirect the user with a verification code

Once the authorization code is generated, PayFit redirects the user to the redirect_uri with the following parameters:

  • code: query parameter used to obtain the first access token
  • state: parameter if provided in the previous step. If the states don't match, the request may have been created by a third party and the process should be aborted.

PayFit will send the user to a URL that looks like this:
https://my-awesome-website.com/oauth?code=<a_useful_code>

From there, it's up to your OAuth feature to act.

Step 3: Exchange the verification code for an access token

Make a server-side POST request to PayFit at https://oauth.payfit.com/token with the following body:

  • client_id: the client id to identify the application
  • redirect_uri: same URI as before, used to identify the application
  • code: the code received in the previous step
  • client_secret: the secret given when the partnership was established
  • grant_type: the string "authorization_code".

The request will return the following JSON payload:

{
"access_token": "your_secret_token",
"token_type": "bearer"
}

Step 4: Store the token and corresponding company_id

You should now store that token on your server.

The access_token is valid for the company of the user who completed the OAuth flow, no other company (if they have several handled by PayFit).
If you need information about that, you can request the introspection POST endpoint https://oauth.payfit.com/introspect with the following cURL command:

curl -X POST \
https://oauth.payfit.com/introspect \
-H 'Authorization: Bearer your_secret_token' \
-H 'Content-Type: application/json' \
-d '{ "token": "your_secret_token" }'

This request will return a JSON response with the company_id:

{
"active": true,
"scope": "scope1 scope2",
"client_id": "your client id",
"company_id": "the_company_id",
"token_type": "bearer"
}

From now on, you must add the header Authorization with the value Bearer your_secret_token on all your requests to call the API.

You are now ready to make your first request to the PayFit API:

curl -X GET \
https://partner-api.payfit.com/companies/the_company_id \
-H 'Authorization: Bearer your_secret_token'

Updated 9 months ago