Getting started

Run in Postman

We are using CURL commands in examples below, but if you prefer Postman, then you can import the entire collection from the below link:

Run in Postman

Getting started video

Check out our Getting Started video or follow the Getting started guide.

Getting started guide

Let’s Get started with the step by step guide designed to help your development journey.

STEP 1: Register and create application

First register at the OFX Developer Portal.

Once registered, login into your account and go to My Apps to create an application, selecting either the Payments API or Rates API.


After creating your app, you will have access to a Consumer Key (also referred to as your Client ID) and Secret.

Step 2: Get an access token

Get the Access token following OAuth 2.0 client credentials flow.

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'

Replace your_client_id and your_client_secret with your client id and client secret .

Copy a temporary access token from your response, which expires in the defined timeframe (seconds).

Example response:

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

See Authentication section for details.

Step 3: Create a quote

Once received an Access Token, it is time to create your first Quote.

curl -X POST \
  https://sandbox.api.ofx.com/v1/payments/quotes \
  -H 'authorization: Bearer your_access_code' \
  -H 'content-type: application/json' \
  -d {
  "buyCurrency": "USD",
  "buyAmount": 10000,
  "sellCurrency": "AUD",
  "beneficiaries": 1}

In this example:

  • We want to transfer 10000 USD to AUD. buyCurrency - the currency OFX buys from the customer, sellCurrency - the currency OFX sells to the customer.
  • Number of beneficiaries is 1, which means the Payment will be paid to 1 recipient.

The successful response contains the Quote ID:

{
  "id": "2e2aadc8-d69b-45d5-9f14-8b08a2365d90"
}

We can quickly check the status of the quote via the following API call:

curl -X GET \
  https://sandbox.api.ofx.com/v1/payments/quotes/2e2aadc8-d69b-45d5-9f14-8b08a2365d90 \
  -H 'authorization: Bearer your_access_token' \
  -H 'content-type: application/json'
{
  "buyCurrency": "USD",
  "buyAmount": 10000,
  "sellCurrency": "AUD",
  "sellAmount": 13304,
  "customerRate": 1.3304,
  "inverseCustomerRate": 0.751653638003608,
  "fee": 0,
  "feeCurrency": "USD",
  "freebies": {
    "total": 0,
    "claimed": 0,
    "remaining": 0
  }
}

In this response:

  • The quote for 10000 USD will be 13304 AUD
  • the rate is 1.3304
  • the other parameters are not important at this stage, you can check specifications for more details later.

See Quote specs for details

Step 4: Create a beneficiary

Now we need to create a beneficiary, a recepient of the payment.

curl -X POST \
  https://sandbox.api.ofx.com/v1/payments/beneficiaries \
  -H 'authorization: Bearer your_access_token' \
  -H 'content-type: application/json' \
  -d { 
    "currency": "AUD",
    "name": "Test name",
    "classification": "Own Account",
    "paymentReason": "Test payment reason",
    "beneficiaryBankDetails": {
        "bankName": "Westpac AU",
        "bankBranchName": "C",
        "branchCode": "234434",
        "account": "45663",
        "bankAddress": {
            "addressLine": "1,vaChatswood Brnch",
            "citySuburb": "Sydney",
            "stateProvince": "New South Wales",
            "postCode": "2060",
            "country": "AU"
        }
    },
    "beneficiaryAddress": { 
        "country": "AU",
        "addressLine": "9/11,vaBridge Street",
        "citySuburb": "Sydney",
        "stateProvince": "New South Wales",
        "postCode": "2000"
    }
   
}

And response:

{
  "beneficiaryId": "2f1901fa-17e0-486f-87fe-42371f97c957"
}

In the above example:

  • currency specifies in which currency the beneficiary will receive funds
  • beneficiaryBankDetails and beneficiaryAddress are the recipient bank details and address

See Beneficiaries specs for details

Step 5: Create a deal

Now, we have a quote ID and Beneficiary ID, it is time to create a deal:

 curl -X POST \
  https://sandbox.api.ofx.com/v1/payments/deals \
  -H 'authorization: Bearer your_access_token' \
  -H 'content-type: application/json' \
  -d {
    "quoteId": "2e2aadc8-d69b-45d5-9f14-8b08a2365d90",
    "fundingSource": "Own account",
    "beneficiaries" : [{
          "beneficiaryId": "2f1901fa-17e0-486f-87fe-42371f97c957",
          "amount": 13304,
          "payReason": "PayReason",
          "payReference": "PayReference"
    }]
}

In above example: ​

  • quoteId - the quote returned from previous create quote API call
  • beneficiaries - array of beneficiaries, who will receive the payment.
  • beneficiaryId - the id from previously created beneficiary
  • amount the amount of the Quote.

The successful response contains the Deal ID:.

{
  "dealId": "d7e59678-8608-498e-a8bc-7ab44017dd90"
}

Deal process simulation on Sandbox

When a deal is created on Sandbox, the deal status is “Booked”. Approximately one day later, the deal status is changed automatically to “Paid”. This simulates the movement of deal through the process and makes testing deal statuses easier. Please note this simulation applies only to the sandbox enviornment.

Congratulations

We’ve just created a new payment!