Collect workflow

321321

 

To Collect is to pull funds from a user, into your bank account - initiated by the payee.

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, however 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).

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

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

As a prerequisite you will need to access your application via the Basiq dashboard and enable capture of payments accounts

31043104
  1. After creating a user you will need to direct them to the consent flow as detailed here Basiq's Consent UI.

  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.

582582
  1. 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"
            }
        }
    ]
}
  1. 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"
  }
}
  1. Use the job.Id you receive to track the payment requests progress via the get job endpoint. 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

  1. 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"
  }
}

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. This can be found here.

The partner can they 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"
            }
        }
    ]
}