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:

https://sandbox.api.ofx.com/v1/oauth/token

OFX OAuth Authorise URL:

https://sandbox.api.ofx.com/v1/oauth/authorize

Supported Flows

Client credentials flow

The client credentials flow should be only used by services and applications to get an access token for their own account, outside the context of any specific user.

STEP 1: Getting access token

After registering your app, you will receive a Client ID and a Client Secret. The ID is considered public information, and is used to build login URLs, or included in Javascript source code on a page. The secret must be kept confidential.

Example request:

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

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=client_credentials&client_id=your_client_id&client_secret=your_client_secret&scope=payments'

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

{
  "access_token": "gAAAAH_x6f2fywNe0MyI2XTh9EMj-ijVbBGQHScMPp0HWMI17kvi-jfkj348zXx3DT6c0drdDnLgMLCBsGLKUP2fDUMhIWOhK9aHfOOaRhwQsNEdAiDJRzlrBWijPhyL5prCbKqE_b-Lq9mrpHopN8TDmaUqAoY_fOmT6BcQpiOW8hAEAAIAAAACmxkA0jiLSNR4M2ko2ETrF-oG_L20KdvnQEXF9wDbR2LPPC70UqGJhQEf-K1Zw27W-M2D67-6GfwsJdzMGa9dtzSrsLl0LSLfcY_ccbFRLmPTMWA5RTq42yYKhD1U6PTyL3PQwDuStvfY3gU2_RrwQOhjlJEbFcGQCmCxHtgMj3iMegsF50PyEGbWNaxbIvO8PoNAaItrnVBNP3U-JHnrU9Eg6QB",
  "expires_in": 3599,
  "token_type": "Bearer"
}

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:

GET https://sandbox.api.ofx.com/v1/payments/beneficiaries?pageSize=1
Authorization: Bearer your_access_token
Content-Type: application/json

or in cURL command:

curl -X GET \
  'https://sandbox.api.ofx.com/v1/payments/beneficiaries?pageSize=2' \
  -H 'authorization: Bearer your_access_token' \
  -H 'content-type: application/json'

Access Code flow

Before you can begin the Access Code process, you must first register a new app with the service. When registering a new app, you usually register basic information such as application name and a redirect URI to be used for redirecting users to for web server, browser-based, or mobile apps.

The service will only redirect users to a registered URI, which helps prevent some attacks. Any HTTP redirect URIs must be protected with TLS security, so the service will only redirect to URIs beginning with “https”. This prevents tokens from being intercepted during the authorization process. Native apps may register a redirect URI with a custom URL scheme for the application, which may look like demoapp://redirect.

STEP 1: Authorization

The first step of OAuth 2 is to get authorization from the user. For browser-based or mobile apps, this is usually accomplished by displaying an interface provided by the service to the user.

GET https://sandbox.api.ofx.com/v1/oauth/authorize?response_type=code&client_id=your_client_id&state=xyz&scope=payments&redirect_uri=your_redirect_url

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.

OFX Log In Dialog

and then the Consent dialog:

OFX Consent Dialog

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

https://your_url.com/cb?code=AUTH_CODE_HERE&state=1234zyx

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

https://your_url.com/cb?error=access_denied&state=1234zyx

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:

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

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=authorization_code&client_id=your_client_id&code=your_auth_code&redirect_uri=your_redirect_url&client_secret=your_client_secret&&scope=payments'

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"
}

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:

GET https://sandbox.api.ofx.com/v1/payments/beneficiaries?pageSize=1
Authorization: Bearer your_access_token
Content-Type: application/json

or in cURL command:

curl -X GET \
  'https://sandbox.api.ofx.com/v1/payments/beneficiaries?pageSize=2' \
  -H 'authorization: Bearer your_access_token' \
  -H 'content-type: application/json'

Using a 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.