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.

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 application must be enabled for payments by Basiq, with the appropriate environment setup. Reach out to [email protected] if you have not already.
  • The paying user must be set up and active in the partner application, and therefore have a userId to associate the payment with. Read more about creating a user here

Collect using your application Direct Debit request form

  1. Before anything, 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.

  2. Once this has been confirmed, partners can collect funds 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
    • payerBankBranchCode: The payers bank branch code (BSB)
    • payerAccountNumber: The payers account number

 

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"
            }
        }
    ]
}
  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 track 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 Basiq's Consent UI: Coming soon..


Did this page help you?