Introduction

OFX Payments API is protected by the industry standard OAuth2.0 protocol

We strongly recommend to read OAuth2.0 documentation if you are not familiar with it.

OFX OAuth Token URL:

OFX OAuth Authorise URL:

Supported Flows

or in cURL command:

Example response contains temporary access token which expires in defined timeframe (seconds)

STEP 2: Making Authenticated Requests

Once you have received the Access Token, you can use it in all subsequent API calls by setting an Authorization header.

For example to retrieve the list of user beneficiaries:

or in cURL command:

• response_type - Should be ‘code’, indicates that your server expects to receive an authorization code
• client_id - The ID you received when you first created the application
• redirect_uri - Indicates the URI to return the user to after authorization is complete
• scope - Should be ‘payments’ for OFX Payments API
• state - A random string generated by your application, which you’ll verify later

As a result of this command in the browser, the user will see the following screens to input the username and password and then to provide user’s consent to grant an access to user’s data.

Login dialog:

and then the Consent dialog:

If the user clicks “YES, ALLOW,” the service redirects the user back to your site with an auth code

• code - The server returns the authorization code in the query string
• state - The server returns the same state value that you passed

If the user clicks “NO, DO NOT ALLOW” the service redirects the user back to your site with an error

• error - The server returns an access_denied error
• state - The server returns the same state value that you passed

STEP 2: Token exchange

Your server exchanges the auth code for an access token:

or in cURL command:

• grant_type=authorization_code - The grant type for this flow is authorization_code
• code=AUTH_CODE_HERE - This is the code you received in the query string
• redirect_uri=REDIRECT_URI - Must be identical to the redirect URI provided in the original link
• client_id=CLIENT_ID - The id you received when you first created the application
• client_secret=CLIENT_SECRET - The secret key you received when you first created the application
• scope - Should be ‘payments’ for OFX Payments API

Example response contains temporary access token which expires in defined timeframe (seconds), along with a ‘refresh_token’, that lives much longer.

{
   "access_token": "Q0NEficYFme0pexJvCq0B1m1b5GM",
   "expires_in": 3599,
   "token_type": "Bearer",
   "refresh_token": "4S9dpU3HzEzrAA6AWH2dWxepYxmPfoUG"
}

Using Refresh Token

When an access token expires, a new access token can be generated using the ‘Refresh Token’ grant type.

This allows clients to continue to have a valid access token without further interaction (re-authentication) with the user.

Note: To get a new access token, always use the refresh token returned in the most recent response.

A Refresh token expires in 2592000 seconds (30 days).

Request

POST https://sandbox.api.ofx.com/v1/oauth/token 
Content-Type: application/x-www-form-urlencoded
        grant_type=refresh_token&client_id=your_client_id&client_secret=your_client_secret&scope=payments&refresh_token=your_latest_refresh_token

or in cURL command:

curl -X POST \
  https://sandbox.api.ofx.com/v1/oauth/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id=your_client_id&client_secret=your_client_secret&scope=payments&refresh_token=your_latest_refresh_token'

• grant_type=refresh_token - The grant type for this flow is ‘refresh_token’
• refresh_token=REFRESH_TOKEN_HERE - This is the refresh token you received previously

The response to the refresh token grant is the same as when issuing an access token.

STEP 3: Making Authenticated Requests

Once you have received the Access Token, you can use it in all API calls that require you to be authorized by providing Authorization header parameter.

For example to retrieve the list of user beneficiaries:

or in cURL command: