Note: This article is relevant to merchants integrating with Zepto in Australia.
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:
Step 1 - Create a Contact with PayID
Step 3 - Expose PayID to your customer
Step 4 - Reconcile received payments
Step 5 - Initiate outbound payments
Step 6 - Reporting
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:
-elon11223344The domain following the @ symbol must match the verified domain provided to Zepto, for example:
-pay.spaceships.com.auThe 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.
(For PayID registration) Please keep daily batches to under 3-4k in a 24 hour period via the API;
(For PayID registration) If you need to process over 5k in a 24 hour period at any time, a 3 week notice period is required as approval is to be granted by us (Zepto) and our Sponsor Bank.
(For PayID deregistration) Please keep daily batches to under 500 in a 24 hour period via the API;
(For PayID deregistration) If you need to process over 1k in a 24 hour period at any time, a 3 week notice period is required as approval is to be granted by us (Zepto) and our Sponsor Bank.
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
Contactrespond with a
201return all of the stored information inside the response, including a special
payid_detailsobject where thestatewill always be returned aspending.
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:
The asynchronous webhook callback after the PayId has been successfully registered (see step 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:
Successful registration
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) |
|
Who made the payment (the |
|
Note: The metadata field will include all the relevant details of the end customer initating the PayID transaction.
The NPP/DE debtor_name, NPP/DE debtor_legal_name, BSB, account number are all returned by the bank and Zepto will display this information as received.
It is recommended that you use a combination of these parameters to identify your end customer and make decisions based on them.
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:
| This is your PayID enabled float account ID where your cleared funds are held |
| 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 new PayID, as the same PayID cannot be reused.
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.
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.
Please find the API documentation attached here.
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.
Please find the API documentation attached here.
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.