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

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. samantha337981@pay.spaceships.com.au

We will then enable your Zepto 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 Zepto 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 Zepto, 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": "Zepto 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?

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

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 Zepto 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, the Zepto 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 1: 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, Zepto 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": "Elon Musk",
"npp_debtor_legal_name": "Elon Peter Simon Jones Musk",
"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

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

Inactive: No payments have been received via PayID or the associated BSB/Account# for over 15 months

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.

The NPPA and Zepto reserve the right to de-register inactive PayIDs at any time after this, where a merchant fails to deregister an inactive PayID.

To retain a good customer experience, the customer should be able to generate a new PayID if required at a later time.

NOTE: Zepto supports 3 PayID states:

Registered

PayID can receive payments

De-registered

PayID can NOT receive payments

Locked

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 simulate incoming payments in Sandbox?

See this article for more information on simulating incoming payments: https://help.zepto.money/en/articles/5630086-simulating-incoming-payments-in-sandbox

Can I disable a receivable contact and re-enable it if need be?

Yes, you are allowed to disable and reactivate the receivable contact according to your needs. Please be mindful that this will incur additional costs outlined in your contract. Please find the API documentation attached here.

Disable:

To disable a receivable contact you will need to make a request to the following API endpoint

POST /contacts/{contact_id}/receivable/disable

Once your request has been successful, all payments made to the relevant Account number or PayID will be rejected and returned back to your customer. Payments made via DE and NPP will be rejected.

Reactivate:
If you would like to reactivate a disabled receivable contact, you will need to make a request to the below endpoint

POST /contacts/{contact_id}/receivable/activate


This will once again allow you to receive funds from your customer via both DE and NPP channels.

Feel free to reach out if you have further questions by emailing us directly at support@zepto.com.au or clicking on the blue bubble icon from the corner of the screen.

Did this answer your question?