We now offer our merchants the ability to receive payments, in real-time, from their customers' bank account using a unique email PayID linked only to that customer. By referencing a unique PayID to each of your Contacts, any payments received via that PayID can be easily reconciled to a specific customer, allowing the real-time delivery of payments to help power your business.

If you wish to use this feature, it will need to be enabled on your account. You can reach out to us at support@splitpayments.com.au, or click on the blue intercom button in the bottom right and ask us to enable this for you.

NOTE: This article outlines the process you need to follow in order to create these unique PayIDs before passing them back to your customers to start making payments.

High-Level Flow

Each of these steps is described in detail below:

  • Set-up
  • Step 1 - Create a Contact with PayID
  • Step 2 - Listen for the PayID registration final state
  • Step 3 - Expose PayID to your customer
  • Step 4 - Reconcile received payments
  • Step 5 - Transfer funds from your Float account into your Bank account
  • Step 6 - Reporting
  • Contact and PayID Management
  • FAQ's

Set-up

We will require the following information to enable the PayID feature:

  • Full legal entity name
    - e.g. Spaceships PTY Ltd.
  • PayID alias name that customers will see when they enter the supplied PayID
    - e.g. Spaceships Australia
  • A legally owned domain that will be used after the @ in the PayID email address
    - e.g. pay.spaceships.com.au
  • Example PayID email addresses to ensure relevance to end customers
    - e.g. elon11223344@pay.spaceships.com.au

We will then enable your Split Payment account with a receivable Float Account.

This account will hold all of the payments you receive via your PayID's. It's balance can be viewed through the Split Payments' UI and API.

You may then withdraw float funds to an external bank account at any time. For more information see step 5.

Step 1 - Create a Contact with PayID

The first step is to create a receivable Contact with your chosen PayID email. This can be done using our POST /contacts/receivable endpoint.

This endpoint requires the following mandatory fields:

  • customer's full name
  • personal email address
  • a unique and relevant PayID

Restrictions:

  • The requested PayID email address must be unique for each customer
  • You control the username part of the email address, before the @ symbol. We suggest an approach where a combination of first name and an internal customer number is used to generate a unique username, for example:
    - elon11223344
  • The domain following the @ symbol must match the verified domain provided to Split, for example:
    - pay.spaceships.com.au
  • The final value for the "payid_email" attribute should look similar to:
    - "payid_email": "elon11223344@pay.spaceships.com.au"
  • Once a PayID has been successfully registered, it cannot be changed.

Endpoint: POST /contacts/receivable

Request Payload:

{
"name": "Elon Musk",
"email": "elon_thespaceman@gmail.com",
"payid_email": "elon11223344@pay.spaceships.com.au",
"metadata": {
"custom_key": "Maybe a customer number",
"another_custom_key": "Maybe a mobile number"
}
}

Response [201]:

{
"data": {
"id": "a7565a92-a570-4ad1-b5c9-e6763e8af42e",
"name": "Elon Musk",
"email": "elon_thespaceman@gmail.com",
"type": "anyone",
"metadata": {
"custom_key": "Maybe a customer number",
"another_custom_key": "Maybe a mobile number"
},
"bank_account": {
"id": "2df3ec05-d0bc-4b3a-a102-45224844255e",
"account_number": "12345678",
"branch_code": "802919",
"bank_name": "Split Float Account",
"state": "active",
"iav_provider": null,
"iav_status": null,
"blocks": {
"debits_blocked": false,
"credits_blocked": false
}
},
"anyone_account": {
"id": "9e03589a-454e-4501-a8e3-f8bb918f850a"
},
"payid_details": {
"alias_value": "elon11223344@pay.spaceships.com.au",
"alias_type": "email",
"alias_name": "Spaceships Australia",
"state": "pending"
}
}
}

What happens after the POST /contacts/receivable request is successful?

Split will:

  • create a 'Contact'
  • respond with a 201
  • return all of the stored information inside the response, including a special payid_details object where the state will always be returned as pending.

NOTE: The full end-to-end process of creating a PayID typically takes less than 1 minute, but can on rare occasions take anywhere up to 5 minutes. Due to this, the final payid_details.state must be retrieved asynchronously.

There are 2 methods to receive this final status which are described in step 2.

Before retrieving this, the Contact id should be stored against your internal customer record. This will help to identify:

  1. The asynchronous webhook callback after the PayId has been successfully registered (see step 2).
    id == id
  2. The real-time payment received notification webhook allowing you to credit those funds into your customer's account (see step 4).
    id == authoriser_contact_id
  3. The PayID float account settlement notification (see step 5).
    id == party_contact_id

Potential error messages on initial Contact creation:

There are a number of errors that may be returned when attempting to create a new PayID receivable Contact.

{ 
"errors": "PayID is not enabled for your account."
}

Your account has not been enabled for receivable PayIDs. Get in touch with our support team to check your account.

{ 
"errors": "PayID is not a valid email address."
}

The submitted payid_email was not constructed as a valid email address. This value should adhere to standard email address formatting and follow the guidelines mentioned previously under Restrictions.

{ 
"errors": "PayID domain pay.spaceships.com.au has not been approved by Split."
}

The email address domain does not match the domain provided on set-up. Check that these values match or contact us if this has changed.

{ 
"errors": "PayID elon11223344@pay.spaceships.com.au has already been used."
}

The submitted payid_email has already been used to create a Contact. Generate a new PayID for this Contact and resubmit.

Step 2 - Listen for the PayID registration final state

At this stage, you should have successfully created a new Contact, and stored the id that was returned in the response. This id is paramount in identifying which Contact had their PayID successfully registered. But before we look at how to discover this final state, it's important to know that there are 2 possible final states:

  1. Successful registration
  2. Failed registration

1. Successful Registration

The requested PayID has been successfully registered and the payid_details.alias_value can now be stored against your customer record, exposed through your relevant channels, and retained for the duration of the relationship with that customer.

"payid_details.state": "success"

2. Failed Registration

This should be an extremely rare situation, but if encountered please get in touch with our support team.

"payid_details.state": "fail"

This can occur if a PayID email has already been registered. To avoid this, ensure that the provided email domain is completely unique and not in use for staff/customer email addresses.

How can we discover what the final PayID registration state is?

We offer 2 options to asynchronously discover the final state.

Option 1 (Preferred): Subscribe to the Contact webhooks for real-time notifications on registration status. This can be accessed by signing-in to your Split Payment account. For more detailed information on our webhooks see here.

An example of the PayID Registered webhook is displayed below:

{
"data": [
{
"id": "a7565a92-a570-4ad1-b5c9-e6763e8af42e",
"name": "Elon Musk",
"type": "anyone",
"email": "elonmusk@spaceships.com",
"metadata": {},
"bank_account": {
"id": "fdb03fbc-df8c-4e54-a66d-e931044d5e1c",
"state": "active",
"blocks": {
"debits_blocked": false,
"credits_blocked": false
},
"bank_name": "Split Float Account",
"iav_status": null,
"branch_code": "802919",
"iav_provider": null,
"account_number": "1065042"
},
"anyone_account": {
"id": "5f05846b-1c65-40f9-b918-f0dc455550c2"
},
"payid_details": {
"state": "active",
"alias_name": "Spaceships Corp",
"alias_type": "email",
"alias_value": "elon11223344@pay.spaceships.com.au"
}
}
],
"event": {
"at": "2020-11-26T22:26:02Z",
"who": {
"account_id": "1b1985dc-9a47-410c-bfd7-d987d72a1197",
"account_type": "Account"
},
"type": "contact.payid_registered"
}
}

This webhook contains all of the information required to identify who this PayID registered update is for, specifically by using:

The contact id stored from step 1

"id": "a7565a92-a570-4ad1-b5c9-e6763e8af42e"

The supplied PayID value

"alias_value": "elon11223344@pay.spaceships.com.au"

For more detailed information on our webhooks see our article on Webhooks.

Option 2: Poll our GET /contacts/{id} endpoint using the Contact id returned in the response from step 1. If going with this option, we recommended polling every 30 seconds.

Step 3 - Expose PayID to your customer

At this stage, Split's Contact ID and PayID should be stored against your customer record. The PayID can now be displayed to your customer through the relevant channels.

Tip: To reduce human error and improve customer experience we suggest enabling a copy function to allow easier entry into their banking platform.

Tip 2: If you wish to display the PayID logo to your customer you must accept the NPPA's PayID terms and conditions, download the official PayID logo pack and adhere to their brand guidelines as described here.

Step 4 - Reconcile received payments

Step 4a - Split receives your customer's payment

As soon as Split receives a payment from one of your customers, you will be notified via our PaymentRequest.Approved webhook. These funds initially sit in Splits main account and are moved into your PayID enabled float account using what we call a Payment Request.

A Payment Request is automatically created from your PayID enabled float account to your PayID contact. By subscribing to this webhook we will notify you in real-time when the funds have been received, allowing you to trigger the crediting of those funds into your customer's account and any other business processes you may have.

NOTE: At this stage, you have total assurance that the funds are processing into your PayID enabled float account.

An example of the PaymentRequest.Approved webhook is displayed below:

{
"data": [
{
"ref": "PR.pnb",
"payout": {
"amount": 2500,
"matures_at": "2020-11-26T13:00:00Z",
"description": "1"
},
"status": "approved",
"created_at": "2020-11-26T22:23:09Z",
"credit_ref": "C.3dv9",
"matures_at": "2020-11-26T13:00:00Z",
"initiator_id": "1d0eac6b-a81d-4bad-ab9e-8006b16aa185",
"responded_at": "2020-11-26T22:23:09Z",
"schedule_ref": null,
"authoriser_id": "c0dd0b3b-555e-41ec-983e-14f7b6e7dc59",
"status_reason": null,
"your_bank_account_id": "1d0eac6b-a81d-4bad-ab9e-8006b16aa185",
"authoriser_contact_id": "a7565a92-a570-4ad1-b5c9-e6763e8af42e"
}
],
"event": {
"at": "2020-11-26T22:23:09Z",
"who": {
"account_id": "ba5c54ce-de1e-4355-9864-fdd7b90fbae0",
"account_type": "AnyoneAccount",
"bank_account_id": "c0dd0b3b-555e-41ec-983e-14f7b6e7dc59",
"bank_account_type": "BankAccount"
},
"type": "payment_request.approved"
}
}

This webhook contains all of the information required to identify who made the payment, and it's value:

Value (cents)

"payout.amount": 2500

Who (the id stored from Step 1)

"authoriser_contact_id": "2eea479d-7b00-4002-8a16-6cfeac6cedc9"

Step 4b - Funds become available in your PayID enabled float account

To be notified once the payment has been cleared into your float account, you must subscribe to our credit.cleared webhook for real-time clearance notifications. Until they fully clear, which can take up to 3 minutes, these funds will not appear as an available balance on the float account.

An example of the Credit.Cleared webhook is displayed below:

{
"data": [
{
"ref": "C.34jt",
"type": "credit",
"amount": 2500,
"status": "cleared",
"bank_ref": "CT.2kee",
"category": "payout",
"channels": [
"direct_entry"
],
"metadata": {
"npp_alias_type": "/EMAL",
"npp_alias_value": "elon11223344@pay.domain.com.au",
"npp_debtor_name": "Incoming Test Payment Contact",
"npp_debtor_legal_name": "Incoming Test Payment Contact",
"npp_payment_reference": "Test Payment",
"npp_debtor_branch_code": "014209",
"npp_payment_description": "Test Payment",
"npp_debtor_account_number": "12345678",
"npp_payment_transaction_id": "SPPYAU22XXXN20210223000000000534600"
},
"cleared_at": "2020-11-20T01:39:52Z",
"created_at": "2020-11-20T01:34:38Z",
"matures_at": "2020-11-20T01:37:54Z",
"parent_ref": "PR.p4n",
"party_name": "Elon Musk",
"description": "PayID Payment received",
"party_bank_ref": "DT.2wsf",
"party_nickname": null,
"bank_account_id": "1d0eac6b-a81d-4bad-ab9e-8006b16aa185",
"current_channel": "xxx",
"party_contact_id": "a7565a92-a570-4ad1-b5c9-e6763e8af42e",
"status_changed_at": "2020-11-20T01:39:52Z"
}
],
"event": {
"at": "2020-11-20T01:39:52Z",
"who": {
"account_id": "1b1985dc-9a47-410c-bfd7-d987d72a1197",
"account_type": "Account",
"bank_account_id": "1d0eac6b-a81d-4bad-ab9e-8006b16aa185",
"bank_account_type": "BankAccount"
},
"type": "credit.cleared"
}
}

This webhook contains all of the information required to identify:

The value of the payment received (cents)

"amount": 2500

Who made the payment (the id stored from Step 1)

party_contact_id": "a7565a92-a570-4ad1-b5c9-e6763e8af42e

Step 5 - Transfer funds from your Float Account into your bank account

There are 2 ways that funds can be transferred into your bank account once they have cleared inside your float account:

Option 1: You can initiate a Transfer from your PayID enabled Float account into your bank account using our Float Management tools hosted within your Split Payments dashboard.

  1. Log-in to your account
  2. Click on your name in the top left-hand corner
  3. Click on Settings
  4. Click on Bank accounts
  5. Click on the PayID enabled float account
  6. Click on the Transfer Funds button on the top right
  7. Ensure the correct From account has been selected
  8. Select the To account that you wish to transfer funds into
  9. Add the value, a description, a maturation date if you wish to initiate the Transfer at a later time, and click the Transfer Funds button

Option 2: You can also programmatically transfer funds from your PayID enabled float account into your deposit bank account using our Payout endpoint. For more information on using this endpoint, see our Help article on Integrating Payouts via BSB and Account Number.

At a high-level:

  • Create a Contact using the BSB and Account Number of the deposit bank account that you wish to receive your PayID float account funds into
  • Create a Payment via our API ensuring the following 2 ids are set correctly:

"your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f"

This is your PayID enabled float account ID

"recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457"

This is the Contact ID you created using your deposit account's BSB and Account number

NOTE: The bank account added cannot be a bank account that has been registered to your Split Account.

Step 6 - Reporting

You can access all of your transactional data using your account dashboard and built-in reporting features. For more detailed information on how to access your reports, see here.

To reconcile Payments received via PayID, use the Transactions Report, and filter using the following values:

  • Category: Payment Request
  • Funds account: PayID enabled float account
  • Created Date: {date.today / date.week / date.month}
  • Status: Processed

Contact and PayID Management

The NPPA actively enforces and monitors all PayID de-registration processes and as such, Split must ensure that our merchants implement a de-registration process when PayIDs are deemed inactive.

Contact and PayID information should of-course be retained for as long as you have an active relationship with your customer.

Should your relationship end with that customer, the Contact must be removed using our Remove Contact endpoint. This will delete the contact and de-register the associated PayID.

Should your PayID Contact have no transactions registered against it after 12 months, Split will automatically Delete and de-register it.

NOTE: Split supports 2 PayID states:

Registered

PayID can receive payments

De-registered

PayID can NOT receive payments

FAQ's

What if we Remove a contact, but then re-engage with them at a later date?

You will have to create a brand new Contact with a fresh new PayID. We suggest that you use the same approach to forming these PayIDs except append a +n value at the end. For example:

Can we test making a payment to a PayID in the Sandbox environment?

You absolutely can. Just use the following API if you'd like to test the payment received flow and trigger all of the follow-up actions.

Endpoint: POST /simulate/incoming_payid_payment

Request Payload:

{
"payid_email": "elon11223344@pay.spaceships.com",
"amount": "2500"
}

Response [201]:

{
"data": {
"payid_email": "elon11223344@pay.spaceships.com",
"amount": "2500",
"id": "219dc26d-bebc-49d5-ae00-68cee22541d7"
}
}

NOTE:

  • This is only available in Sandbox
  • Amount uses cents
Did this answer your question?