Paste this query to the GraphQL Playground

const bodyJSON = {
  operationName: "balances",
  variables: {
    currencies: ["AUD"],
  },
  query: `
query balances($currencies: [CurrencyIso3]) {
  balances(currencies: $currencies) {
    currency cleared pending
  }
}`,
};

query balances($currencies: [CurrencyIso3]){
  balances(currencies: $currencies) {
    currency
    cleared
    pending
  }
}

{
  "currencies": ["AUD"]
}

The cleared is the Primary balance you see on the Flash Connect website.

The pending balance is typically not shown on the Flash Connect interface because it's rather short lived. If your Pending balance is not 0 then you can see it right next to the Primary balance.

If you omit the currencies input argument then the query would return all the currency balances you have. Contact us to enable more than just the default AUD currency.

Top up your UAT account balance

If you need to increase your UAT account balance please sign in to the Flash Connect website, open Deposits page, and click Send Test Deposit.

The sub-client (aka merchant) feature allows you to create client accounts for deposit collection purposes. These virtual accounts can be issued to individuals, companies, or other organisations.

Each sub-client will receive a dedicated BSB and Vitrual Account Number (VAN) that you or your clients can use to accept and withdraw domestic AUD transfers within Australia.

The account name is your sub-client's name. For companies - it's their tradingAsName or legalName. For individuals - it's their fullName (firstName + middleName + lastName).

If your Flash account has a multi-currency feature enabled, each of your sub-clients will also have access to virtual accounts in the selected currencies for which you hold balances.

All deposits sent to your sub-client Virtual Account Numbers (VANs) are booked on your (master-client's) corresponding account balances. Sub-clients can't have their own balances.

You can disburse funds and make FX payments on behalf of your sub-clients by providing the sub-client ID when you create withdrawals or payments. This sub-client record will then be used as the sender, linked to the transaction, and reported to the government.

Notifications via webhooks will provide important sub-client information as well.

A sub-client lifecycle follows these stages.

A sub-client is created and has the temporary INITIATED status. At this stage, the request has been received and the system is currently processing it.

If processing is completed successfully, the sub-client automatically transitions to the ACTIVE. In this status, the sub-client is fully activated and approved.

If the sub-client requires manual compliance review, the sub-client moves from INITIATED to the temporary UNAPPROVED status. From this status it would eventually transition to either ACTIVE or FAILED_KYC. Typically, we can't disclose the exact reason of the KYC failure, while it mostly happens because we do not have risk appetite for your client.

You can deactivate the client (via API of Flash Connect), - it'd move from ACTIVE to DEACTIVATED. A sub-client in the DEACTIVATED status can be activated by you at any time, returning to ACTIVE.

At any point, a sub-client may be moved to DISABLED. In this status, the sub-client is disabled and cannot be enabled by you, and contacting support is required for further information.

Available queries

Query for a single sub-client

const bodyJSON = {
  variables: {
    id: "606d28675a2d931bc925fec2",
      input: {
        currencies: ["EUR","USD","HKD","CNY"],
      },
  },
  query: `
query ($id: ID!, $input: FundingAccountQueryInput!) {
  subClient(id: $id) {
    id fullName legalName tradingAsNam clientType status 
    primaryContact {
      firstName middleName lastName email dob mobile
    }
    address {
      building street suburb state country postcode
    }
    postalAddress {
      building street suburb state country postcode
    } 
    businessNumber bsb accountNo externalId
    fundingAccounts(input: $input) {
      iban accountNo bic currency externalReference
    }
  }
}`,
};

Query for multiple sub-clients

Query for multiple sub-clients with filters

There are two types of sub-clients: company and individual.

For every company registered as a sub-client, there must be one contact person for individual data submitted. Ideally, the contact person should be a company director or have a similar role. Therefore, if you are creating a sub-client of the company type, we require you to provide extra details:

• legalName - company legal name

• businessNumber - company business number (e.g. ABN in Australia)

If the above fields are not set, the sub-client will be created as individual type.

The above personal data submission requirements should be as equally followed for the company contact person, with the exception of address property, which can be a company address in this case.

To create a sub-client, you need to execute the createSubClient mutation as below. You can find the description of each field in the GraphQL API schema.

const bodyJSON = {
  variables: {

mutation($input: CreateSubClientInput!) {
  createSubClient(input: $input) {
    success
    code
    message
    subClient {
      id
      legalName
      businessNumber
      fullName
      clientType
      status
      primaryContact {
        firstName
        lastName
        email
        mobile
        dob
      }
      address {
        country
      }
      bsb
      accountNo
      externalId
      # more properties available, see API schema
    }
  }
}

{ 
  "input": {
    "legalName": "Chineese Tradings",
    "businessNumber": "330782000329701",
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "mobile": "+61422832849",
    "dob": "1979-05-12",
    "address": {
      "building": "25",
      "street": "Xihu Road, Yuexiu District",
      "suburb": "Guangzhou City",
      "state": "Guangdong Province",
      "postcode": "510030",
      "country": "CN"
    },
    "idDoc": {
      "type": "passport",
      "docNumber": "FF1948394",
      "issuer": "Australian Passport Office (APO)",
      "issueDate": "2000-01-01",
      "expiryDate": "2045-01-01",
      "country": "AU"     
    },
    "externalId": "991188227733"
  }
}

{
  "data": {
    "createSubClient": {
      "success": true,
      "code": "SUBCLIENT_CREATED",
      "message": "Sub-client was successfully created",
      "subClient": {
        "id": "606d28675a2d931bc925fec2",
        "legalName": "Chineese Tradings",
        "businessNumber": "330782000329701",
        "fullName": "John Smith",
        "clientType": "INDIVIDUAL",
        "status": "ACTIVE",
        "primaryContact": {
          "firstName": "John",
          "lastName": "Smith",
          "email": "[email protected]",
          "mobile": "+61 422 832 849",
          "dob": "1979-05-12"
        },
        "address": {
          "country": "CN"
        },
        "bsb": "802919",
        "accountNo": "1066419",
        "externalId": "991188227733"
      }
    }
  }
}

You can disable and activate sub-clients. Deposits sent to a disabled sub-client will no longer be booked against your balance.

Disabling a sub-client

const bodyJSON = {
  variables: {
    input: "606128f24bf29139b2cf74ef",
  },
  query: `
mutation ($input: ID!) {
  disableSubClient(id: $input) {
    success code message 
    subClient {
      id status
    }
  }
}`,
};

mutation($input: ID!) {
  disableSubClient(id: $input) {
    success
    code
    message
    subClient {
      id
      status
    }
  }
}

{ 
   "input": "606128f24bf29139b2cf74ef"
}

{
  "data": {
    "disableSubClient": {
      "success": true,
      "code": "SUCCESS",
      "message": "Sub-client was successfully disabled",
      "subClient": {
        "id": "606128f24bf29139b2cf74ef",
        "status": "DISABLED"
      }
    }
  }
}

Activating a sub-client

const bodyJSON = {
  variables: {

mutation($input: ID!) {
  activateSubClient(

{ 
   "input": "606128f24bf29139b2cf74ef"
}

{
  "data": {
    "activateSubClient": {
      "success": true,
      "code": "SUCCESS",
      "message": "Sub-client was successfully activated",
      "subClient": {
        "id": "606128f24bf29139b2cf74ef",
        "status": "ACTIVE"
      }
    }
  }
}

Updating sub-clients

At this point, you can only update the externalId , address and postalAddress properties because each sub-client has a set of linked domestic and international Virtual Account Numbers to send and receive funds.

Updating sub-client externalId

const bodyJSON = { 
  variables: {
    id: "660fef8e1f3b5452bd6945ec",
    input: {
      externalId: "my_system_id_29f-ae0978b00d09e",
    },
  }, 
  query: `
mutation ($id: ID!, $input: UpdateSubClientInput!) {
  updateSubClient(id: $id, input: $input) {
    success code message
    subClient {
      id status externalId
    }
  }
}`,
};

mutation($id: ID!, $input: UpdateSubClientInput!) {
  updateSubClient(id: $id, input: $input) {
    success
    code
    message
    subClient {
      id
      status
      externalId
    }
  }
}

{ 
  "id": "660fef8e1f3b5452bd6945ec", 
  "input": {
    "externalId": "my_system_id_29f-ae0978b00d09e"
  }
}

{
  "data": {
    "updateSubClient": {
      "success": true,
      "code": "SUCCESS",
      "message": "Sub-client was successfully updated",
      "subClient": {
        "id": "660fef8e1f3b5452bd6945ec",
        "status": "ACTIVE",
        "externalId": "my_system_id_29f-ae0978b00d09e"
      }
    }
  }
}

Updating sub-client address

const bodyJSON = { 
  variables: {
    id: "660fef8e1f3b5452bd6945ec",
    input: {
      adddress: {
        street: "456 New St",
        suburb: "Newtow",
        state: "VIC",
        postcode: "3220", 
        country: "AU",
      },
    },
  }, 
  query: `
mutation ($id: ID!, $input: UpdateSubClientInput!) {
  updateSubClient(id: $id, input: $input) {
    success code message
    subClient {
      id status externalId address {building street suburb state postcode country}
    }
  }
}`,
};

mutation($id: ID!, $input: UpdateSubClientInput!) {
  updateSubClient(id: $id, input: $input) {
    success
    code
    message
    subClient {
      id
      status
      externalId
      address {
        building 
        street
        suburb
        state
        postcode
        country
      }
    }
  }
}

{ 
  "id": "660fef8e1f3b5452bd6945ec", 
  "input": {
    "address": {
        "street": "456 New St",
        "suburb": "Newtow",
        "state": "VIC",
        "postcode": "3220",
        "country": "AU"
    }
  }
}

{
  "data": {
    "updateSubClient": {
      "success": true,
      "code": "SUCCESS",
      "message": "Sub-client was successfully updated",
      "subClient": {
        "id": "660fef8e1f3b5452bd6945ec",
        "status": "ACTIVE",
        "externalId": "my_system_id_29f-ae0978b00d09e",
        "address": {
          "building": null,
          "street": "456 New St",
          "suburb": "Newtow",
          "state": "VIC",
          "postcode": "3220",
          "country": "AU"
        }
      }
    }
  }
}

Retrieving all your conversions

const bodyJSON = {
  variables: {
    input: {
    },
  },
  query: `
query ($input: ConversionQueryInput!) {
  conversions(input: $input) {   
    id fromCurrency toCurrency rate 
  }
}`,
};    

 query($input: ConversionQueryInput!) {
  conversions(input: $input) {
    id
    fromCurrency
    toCurrency
    rate
    # there are many other properties
  }
}

 {
  "input": { 
  }
}

{
  "data": {
    "conversions": [
      {
        "id": "6b04c62ec0bf606bf216ae21",
        "fromCurrency": "AUD",
        "toCurrency": "EUR",
        "rate": 0.71
      },
      {
        "id": "6b04c6bfc0bf606bf216af06",
        "fromCurrency": "AUD",
        "toCurrency": "USD",
        "rate": 0.70
      },
      {
        "id": "6b04c8e3c0bf606bf216b026",
        "fromCurrency": "EUR",
        "toCurrency": "AUD",
        "rate": 0.71
      }
    ]
  }
}

Retrieving some of your conversions

const bodyJSON = {
  variables: {

query($input: ConversionQueryInput!) {
  conversions(

{
  "input": { 
    "statuses": "CONVERTED",
    "toCurrencies": ["EUR","USD"]
  }
}

{
  "data": {
    "conversions": [
      {
        "id": "6833ad9b4e94acce5d4a031b",
        "fromCurrency": "AUD",
        "toCurrency": "USD"
      },
      {
        "id": "678a18bb2879c374b378ee71",
        "fromCurrency": "AUD",
        "toCurrency": "EUR"
      }
    ]
  }
}

Retrieving a single conversion by ID

const bodyJSON = {
  variables: {
    input: "6b04c62ec0bf606bf216ae21",
  },
  query: `
query ($input: ID) {  
  conversion(id: $input) {
    status createdAt fromAmount toAmount 
  }
}`,
};

query($input: ID) {
  conversion(id: $input) {
    status
    createdAt
    fromAmount
    toAmount
    # there are many other properties
  }
}

{
  "input": "6b04c62ec0bf606bf216ae21"
}

{
  "data": {
    "conversion": {
      "status": "CONVERTED",
      "createdAt": "2024-08-13T05:45:28.698Z",
      "fromAmount": 1000,
      "toAmount": 710.01
    }
  }
}

You can create payouts via the createWithdrawal mutation.

You can retrieve your payouts via the withdrawals query.

Sometimes you'd need to understand the supported delivery methods using the availableDeliveryMethods query.

If you get instructed by another financial institution then you must submit their details too.

If the payouts didn't pass compliance we would reject it with a proper rejection code and descriptive message.

Upon detecting a deposit in a Flash Payments Virtual Account Number (VAN), we immediately record it as a deposit in our system.

The status of a successful deposit goes through the following lifecycle

INITIALISED->REVIEWING→CONFIRMED

If you choose to reject a deposit, its status goes through the following lifecycle instead:

INITIALISED->REVIEWING→CONFIRMED→REFUNDING→REFUNDED

If Flash Payments Compliance choose to reject a deposit, its status lifecycle goes through following stages:

INITIALISED→REVIEWING→REFUNDING→REFUNDED

If you use our multi-currency feature, you can exchange currency and convert funds between your master accounts in real-time.

Conversion fees are detailed in your contract and vary based on your use case and risk assessment.

The GraphQL schema defines statuses like this:

enum ConversionStatus {
    INITIALISED
    PENDING
    CONVERTED
    FAILED
    CANCELLED
}

The status of a conversion can be any of the following:

• INITIALISED — A conversion record was created, but no further action has been taken. This status typically does not occur via the API.

• PENDING — The conversion is in progress. This is the usual status immediately after creation.

• CONVERTED — The conversion completed successfully. Your balances have been updated accordingly.

• FAILED — An error occurred during the conversion. This is usually a temporary state.

• CANCELLED — The conversion was not completed and has been cancelled. This action is typically performed by the Flash Payments operations team.

Most documentation examples utilise typical GraphQL input data for successfully executing queries.

It's strongly encouraged that you always submit complete and accurate data, as this reduces our compliance team's reviewing efforts and, as a result, speeds up transactions and provides a great experience for your customers.

At the same time, we recognise that gathering complete customer information can be technically challenging, particularly regarding country-specific address details or account information. As a result, our API documentation emphasises the required input fields based on the principle of minimal necessity.

Please pay attention to the exclamation mark ( ! ) next to the field type in the API schema specification from the "Docs" section of our API Playground. Those are the required fields as it's demonstated on the screenshot below:

Please always verify that you have all required data to initiate a successful mutation or query.

What we call "FX Payment" is a fully orchestrated account to account delivery of any currency(-ies) we support. Typical examples:

• You need to send from the EU to Australia. You would have a European virtual IBAN on your name. As soon as you deposit some EUR to it - you'll see a corresponding amount of AUD on your master balance in a matter of minutes, which you'll be able to use immediately.

• You need to fund someone's overseas IBAN in Euros. You send us the AUD and give us the recipient's details either via API or via you FlashConnect back-office GUI. We orchestrate the rest.

You can create payments. using the createPayment mutation.

You can your payments with the payments query.

But before you need to understand the supported delivery methods using the query.

If your withdrawal is canceled (aka rejected) by our AML and Compliance team, you'll receive the webhook containing both a rejection code (rejectCode) and a manually written rejection reason (statusMessage). You can find the same two properties within the GraphQL type.

Here is a current list of all possible rejectCodes, but please note this list can be extended with time.

Refund deposit by ID

After fully registering with us, you get a BSB and a dedicated Virtual Account Number (VAN).

Every deposit to your VAN would increase your Flash Payments balance.

Every deposit can trigger a notification, keeping you informed in real time

The GraphQL schema defines statuses like this:

The status of a payment can be any of the following:

Payment Statuses:

• INITIALISING – a draft payment. It may or may not have all required information to be executed. Typically, this never happens through the API. Can be created via the under certain circumstances.

• OPEN – The payment is in progress.

General information

Flash Payments API is GraphQL-based, offering simple and developer-friendly querying experience. All data is exchanged in JSON format.

Flash Payments API playground is located here: https://api.uat.flash-payments.com.au/

Complete API docs

This documentation website does not have full list of API fields and methods. This is intentional. The full list of the API calls you can performs and the data fields you can send/receive is listed in the (click "DOCS" on the right hand side).

High level feature overview

You can search, visualise, or extract your data using our interface.

Instant local Australian deposit (aka pay-in)

Once registration is complete, a dedicated BSB and Virtual Account Number (VAN) for use within Australia will be assigned to you.

Any funds deposited to your VAN would increase your Flash Payments balance. We store and retain the reference attached to each deposit (e.g., an invoice number) to support your reconciliation or reporting needs.

By default, only you can deposit into your VAN. Third-party deposits are also supported, but this feature must be enabled separately

Deposits are typically processed in real time, but depending on the bank, there may be a delay of up to 24 hours.

You can configure webhook notifications to receive alerts for every deposit made to your VAN. Please visit to set up your deposit webhook.

You can manually reject unwanted deposits via the interface. The funds will be returned to the original sender bank account.

Local Australian withdrawal (aka pay-out)

The Flash Payments API enables you to withdraw funds from your Flash Payments balance. By default, only you are authorized to receive these withdrawals. Third-party withdrawals (also known as payouts) are available upon request and require separate activation.

If your payout involves a foreign exchange (FX) payment, it must be processed using the Australian Direct Entry system in accordance with legal requirements. Processing time may vary from immediate to a few hours. Other payouts are credited instantly.

If a payout fails, you will receive a webhook notification detailing the reason for the failure.

The payout remitter name is configurable. You can give us the remitter name as withdrawal.sender data property. This is especially useful for FX-linked payouts. If a Brazilian mama Katarina Oreiro sends money to her son in Australia, he will see his mom's name in the bank statement - "Payment from Katarina Oreiro".

Payouts can also be done via the interface.

Send or receive money internationally

You can send your Flash Payments balance internationally via our API and benefit from instant delivery to many countries with local instant payment systems (e.g. Philippines)

To initiate a payment, you must pre-create the sender and recipient via the API.

All entities in our database, including withdrawals, payments, senders, and recipients, can store your system’s unique identifier. Please refer to the externalId field in the .

Payment delivery times depend on the recipient's country. While many are processed quickly, some may take additional time. You’ll be notified via webhook whenever the payment status changes.

You can send funds through an international payment to your Flash Payments account. A webhook notification will be triggered when we detect payments from other countries.

Security

The API token you generate expires in 4 hours. You can always use logout GraphQL mutation to expire it earlier.

You can't reset your own password until we verify your identity.

The interface supports Google and One-Time-Password logins.

Webhooks have cryptographic signatures.

IP address whitelisting feature is available from FlashConnect interface allowing login to our APIs from only preapproved addresses that you specify.

API rate limiting is in place to ensure stable performance of our service and prevent its potential abuse.

How to start

1. Contact with us via or by clicking the Intercom button on the bottom right of this page.

2. Explain what kind of services you are looking from Flash Payments.

3. We will examine your needs and explain how to get access to our UAT environment.

For more detailed instructions head to the page.

Important notes

Breaking changes

While we will endeavour to not introduce any breaking changes they might still occur in the future. In that case we will communicate about the upcoming changes via your registered email.

When sending a payment, creating a local withdrawal or ordering a conversion you can provide us a webhook (callback) URI - callbackUri. We will call it when a payment or withdrawal status changes.

We recommend API clients to generate and add ?signature=ASecretPerPaymentKey query to your callbackUri to make sure it's Flash Payments calling your webhook endpoint. For example:

https://my-webhooks.example.com/flash-payments?signature=oZaDlmfXbdXSKCnuWrvos2ImVBFX2Ru5

To avoid storing the signatures in a database we recommend generating them on the fly using a strong hash function or any kind of cryptography.

Example

You would need to implement two functions.

1. Function to generate "signature".

2. Function to verify the "signature".

Generating signatures

Node.js pseudo code to generate a signature in your integration code.

The code above creates a callbackUri and externalId variables. Use both of them when creating a transfer in Flash Payments API.

Verifying signatures

Node.js pseudo code of your webhook HTTP request handler.

GraphQL Playground

All the GraphQL queries can be sent via the or as a HTTP POST request to https://api.uat.flash-payments.com.au. Example:

All the responses are JSON and have at least one property data and optional property errors.

Some of the GraphQL query parameters are required, others are optional. To understand if a variable/property is required you would need to check the API schema.

• Go to the and click the button "DOCS" on the right.

• Browse through queries, mutations, input and output types. Find a variable/property which have an exclamation mark at the end. E.g. fromCurrency: FromCurrency!.

• The exclamation mark denotes that the variable/property is mandatory.

Data cleansing is your responsibility

The user-agent HTTP header

It is a good idea to always send custom user-agent HTTP header value when doing requests to Flash Payments API. Here is why:

• In case of troubleshooting we will be able to trace and mitigate your support questions faster.

• You might be blocked by our automated firewall if your user agent is something generic like curl, Java-http-client, python-requests, Ruby, etc.

429 Too many requests

Our API have smart monitoring and it may temporarily block your IP if it detects system misuse. For more information, please refer to the page.

This query returns the same data as the Download CSV button on the Account Statement page of the Flash Connect.

The dates must be any ISO 8601 formatted dates.

const bodyJSON = {
  variables: {

query($input: StatementQueryInput!) {
  statement(

{
  "input": {
    "fromDate": "2023-08-28T00:00:00+03:00",
    "currency": "USD"
  }
}

{
  "data": {
    "statement": [
      {
        "success": true,
        "code": "GENERATED",
        "message": "Statement generated",
        "fromDate": "2023-08-27T21:00:00Z",
        "toDate": "2023-08-28T21:00:00Z",
        "rows": {
          [
            {
              "debit": 123.45,
              "credit": 0
            }
          ]
        }
      }
    ]
  }
}

The response dates are aways UTC. Timezones are always taken into account.

For your initial tests, it may be easier and more practical to send data by embedding values directly into the GraphQL queries and mutations, as shown in the example below.

At the same time, to enable efficient and accurate handling of complex queries in code, we support sending GraphQL queries as JSON objects that consist of two properties: "query" and "variables". Here is how you can do it:

• Declare the $input variable in the QraphQL "query"

Adverse Media Search (AMS) lets you screen an individual or organisation against web-based adverse media sources — news articles, court records, and other publicly available content.

You can via the adverseMediaSearch mutation or past searches via the amsRequest and

Before doing any other API calls you have to obtain an auth token. It's a standard JWT token carrying the following payload:

{
  ...

  "iat": 1620967717,
  "exp": 1621054117
}

The token lifetime is 4 hours at this time. We might change this value in the future.

To be more future-proof, it is recommended to parse the token payload and compare current time to the token's expiration time. JavaScript code:

Getting a token

1. After we enable you, go to the , click "DOCS" on the right to explore the possibilities.

2. Find there the login mutation. Execute it to obtain your access token. For example: mutation { login(input: {email: "YOUR_EMAIL" password: "YOUR_PWD"}) {token message} }

Here is an example of the login query.

If using then click the "HTTP HEADERS" on the bottom left and paste there the following (replace the YOUR_TOKEN with the value you have just received form the above mutation):

Affiliation

Clients that have contractual agreements with more than one subsidiary of Flash Payments, can use the optional field affiliation to control which account to log into.

The affiliation field accepts one of two constant values - FP_AUS or FP_LUX - which are passed unquoted.

If the affiliation value does not correspond to an existent account, authentication will fail with code UNREGISTERED even if an account exists with another affiliation and the credentials are correct.

If the user has multiple affiliations and the field affiliation is omitted, authentication will fail with code NEED_AFFILIATION.

Event notifications with webhooks

Flash Payments uses webhooks to notify your application when a transaction event happens in your account. This includes status update of your withdrawal, clearing of the incoming deposit, and more.

With webhooks, you can subscribe to the events of interest to trigger a subsequent action within your integration.

There are two steps to begin using webhooks. Building a custom endpoint on your server and registering it via the FlashConnect settings.

Building webhook endpoint

Each time a transaction event happens, we will send a HTTP POST request to your endpoint(s) that are subscribed to that event. The payload with event data is in the JSON format and can be used immediately. Every webhook endpoint must acknowledge the request, and as we strongly advise, verify the webhook signature.

Acknowledging request

To acknowledge the receipt of the event, your endpoint must return 2xx HTTP status code. All other response codes, including 3xx codes, indicate that you did not receive the event.

If we do not receive 200 HTTP status code, we will make up to 3 more request attempts. There is 6, 60 and 600 seconds delay between each delivery attempt respectively. If all request attempts fail, we mark webhook request as failed and will no longer try to deliver it.

Each webhook request has a flashfx-request-id header with a string that uniquely identifies a webhook event. For example, if there are multiple delivery attempts for the webhook event, each request will hold the same flashfx-request-id. This can be used to check if the webhook event was already processed by your application.

We advise that you acknowledge webhook request as early as possible.

Securing the request

To ensure that webhook was sent by Flash Payments and not a third party, we include the cryptographic signature in each request’s flashfx-signature header.

Before you can verify a signature, you need to retrieve your endpoint’s secret from webhook settings in the . Each registered endpoint has a unique secret that is used to sign a payload delivered to you on each event. Steps to verify signature:

1. Extract signature from the request header

2. Compute HMAC with SHA256 function. Use your endpoint secret as key and JSON payload string as a message.

3. Compare signature in the header to the computed signature.

Here is a Node.js pseudo code to generate and compare signatures

And verifying signature

Testing your endpoint

To make sure your webhook endpoint is setup correctly, you can make a test HTTP request from the webhook settings. Click the "Send Test” button. You should receive a dummy request, which will need to be acknowledged the same way as your real webhook requests.

Then go to the history of the webhook requests and find the test request and response there.

Subscribing to the events

Webhook requests come with event data. You can see all available event types in the settings. To subscribe, select which events you would like to receive and specify your endpoint. Please note, your endpoint must adhere to the HTTPS protocol for security reasons.

To convert between, say, AUD and EUR you should:

1. Request a tradeable quote with applicability: CONVERSION.

2. Retrieve the quote ID from the response.

3. Reference the quote ID when creating the conversion.

Get a tradable quote ID:

Convert funds:

Query all deposits

const bodyJSON = {
  variables: {

query($input: DepositQueryInput!) {
  deposits(

{ 
  "input": {
  }
}

{
  "data": {
    "deposits": [
      {
        "id": "6053d4e0e3bc655e0598a742",
        "amount": 2000,
        "currency": "AUD",
        "status": "CONFIRMED",
        "statusMessage": "Transaction Confirmed",
        "externalId": "PR.1vcl",
        "externalReference": "FX1111",
        "subClient": null,
        "createdAt": "2021-03-18T22:32:01.010Z"
      },
      {
        "id": "6053d3319588389e1443587e",
        "amount": 40,
        "currency": "AUD",
        "status": "CONFIRMED",
        "statusMessage": "Transaction Confirmed",
        "externalId": "PR.1vci",
        "externalReference": "FX2121",
        "subClient": {
          "id": "5fb314cb9224595df522db61",
          "fullName": "John Doe",
          "status": "ACTIVE",
          "clientType": "INDIVIDUAL"
        },
        "createdAt": "2021-03-18T22:24:49.096Z"
      },
    ]
  }
}

Query deposit by ID

1. You create a withdrawal. Your balance goes down by the withdrawal amount plus fee. INITIALISED

   1. We might internally review the transaction. INITIALISED-> REVIEWING

   2. If review goes well it will become pending. REVIEWING→ PENDING

   3. Otherwise it gets cancelled. REVIEWING→ CANCELLED

2. The transaction is sent to the recipient bank for processing. INITIALISED → PENDING

3. PENDING →

   • CONFIRMED - the recipient bank has the money now. Does not mean the beneficiary account number was credited though. Mostly FINAL status. Except when bank decides to return the funds, the withdrawal gets refunded (see step 4).

4. The recipient bank decided to return this transaction back to Flash Payments.CONFIRMED → FAILED → REFUNDED - usual way - automatic refunding. Your balance goes up by the withdrawal amount, Flash Payments keeps the fee. FINAL status.

Most common status transitions

Happy path

INITIALISED→REVIEWING→PENDING→CONFIRMED

Unhappy paths

Recipient bank accepts the payout but then returns it:

INITIALISED→PENDING→CONFIRMED→FAILED→REFUNDED

Recipient bank rejects the payout:

INITIALISED→PENDING→FAILED→REFUNDED

Flash Payments Compliance team rejects the payout:

INITIALISED→REVIEWING→CANCELLED

Testing/simulating unhappy paths

Typically, you want to adapt your system to handle the following common withdrawal scenarios:

1. Too long in the REVIEWING status

If your withdrawal is in this status this means that we are doing an internal review of it. It happens occasionally when you trigger our monitoring rules. Also, this means that we have sent your Compliance Team (or else) an email message requesting more information. You must respond. In other words, if there is a delay - it's on you. Because Flash Payments delivers all your transactions in real-time 24/7.

You can simulate the behaviour. Your externalReference must include this text: HALT_AML. For example: "testing HALT_AML attempt 2". The withdrawal will get stuck in REVIEWING forever.

2. Fails AML and gets cancelled

We checked the data you sent us for withdrawal. We didn't like it. So we cancel it immediately.

You can simulate the behaviour. Your externalReference must include this text: FAIL_AML. For example: "testing FAIL_AML attempt 4". The withdrawal will be cancelled next moment after you submit it.

3. Passes AML and gets processed

If our smart AML/TM checks stop your withdrawal for manual review, you can have it automatically pushed forward by including PUSH_AML in the externalReference. For example: "testing PUSH_AML attempt 5". This enables the transaction to continue as if it were approved by the compliance analyst. It can be particularly useful during your integration testing activities and also help with UAT regression testing later.

Please note that the REVIEWING status for this payout will be recorded on our end, and a withdrawal_reviewing webhook will be sent.

4. Recipient bank rejects the money

A common scenario in the Australian domestic payment system involves a transaction that appears successful initially, but is later reversed by the recipient’s bank—sometimes days after processing. This can happen for various reasons, such as an invalid or closed account number, an account in the wrong currency, or other account-related issues.

You can simulate the behaviour. Your externalReference must include this text: FAIL_ACC. For example: "testing FAIL_ACC attempt 8". The withdrawal will be completed, and next moment failed and refunded.

Please verify that you have all the required data to initiate a successful payment transfer.

List all the available payment delivery methods

const bodyJSON = {
  variables: {

query($input: AvailableDeliveryMethodsInput!) {
  availableDeliveryMethods

{ 
  "input": {
  }

{
  "data": {
    "availableDeliveryMethods": [
      {
        "country": "AE",
        "currency": "AED",
        "method": "ACC_NO",
        "requiredFields": [
          "bic",
          "accountNo"
        ]
      },
      {
        "country": "AT",
        "currency": "EUR",
        "method": "IBAN",
        "requiredFields": [
          "bic",
          "iban"
        ]
      },
...

The response above means that if you want to send euros to Austria (AT) then you'd need a BIC (aka SWIFT) code and an IBAN.

List some of the delivery methods

The response above means that to send euros to France (FR) you have to have ether of:

• BIC and an account number, or

• BIC and an IBAN.

Instructing Institution

Institution entity is a piece of information about the party who instructed you to make the withdrawal. This data is important for compliance within Australia. This is not the sender. If there is no other institution who has instructed this withdrawal, leave this blank and your own details will be used for compliance and auditing purposes.

Creating institutions

• via Flash Connect (you can copy an ID of an existing Institution).

• via API by invoking createInstitution mutation.

• by providing instructingInstitution object into createWithdrawal

Creating institution example

Confirmation of Payee (CoP) is a security feature that verifies whether an account holder's name matches the account details you provide. It helps to:

• Reduce fraud by verifying the account holder's name before sending funds

• Prevent accidental payments to wrong accounts due to mistyped details

Retrieving all your payments

Here is the list of all possible CoP response codes.

1. - query bank information to validate if we support your BSB, IBAN, BIC (aka Swift code).

2. depositDetails - query the accounts you can send deposits to in order to increase your Flash Payments master balance.