Collect Payments

To Collect is to pull funds from a user (also know as the payer).

Example: Piper Pay, a PFM app, charges a monthly $2.99 subscription fee for their customers to continue using their service. On the 1st of every month, they will collect this fee from their customers using the Basiq API.

How does collect appear?

All payrequests submitted on an Australian business day before 7pm will appear as individual payments on your payers' bank accounts. All the funds cleared and settled will be credited to your dedicated float account. You will then be able to Send workflow those funds out from your float account.

Example: Piper Pay has 10 active users, so when they charge all users on the 1st of the month, each user will have a single transaction of $2.99 on their individual bill.

Example: Piper Pay has 10 active users, so when they charge all users on the 1st of the month, each user will have a single transaction of $2.99 on their individual bill, and Piper Pay will have one bulk transaction of $29.90.

Prerequisites for using Collect

The paying 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 paying 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.

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

Collect using Basiq's Consent UI

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

Steps

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.
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.

Once they have selected the payments account you can start collecting payments from the user by submiting payment requests, including in the request:
- requestId: A unique ID generated by the partner application
- amount: The amount of the payment you are collecting
- description: The description to be included on the payment
- payerUserId: Basiq’s unique identifier given when they are created with Basiq

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

{
    "payrequests": [
        {
            "requestId": "01824ad0-73f1-0138-3700-0a58a9feac09",
            "amount": 123.20,
            "description": "Investment",
            "payer": {
                "payerUserId": "21824ad0-73f1-0138-3700-0a58a9feac09"
            }
        }
    ]
}

The response will contain the job resource responsible for processing this payment request. It will not return the payment itself. You can use this job to track the progress of the payment request and know when it has successfully completed.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "type": "job",
  "id": "b1824ad0-73f1-0138-3700-0a58a9feac09",
  "requestId": "01824ad0-73f1-0138-3700-0a58a9feac09",
  "links": {
    "self": "https://au-api.basiq.io/jobs/b1824ad0-73f1-0138-3700-0a58a9feac09"
  }
}

Use the job.Id you receive to track the payment requests progress via the job endpoint Jobs . You can continue to poll this endpoint regularly to stay updated of the success/failure of your request.

{
  "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/payrequests/33454ad0-73f1-0138-3700-0a58a9feac09"
      }
    },
    {
      "title": "external-processing",
      "status": "success",
      "result": {
        "type": "link",
        "url": "/payments/payrequests/33454ad0-73f1-0138-3700-0a58a9feac09"
      }
    },
    {
      "title": "payment-completed",
      "status": "success",
      "result": {
        "type": "link",
        "url": "/payments/payrequests/33454ad0-73f1-0138-3700-0a58a9feac09"
      }
    }
  ],
  "links": {
    "self": "/jobs/33454ad0-73f1-0138-3700-0a58a9feac09",
    "source": "/payments/payrequests/33454ad0-73f1-0138-3700-0a58a9feac09"
  }
}

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

You can use Use the returned job.Id you receive to enquire about the payment requests progress by calling Retrieve a payment request

{
  "type": "payrequest",
  "id": "f7824ad0-73f1-0138-3700-0a58a9feac0f",
  "requestId": "01824ad0-73f1-0138-3700-0a58a9feac09",
  "created": "2022-03-21T20:28:22.378Z",
  "updated": "2022-03-21T20:28:22.378Z",
  "method": "batch",
  "status": "in-progress",
  "payer": {
    "payerUserId": "21824ad0-73f1-0138-3700-0a58a9feac09",
    "payerBankBranchCode": "730002",
    "payerAccountNumber": "123456789"
  },
  "description": "Spaceship Investment",
  "amount": 173.45,
  "currency": "AUD",
  "links": {
    "self": "/payments/payrequests/f7824ad0-73f1-0138-3700-0a58a9feac0f",
    "job": "/jobs/f7824ad0-73f1-0138-3700-0a58a9feac0f"
  }
}

Check account balance as part of collect flow

When performing a payrequest, you can optionally opt to check the account balance as part of processing the payrequest by passing checkAccountBalance=true.

It is important to keep in mind that using this flag does not guarantee that the payment will succeed and is based on best efforts. This is due to a wide range of factors being:

The debit is sent from our systems and our processing partner on batch based schedule.
There might be multiple banks in the chain before the payment reaches the actual payer bank
Payer banks process direct debits at different time based on their systems.
The balance check performed within Basiq against the payer user is cached and not performed in real time. That balance check could be 10 hours old. Meaning it could be different to the actual balance in the payer's account. We are unable to perform this check in real time as we are limited by how many times we are allowed to refresh account balance data.

Collect using application Direct Debit request form

Alternatively, partners can maintain their own onboarding flow and present users with the Direct Debit Service and Direct Debit Service Request Authority.

In order to do this partners must ensure as part of onboarding their user onto their platform that they have read, and agree to, the terms in the Direct Debit service. The partner should store the signed Direct Debit service in their records in order to manage any disputes. A copy of the Direct Debit Service and Direct Debit Service Request Authority can be found here.

The partner can submit payrequests for collecting funds similar to the flow above with the exception of indicating the payer account numbers as part of submitting the payrequest as outlined below

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

{
    "payrequests": [
        {
            "requestId": "01824ad0-73f1-0138-3700-0a58a9feac09",
            "amount": 123.20,
            "description": "Investment",
            "payer": {
                "payerUserId": "21824ad0-73f1-0138-3700-0a58a9feac09",
                "payerBankBranchCode": "730002",
                "payerAccountNumber": "123456789"
            }
        }
    ]
}

Automatic bulk payout of collect funds

As part of enabling payments for your business, you can elect to automatically pay out funds settled from collect to your primary bank account. In this case, all the payrequests funds settled on a business day will be rolled into one single credit appearing on the nominated bank account that is supplied to Basiq upon enabling payments. The reference on that bulk credit to your nominated bank account will look like Zepto {reference} where the reference is a 9 character code (e.g. Zepto CT.a1wh3).