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 sending funds to.

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 - Initiate outbound payments
  • Step 6 - Reporting
  • Contact and PayID Management

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. samantha337981@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 and its balance can be viewed through the Split Payments' UI and API.

Once received funds have been reconciled, you may then initiate outbound payments to your customers. 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.domain.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.domain.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 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.

After a successful response, the Contact "id" should be stored against your internal customer record to help identify:

  1. The asynchronous webhook callback after the PayId has been successfully registered (see step 2).
  2. The real-time settlement notification webhook allowing you to trigger your next steps (see step 4).

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 critical in identifying which Contacts have had their PayID's successfully registered.

What should we be waiting for?

Once the PayID registration is complete, there are 2 possible final states:

  1. Successful registration
  2. Failed registration

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"

Failed Registration

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

"payid_details.state": "fail"

How can we discover what the final 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.

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

After payment has been received from your customer, Split will clear the funds into your allocated float account using a Payment Request.

To be notified of customer payments via PayID, you must subscribe to our credit.cleared webhook for real-time settlement notifications.

An example of this webhook is displayed below:

{
"data": [
{
"ref": "C.34jt",
"type": "credit",
"amount": 100,
"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": "2eea479d-7b00-4002-8a16-6cfeac6cedc9",
"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": "2eea479d-7b00-4002-8a16-6cfeac6cedc9"

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

Step 5 - Initiate Outbound Payments

After the received payment has cleared into your PayID enabled Float account and has been reconciled, you may then initiate an outbound payment to the appropriate customer.

This is done using our Make a Payment endpoint. For more information on how to use this endpoint, see our API Docs and our Help article on creating Contacts and Integrating Payouts via BSB and Account Number.

At a high-level:

  • First create a Contact using the Name, Email, BSB, and Account Number of the customer that you wish to send Payment to
  • Then create a Payment via our API with special attention that the following 2 fields are set correctly:

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

This is your PayID enabled float account ID where your cleared funds are held

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

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

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

To report on Payments made from your PayID enabled float account, use the same report, and filter using the following values:

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

Contact and PayID Management

PayIDs incur an on-going fee for as long as they remain operational. 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
  • Monthly costs are incurred

De-registered

  • PayID can NOT receive payments
  • No monthly costs

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?