Developer hub
← Back HomeNPMDeveloper HubAPIBlog

Send Payments

Suggest Edits

 

 

To Send is to pay out funds from your float account to one of your users or your own account held at a bank.

Example: Piper Pay, an investment app, has been holding investment funds for one of its users, Adam. Adam has made a profit on his investment and instructs Piper Pay to pay out the profits to his account. Upon receiving the instruction to pay out the profits, Piper Pay would call the Basiq Send (payouts) API to send the funds from their float account to Adam's account at ANZ.

Send payment methods

When performing a payout instruction, partners have the ability to indicate the payment method as fast, batch, or fast/batch. The details of each one are as follows:

  • fast means the payout will be transmitted over fast/real-time payments networks (e.g. NPP / OSKO in Australia) provided the recipient bank and account can accept fast payments. In this case funds should land in the recipient bank account within a minute in most cases.
  • batch means the payout will be transmitted over batch payments networks (e.g. BECS/DE in Australia). In this case funds should land in the recipient bank account within 2 business days
  • fast/batch means the payout will first be attempted to be sent over the fast/real-time network and if a failure occurs (e.g. the recipient bank and/or account is not enabled for fast/real-time) then the payout will be sent as a batch payment.

Prerequisites for using Send

  • The payee user must be set up as active in the partner application, and therefore have a userId to associate the payment with. Read more about creating a user here
  • The payee user must have a valid user name and email address. This includes having a first name with a minimum of 2 characters and a last name with a minimum of 2 characters and the email address exist and be a valid email address.
  • The application must be enabled for payments by Basiq, with the appropriate environment setup. You can enable the application for payments in Sandbox or request production access through the Basiq dashboard.
  • You should have enough funds in the float account in order to perform payouts. All payouts are sent out using funds you have in the float account held by Basiq and/or its 3rd party partners/providers. Please refer to Managing float accounts

Alternatively you can always reach out to [email protected] if you have not already.

Send to payees with consented payment accounts

One of the main benefits of using Basiq for payments is the ability to tie in data with payments in one platform. Through this combination you can get your users to share their accounts details and select which accounts to use for payments all in a single flow. Here is how to achieve that

As a prerequisite you will require to trigger payments flow from your redirect URI by adding payment as an action to enable capture of payments accounts.

Steps

  1. After creating a user you will need to direct them to the consent flow as detailed here Basiq's Consent UI passing the action=payment step to show the payment consent.

  2. After the user selects the accounts they wish to share, they will be presented with the payments page where they specify which account to use for payments.

582
  1. Once they have selected the payments account you can submit a payout instruction Submit payouts, including in the instruction:
    • requestId: A unique ID generated by the partner application
    • amount: The amount of the payment you are paying out
    • description: The description to be included on the payment
    • payeeUserId: Basiq’s unique identifier given when they are created with Basiq
    • method: Indicating if it is a fast, batch, or fast/batch as detailed above 
POST /payments/payouts HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic $YOUR_ACCESS_TOKEN

{
    "payouts": [
        {
            "requestId": "01824ad0-73f1-0138-3700-0a58a9feac09",
            "method": "fast",
            "amount": 512.56,
            "description": "Investment profits",
            "payee": {
                "payeeUserId": "21824ad0-73f1-0138-3700-0a58a9feac09"
            }
        }
    ]
}
  1. The response will contain the job resource responsible for processing this payout. It will not return the payment itself. You can use this job to track the progress of the payout and know when it has successfully completed. 
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "type": "job",
  "id": "33454ad0-73f1-0138-3700-0a58a9feac09",
  "requestId": "01824ad0-73f1-0138-3700-0a58a9feac09",
  "links": {
    "self": "https://au-api.basiq.io/jobs/33454ad0-73f1-0138-3700-0a58a9feac09"
  }
}
  1. Use the job.Id you receive to track the payouts' progress via the Jobs You can continue to poll this endpoint regularly to stay updated of the success/failure of your payouts.

Note: The jobId returned can also be used to retrieve the payout directly via the API

{
  "type": "job",
  "id": "33454ad0-73f1-0138-3700-0a58a9feac09",
  "created": "2016-06-08T09:10:32.000Z",
  "updated": "2016-06-08T09:14:28.000Z",
  "steps": [
    {
      "title": "validate-payment",
      "status": "success",
      "result": {
        "type": "link",
        "url": "/payments/payouts/33454ad0-73f1-0138-3700-0a58a9feac09"
      }
    },
    {
      "title": "external-processing",
      "status": "success",
      "result": {
        "type": "link",
        "url": "/payments/payouts/33454ad0-73f1-0138-3700-0a58a9feac09"
      }
    },
    {
      "title": "payment-completed",
      "status": "success",
      "result": {
        "type": "link",
        "url": "/payments/payouts/33454ad0-73f1-0138-3700-0a58a9feac09"
      }
    }
  ],
  "links": {
    "self": "/jobs/33454ad0-73f1-0138-3700-0a58a9feac09",
    "source": "/payments/payouts/33454ad0-73f1-0138-3700-0a58a9feac09"
  }
}
  1. You can use Use the returned job.Id you receive to enquire about the payouts progress by calling Get a payout by its basiq Id 
{
    "type": "payout",
    "id": "33454ad0-73f1-0138-3700-0a58a9feac09",
    "requestId": "01824ad0-73f1-0138-3700-0a58a9feac09",
    "created": "2022-11-10T12:01:24Z",
    "updated": "2022-11-10T13:00:33Z",
    "method": "fast",
    "requestedMethod": "fast",
    "status": "successful",
    "payer": {
        "payerUserId": "21824ad0-73f1-0138-3700-0a58a9feac09",
        "payerBankBranchCode": "730002",
        "payerAccountNumber": "123456787",
        "payerAccountId": "100f1793-bb73-4c77-a3c8-d8497801191f"
    },
    "description": "Investment profits",
    "amount": 512.56,
    "currency": "AUD",
    "links": {
        "self": "https://au-api.basiq.io/payments/payouts/33454ad0-73f1-0138-3700-0a58a9feac09",
        "job": "https://au-api.basiq.io/jobs/33454ad0-73f1-0138-3700-0a58a9feac09"
    }
}

Send to payees without consented payment accounts

  1. One you have a user setup as per the prerequisites above you can submit a payout instruction Submit payouts, including in the instruction:
    • requestId: A unique ID generated by the partner application
    • amount: The amount of the payment you are paying out
    • description: The description to be included on the payment
    • payeeUserId: Basiq’s unique identifier given when they are created with Basiq
    • payeeBankBranchCode: The code of their bank and branch (BSB for Australia)
    • payeeAccountNumber: The account number
    • method: Indicating if it is a fast, batch, or fast/batch as detailed above

 

POST /payments/payouts HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic $YOUR_ACCESS_TOKEN

{
    "payouts": [
        {
            "requestId": "01824ad0-73f1-0138-3700-0a58a9feac09",
            "method": "fast/batch",
            "amount": 512.56,
            "description": "Investment profits",
            "payee": {
                "payeeUserId": "21824ad0-73f1-0138-3700-0a58a9feac09",
                "payeeBankBranchCode": "730002",
                "payeeAccountNumber": "123456787"
            }
        }
    ]
}
  1. The response will contain the job resource responsible for processing this payout. It will not return the payment itself. You can use this job to track the progress of the payout and know when it has successfully completed. 
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "type": "job",
  "id": "33454ad0-73f1-0138-3700-0a58a9feac09",
  "requestId": "01824ad0-73f1-0138-3700-0a58a9feac09",
  "links": {
    "self": "https://au-api.basiq.io/jobs/33454ad0-73f1-0138-3700-0a58a9feac09"
  }
}
  1. Use the job.Id you receive to track the payouts' progress via the get job endpoint. You can continue to poll this endpoint regularly to stay updated of the success/failure of your payouts.

Note: The jobId returned can also be used to retrieve the payout directly via the API

{
  "type": "job",
  "id": "33454ad0-73f1-0138-3700-0a58a9feac09",
  "created": "2016-06-08T09:10:32.000Z",
  "updated": "2016-06-08T09:14:28.000Z",
  "steps": [
    {
      "title": "validate-payment",
      "status": "success",
      "result": {
        "type": "link",
        "url": "/payments/payouts/33454ad0-73f1-0138-3700-0a58a9feac09"
      }
    },
    {
      "title": "external-processing",
      "status": "success",
      "result": {
        "type": "link",
        "url": "/payments/payouts/33454ad0-73f1-0138-3700-0a58a9feac09"
      }
    },
    {
      "title": "payment-completed",
      "status": "success",
      "result": {
        "type": "link",
        "url": "/payments/payouts/33454ad0-73f1-0138-3700-0a58a9feac09"
      }
    }
  ],
  "links": {
    "self": "/jobs/33454ad0-73f1-0138-3700-0a58a9feac09",
    "source": "/payments/payouts/33454ad0-73f1-0138-3700-0a58a9feac09"
  }
}
  1. You can use Use the returned jobId you receive to enquire about the payouts progress by calling Get a payout by its basiq Id 
{
    "type": "payout",
    "id": "33454ad0-73f1-0138-3700-0a58a9feac09",
    "requestId": "01824ad0-73f1-0138-3700-0a58a9feac09",
    "created": "2022-11-10T12:01:24Z",
    "updated": "2022-11-10T13:00:33Z",
    "method": "fast",
    "requestedMethod": "fast/batch",
    "status": "successful",
    "payee": {
        "payeeUserId": "21824ad0-73f1-0138-3700-0a58a9feac09",
        "payeeBankBranchCode": "730002",
        "payeeAccountNumber": "123456787",
        "payeeAccountId": "100f1793-bb73-4c77-a3c8-d8497801191f"
    },
    "description": "Investment profits",
    "amount": 512.56,
    "currency": "AUD",
    "links": {
        "self": "https://au-api.basiq.io/payments/payouts/33454ad0-73f1-0138-3700-0a58a9feac09",
        "job": "https://au-api.basiq.io/jobs/33454ad0-73f1-0138-3700-0a58a9feac09"
    }
}

Updated 6 months ago