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.
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
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"
}
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:
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'