Getting started

Run in Postman

We are using CURL commands in below examples, 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 OFX Developer and follow the steps.

Once registered, login into your account and go to My Apps (You will need to be logged in) to create an application.


You will be able to get your API keys (id and secret) after your application approval. Please note, it may take several business days to get your application approved.

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 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 (or customer sells), sellCurrency - the currency OFX sells to the customer (of customer wants to buy from OFX).
  • 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 above example we created a beneficiary (the entity that will receive the payment). Some of the key fields:

  • currency specifies in which currency beneficiary should receive funds
  • beneficiaryBankDetails and beneficiaryAddress are the payment 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 book a payment deal:

 curl -X POST \
  https://sandbox.api.ofx.com/v1/payments/deals/spot \
  -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 and the amount is the amount from the Quote. ​ and response:
{
  "processId": "833771b4-b7db-4770-83ba-6e69d88e1631"
}

Please note, a processId is NOT a dealId. The Create Deal process is an asynchronous call (process) that has a processId. This call will return the process ID which we can then use to check the status of the Deal using a separate API call to get long the processing status of the Deal - STEP 6. See Deals specs for details

Alternatively, you can use the notifications callback mechanism, to get an event when deal creation process has finished. See notifications callback for moredetails

Step 6: Get the “create deal” process result

We can easily get the status of the Long running process via the following API call.

curl -X GET \
  https://sandbox.api.ofx.com/v1/payments/deals/process/833771b4-b7db-4770-83ba-6e69d88e1631 \
  -H 'authorization: Bearer your_access_token' \
  -H 'content-type: application/json'
  • where 833771b4-b7db-4770-83ba-6e69d88e1631 is the processid from previous Create Spot deal API call. ​ and the 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”. Approaximately 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!

What is next ? Go to the Authentication section to learn more about OFX APIs.