Note: This article is relevant to merchants integrating with Zepto in Australia.
We are able to notify you through multiple avenues whenever one of your Agreements is accepted. You can choose one of these available methods to get notified and process the relevant data when this event occurs.
This article outlines three ways to get notified:
If you need help setting up an Agreement prior to this step check out the following articles:
Once you've gone through this process and have an Accepted Agreement in place, you're ready to start issuing Payment Requests to your customers to collect funds. The following article will describe how to do this in detail.
Redirect URL
When showing an Unassigned / Open Agreement to onboard your customers, there are multiple query string values that can be appended to the Agreement URL for your own customisation. One such string that can be added is the success_url parameter, eg:
https://go.split.cash/open_agreements/{agreement_id}/agreements/invitation?success_url={your_chosen_url}When appended to the Agreement link, this parameter will be the URL that your application redirects to upon successful completion and submission of the Agreement form.
When the user clicks Accept in the above example Zepto will redirect your application to the specified success_url . The associated agreement reference, agreement_ref , is also appended to the end of the URL as a query string for your application to consume and persist as required.
Example URL after redirect:
https://{your_chosen_url}?agreement_ref=A.xxxxYour application is now free to take this agreement_ref , persist it against your customer's details and reference it in future requests to Zepto.
Failure Reasons
Along with being able to append the success_url query, you can also append a failure_url query to your Agreement link. This will tell us to redirect your application to the given link when a customer attempts to accept an Agreement but, for some reason, fails. On top of redirecting, we will append a failure reason query which will outline the reason for failure. Possible failure reasons are outlined below:
?errors=must_be_active= Agreement isn't active.?errors=contact_agreement_exists= An agreement between you and this person already exists.?errors=bank_account_agreement_exists= An agreement already exists between you and the holder of this bank account.?errors=authoriser_blank= Authoriser account can't be blank.?errors=is_own_agreement= You cannot accept your own agreement proposal.?errors=agreement_expired= Agreement proposal has expired.?errors=contact.is_own_account= You cannot add your own account.?errors=contact.name_too_long= Name must be less than 80 characters.?errors=contact.name_blank= Name cannot be blank.
Webhooks
The first step to utilising this feature is to create a webhook and add the URL you would like us to send the information. For a detailed guide on setting up your applications webhooks please refer to this article.
When a user accepts an Agreement Zepto will notify your application of the acceptance via the Open/Unassigned Agreement and Agreement webhooks. This process differs slightly depending on whether you use an Open Agreement or an Unassigned Agreement.
Open Agreements
Firstly the following payload will be sent to your callback URL. The webhook that this is sent through can be found by looking at the "type" field. In this case, the webhook being used is the Open Agreement - Accepted hook.
{
"data": [
{
"ref": "OA.xxxx",
"link": "link_used_to_show_agreement",
"terms": {
"per_payout": {
"max_amount": null,
"min_amount": null
},
"per_frequency": {
"days": null,
"max_amount": null
}
},
"title": "agreement_title",
"status": "active",
"created_at": "utc_time_agreement_created"
}
],
"event": {
"at": "2020-03-02T22:54:11Z",
"who": {
"account_id": "agreement_acceptor_user_id",
"account_type": "agreement_acceptor_account_type"
},
"type": "open_agreement.accepted"
}
}
2. When a user accepts your Open Agreement, Zepto will create a new accepted Agreement between yourself and your user. Zepto will send you two notifications during this process.
The first will be informing you that a new Agreement has been proposed.
{
"data": [
{
"ref": "A.xxx",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": null
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
},
"status": "accepted",
"contact_id": "contact_id",
"created_at": "utc_time_agreement_accepted",
"initiator_id": "your_contact_id",
"responded_at": "utc_time_response_received",
"authoriser_id": "acceptor_contact_id",
"status_reason": null,
"bank_account_id": "contact_bank_account_id",
"open_agreement_id": "linked_open_agreeement_id"
}
],
"event": {
"at": "utc_time_agreement_accepted",
"who": {
"account_id": "contact_account_id",
"account_type": "anyone_or_account"
},
"type": "agreement.proposed"
}
}
The second, that the Agreement is accepted.
{
"data": [
{
"ref": "A.xxxx",
"terms": {
"per_payout": {
"max_amount": 100000,
"min_amount": 100
},
"per_frequency": {
"days": 7,
"max_amount": 200000
}
},
"status": "accepted",
"contact_id": "contact_id",
"created_at": "utc_time_agreement_accepted",
"initiator_id": "your_contact_id",
"responded_at": "utc_time_response_received",
"authoriser_id": "acceptor_contact_id",
"status_reason": null,
"bank_account_id": "contact_bank_account_id",
"open_agreement_id": "linked_open_agreeement_id"
}
],
"event": {
"at": "utc_time_agreement_accepted",
"who": {
"account_id": "contact_account_id",
"account_type": "anyone_or_account"
},
"type": "agreement.accepted"
}
}
All information that your application will need to access and persist for future use (payment requests, payouts, etc) is available in the last payload including the Agreement reference, Agreement Terms, Contact ID and Bank Account ID.
Unassigned Agreement
When you hit our API to create the Unassigned Agreement we will send out the following notification.
{
"data": [
{
"ref": "A.xxxx",
"link": link_to_show_agreement,
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": null
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
},
"status": "proposed",
"created_at": "utc_time_agreement_created",
"single_use": true_or_false,
"initiator_id": "your_contact_id",
"responded_at": null,
"assignment_expires_at": "utc_time_this_agreement_will_expire"
}
],
"event": {
"at": "utc_time_agreement_created",
"who": {
"account_id": "same_as_initiator_id",
"account_type": "anyone_or_split"
},
"type": "unassigned_agreement.proposed"
}
}
2. You won't receive another notification until someone uses the link supplied and successfully accepts this agreement. At this point in time, we will send the following payload via the Agreement - Accepted hook.
{
"data": [
{
"ref": "A.xxxx",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": null
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
},
"status": "accepted",
"contact_id": "contact_id",
"created_at": "utc_time_created_at",
"initiator_id": "your_account_id",
"responded_at": "utc_time_agreement_accepted",
"authoriser_id": "acceptor_contact_id",
"status_reason": null,
"bank_account_id": "bank_account_id",
"open_agreement_id": null
}
],
"event": {
"at": "utc_time_agreement_accepted",
"who": {
"account_id": "same_as_initiator_id",
"account_type": "anyone_or_account"
},
"type": "agreement.accepted"
}
}
All information that your application will need to access and persist for future use (payment requests, payouts, etc) is available in the last payload including the Agreement reference, Agreement Terms, Contact ID and Bank Account ID.
You now have an Agreement in place and have been notified
Once your application has received the last payloads and consumed the data that it requires from these, this user is officially a contact within your Zepto account. While this agreement is in place, all Payment Requests sent to the authorising contact will be automatically approved and will begin to process.
Javascript Events
If you're showing your users an Agreement via an iframe then we recommend you listen for the events Zepto will broadcast via the postMessage API. In order for these events to be dispatched by us, you will need to append the following query string values to your Agreement link:
handle_success=1 - When appended to the agreement URL and the customer successfully accepts the agreement, the success event will be broadcast via the postMessage web API.
handle_failure=1 - When appended to the agreement URL and the customer accepts the agreement but fails for some reason, the failure event will be broadcast via the postMessage web API.
Example Agreement Link:
When a user follows this link and accepts the agreement we will broadcast an event via the postMessage API. You can then configure your application to listen for this event and redirect your user accordingly. Note that no redirection will be done by us and your application will have to do the appropriate redirection.
Example Javascript:
function receive(event) {
// Check to make sure it's coming from us
if (event.origin !== "https://go.sandbox.split.cash") {
return;
}
// See how the payload is formed, particularly the data key
console.log(event)
// Do stuff like redirect.
window.location.replace("https://example.com");
}
// Listen for message from the iFrame
window.addEventListener('message', receive, false)
I hope this article has helped, feel free to reach out to us by clicking on the blue bubble icon or email us directly at support@zepto.com.au