Zepto API v1.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Zepto allows you to make, get and manage payments using nothing but bank accounts.

It is important to understand that there are 2 main ways Zepto can be used for maximum flexibility:

Between Zepto accounts.
Between a Zepto account and anyone.

Due to the above, certain endpoints and techniques will differ slightly depending on who you are interacting with. You can find more on this in the Making payments and Getting paid guides.

And for all kinds of How To's and Recipes, head on over to our Help Guide.

Conventions

Authentication is performed using OAuth2. See the Get started and Authentication & Authorisation guides for more.
All communication is via https and supports only TLSv1.2.
Production API: https://api.nz.zepto.money/.
Production UI: https://go.nz.zepto.money/.
Sandbox API: https://api.nz.sandbox.zepto.money/.
Sandbox UI: https://go.nz.sandbox.zepto.money/.
Data is sent and received as JSON.
Clients should include the Accepts: application/json header in their requests.
Currencies are represented by 3 characters as defined in ISO 4217.
Dates & times are returned in UTC using ISO 8601 format with second accuracy. With requests, when no TZ is supplied, the configured TZ of the authenticated user is used, or Pacific/Auckland if no TZ is configured.
Amounts are always in cents with no decimals unless otherwise stated.
Zepto provides static public IP addresses for all outbound traffic, including webhooks.
- Sandbox IP: 13.237.142.60
- Production IPs: 52.64.11.67 and 13.238.78.114

Breaking Changes

A breaking change is assumed to be:

Renaming a parameter (request/response)
Removing a parameter (request/response)
Changing a parameter type (request/response)
Renaming a header (request/response)
Removing a header (request/response)
Application of stricter validation rules for request parameters
Reducing the set of possible enumeration values for a request
Changing a HTTP response status code

We take backwards compatibility very seriously, and will make every effort to ensure this never changes. In the unfortunate (and rare) case where a breaking change can not be avoided, these will be announced well in advance, enabling a transition period for API consumers.

The following are not assumed to be a breaking change and must be taken into account by API consumers:

Addition of optional new parameters in request
Addition of new parameters in response
Addition of new headers in request
Reordering of parameters in response
Softening of validation rules for request parameters
Increasing the set of possible enumeration values

In the case of non breaking changes, a transition period may not be provided, meaning the possibility of such changes occurring must be considered in consumers' logic so as not to break any integrations with both API and Webhooks.

Guides

Try it out

The best way to familiarise yourself with our API is by interacting with it.

We've preloaded a collection with all our endpoints for you to use in Postman. Before you start, import a copy of our API collection:

Okay, let's get things setup!

Create a Zepto account

If you haven't already, you'll want to create a sandbox Zepto account at https://go.nz.sandbox.zepto.money
Register your application with Zepto

Sign in and create an OAuth2 application: https://go.nz.sandbox.zepto.money/oauth/applications.
Generate personal access tokens

The quickest way to access your Zepto account via the API is using personal access tokens. Click on your newly created application from your application list and click on + Personal Access Token.

(You'll have the option to give the token a title)

Please note that personal access tokens do not expire.
Use personal access token in Postman

You can use this access_token to authorise any requests to the Zepto API in Postman by choosing the Bearer Token option under the Authorization tab.
Make an API request!

You are now ready to interact with your Zepto account via the API! Go ahead and send a request using Postman.

Get started

This guide will help you setup an OAuth2 app in order to get authenticated & authorised to communicate with the Zepto API.

Before you start:

We use the term user below but the user can be a third party or the same user that owns the OAuth2 application.
As noted below, some access tokens expire every 2 hours. To get a new access token use the refresh grant strategy to swap a refresh token for a new access token.

Create a Zepto account

If you haven't already, you'll want to create a sandbox Zepto account at https://go.nz.sandbox.zepto.money.
Choose authentication method

All requests to the Zepto API require an access_token for authentication. There are two options for obtaining these tokens, the correct option will depend on your use case:

Personal access token If you only need to access your own Zepto account via the API, then using personal access tokens are the most straight-forward way. Refer to Personal access token to setup. These tokens do not expire so no refreshing is required.

OAuth grant flow When you require your application to act on behalf of other Zepto accounts you'll need to implement the OAuth grant flow process. Refer to OAuth grant flow guide to setup. There is also an OAuth grant flow tutorial. These access tokens expire every 2 hours, unless the offline_access scope is used in which case the tokens will not expire.

Personal access token

If you're looking to only access your own account via the API, you can generate a personal access token from the UI. These tokens do not expire, but can be deleted.

To do this, sign in to your Zepto account and create an application if you haven't already. Click on your application from your application list and click on Personal access.

(You'll have the option to give the token a title)
Now that you have an access_token you can interact with your Zepto account via the API.

To do so, you must simply append the access token to the header of any API request: Authorization: Bearer {access_token}

OAuth grant flow

Register your application with Zepto

Once you've got your account up and running, sign in and create an OAuth2 profile for your application: https://go.nz.sandbox.zepto.money/oauth/applications

Parameter	Description
Name	The name of your application. When using the the Authorisation Grant Flow, users will see this name as the application requesting access to their account.
Redirect URI	Set this to your application's endpoint charged with receiving the authorisation code.

Obtain an authorisation code

Construct the initial URL the user will need to visit in order to grant your application permission to act on his/her behalf. The constructed URL describes the level of permission (scope), the application requesting permission (client_id) and where the user gets redirected once they've granted permission (redirect_uri).

The URL should be formatted to look like this: https://go.nz.sandbox.zepto.money/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}

Parameter	Description
`response_type`	Always set to `code`
`client_id`	This is your `Application ID` as generated when you registered your application with Zepto
`redirect_uri`	URL where the user will get redirected along with the newly generated authorisation code
`scope`	The scope of permission you're requesting

Exchange the authorisation code for an access token

When the user visits the above-mentioned URL, they will be presented with a Zepto login screen and then an authorisation screen:

After the user has authorised your application, they will be returned to your application at the URL specified in redirect_uri along with the code query parameter as the authorisation code.

Finally, the authorisation code can then be exchanged for an access token and refresh token pair by POSTing to: https://go.nz.sandbox.zepto.money/oauth/token

Note The authorisation code is a ONE-TIME use code. It will not work again if you try to POST it a second time.

Parameter	Description
`grant_type`	Set to `authorization_code`
`client_id`	This is your `Application ID` as generated when you registered your application with Zepto
`client_secret`	This is your `Secret` as generated when you registered your application with Zepto
`code`	The authorisation code returned with the user (ONE-TIME use)
`redirect_uri`	Same URL used in step 3

Wrap-up

Now that you have an access token and refresh token, you can interact with the Zepto API as the user related to the access token. To do so, you must simply append the access token to the header of any API request: Authorization: Bearer {access_token}

OAuth grant flow tutorial

The OAuth grant flow process is demonstrated using Postman in the steps below.

Before you start, load up our API collection:

A screencast of this process is also available: https://vimeo.com/246203244.

Create a Zepto account

If you haven't already, you'll want to create a sandbox Zepto account at https://go.nz.sandbox.zepto.money
Register your application with Zepto

Sign in and create an OAuth2 application: https://go.nz.sandbox.zepto.money/oauth/applications.

Use the special Postman callback URL: https://www.getpostman.com/oauth2/callback
In Postman, setup your environment variables

We've included the Zepto Public Sandbox environment to get you started. Select it in the top right corner of the window then click the icon and click edit.

Using the details from the OAuth2 app you created earlier, fill in the oauth2_application_id & oauth2_secret fields.
Setup the authorization

Click on the Authorization tab and select OAuth 2.0

Click the Get New Access Token button

Fill in the OAuth2 form as below:
Get authorised

Click Request Token and wait a few seconds and a browser window will popup

Sign in with your Zepto account (or any other Zepto account you want to authorise).

Click Authorise to allow the app to access the signed in account. Once complete, Postman will automatically exchange the authorisation code it received from Zepto for the access_token/refresh_token pair. It will then store the access_token/refresh_token for you to use in subsequent API requests. The access_token effectively allows you to send requests via the API as the user who provided you authorisation.
You're now ready to use the API

Select an endpoint from the Zepto collection from the left hand side menu. Before you send an API request ensure you select your access token and Postman will automatically add it to the request header.

Authentication and Authorisation

Zepto uses OAuth2 over https to manage authentication and authorisation.

OAuth2 is a protocol that lets external applications request permission from another Zepto user to send requests on their behalf without getting their password. This is preferred over Basic Authentication because access tokens can be limited by scope and can be revoked by the user at any time.

New to OAuth2? DigitalOcean has a fantastic 5 minute introduction to OAuth2.

We currently support the authorisation code and refresh token grants.

Authorisation Code Grant

This type of grant allows your application to act on behalf of a user. If you've ever used a website or application with your Google, Twitter or Facebook account, this is the grant being used.

See the Get Started guide for step by step details on how to use this grant.

Refresh Token Grant

Code sample

curl -F "grant_type=refresh_token" \
     -F "client_id={{oauth2_application_id}}" \
     -F "client_secret={{oauth2_application_secret }}" \
     -F "refresh_token={{refresh_token}}" \
     -X POST https://go.nz.sandbox.zepto.money/oauth/token

Example response

{
    "access_token": "ad0b5847cb7d254f1e2ff1910275fe9dcb95345c9d54502d156fe35a37b93e80",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "cc38f78a5b8abe8ee81cdf25b1ca74c3fa10c3da2309de5ac37fde00cbcf2815",
    "scope": "public"
}

When using the authorisation code grant above, Zepto will return a refresh token along with the access token. Access tokens are short lived and last 2 hours but refresh tokens do not expire.

When the access token expires, instead of sending the user back through the authorisation flow you can use the refresh token to retrieve a new access token with the same permissions as the old one.

The refresh_token gets regenerated and sent alongside the new access_token. In other words, refresh_tokens are single use so you'll want to store the newly generated refresh_token everytime you use it to get a new access_token

Making payments

In order to payout funds, you'll be looking to use the Payments endpoint. Whether you're paying out another Zepto account holder or anyone, the process is the same:

Add the recipient to your Contact list.
Make a Payment to your Contact.

Common use cases:

Automated payout disbursement (Referal programs, net/commission payouts, etc...)
Wage payments
Gig economy payments
Lending

Getting paid

POSTing a Payment Request

Provides the ability to send a Payment Request (get paid) to any Contact that has an accepted Agreement in place.

To send a Payment Request to a Contact using the API, you must first have an accepted Agreement with them.

To do so, you can send them an Unassigned Agreement link for them to accept the Agreement.

Having this in place will allow any future Payment Requests to be automatically approved and processed as per the Agreement terms.

Common use cases:

Subscriptions
On-account balance payments
Bill smoothing
Repayment plans

Idempotent requests

Example response

{
  "errors": [
    {
      "title": "Duplicate idempotency key",
      "detail": "A resource has already been created with this idempotency key",
      "links": {
        "about": "https://docs.nz.zepto.money/"
      },
      "meta": {
        "resource_ref": "PB.1a4"
      }
    }
  ]
}

The Zepto API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a Payment is POSTed and a there is a network connection error, you can retry the Payment with the same idempotency key to guarantee that only a single Payment is created. In case an idempotency key is not supplied and a Payment is retried, we would treat this as two different payments being made.

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to the request. You can pass any value as the key but we suggest that you use V4 UUIDs or another appropriately random string.

Keys expire after 24 hours. If there is a subsequent request with the same idempotency key within the 24 hour period, we will return a 409 Conflict.

The meta.resource_ref value is the reference of the resource that was previously created with the conflicting idempotency key.
The Idempotency-Key header is optional but recommended.
Only the POST action for the Payments, Payment Requests and Refunds endpoints support the use of the Idempotency-Key.
Endpoints that use the GET or DELETE actions are idempotent by nature.
A request that quickly follows another with the same idempotency key may return with 503 Service Unavailable. If so, retry the request after the number of seconds specified in the Retry-After response header.

Currently the following POST requests can be made idempotent. We strongly recommend sending a unique Idempotency-Key header when making those requests to allow for safe retries:

Error responses

Example detailed error response

{
  "errors": [
    {
      "title": "A Specific Error",
      "detail": "Details about the error",
      "links": {
        "about": "https://docs.nz.zepto.money/..."
      }
    }
  ]
}

Example resource error response

{
  "errors": "A sentence explaining error/s encounted"
}

The Zepto API returns two different types of error responses depending on the context.

Detailed error responses are returned for:

Authentication
Request types
Idempotency

All other errors relating to Zepto specific resources(e.g. Contacts) will return the Resource error response style.

403 errors

403 errors are generally returned from any of our endpoints if your application does not have the required authorisation. This is usually due to:

An invalid/expired access_token; or
The required scopes not being present when setting up your OAuth application; or
The required scopes not being present in the authorisation code link used to present your user with an authorisation request.

Speeding up onboarding

Consider the following scenario:

Zepto is integrated in your application to handle payments.
A customer would like to use Zepto but does not yet have Zepto account.
You already have some information about this customer.

Given the above, in a standard implementation where a customer enables/uses Zepto within your application, these are the steps they would follow:

Click on some sort of button within your app to use Zepto.
They get redirected to the Zepto sign in page (possibly via a popup or modal).
Since they don't yet have a Zepto account, they would click on sign up.
They would fill in all their signup details and submit.
They would be presented with the authorisation page.
They would click the "Authorise" button and be redirected to your app.

Whilst not too bad, we can do better!

In order to speed up the process, we allow query string params to be appended to the authorisation URL. For instance, if we already have some information about the customer and know they probably don't have a Zepto account, we can embed this information in the authorisation URL.

Supported query string parameters

Parameter	Description
`landing`	Accepted value: `sign_up`. What page the user should see first if not already signed in. Default is the sign in page.
`nickname`	Only letters, numbers, dashes and underscores are permitted. This will be used to identify the account in Zepto.
`name`	Business account only. Business name.
`abn`	Business account only. Business ABN.
`phone`	Business account only. Business phone number.
`street_address`
`suburb`
`postcode`
`first_name`
`last_name`
`mobile_phone`
`email`

All values should be URL encoded.

As an example, the following authorisation URL would display the personal sign up & prefill the first name field with George: https://go.nz.sandbox.zepto.money/oauth/authorize?response_type=code&client_id=xxx&redirect_uri=xxx&scope=xxx&landing=sign_up&first_name=George

You can also pass the values directly to the sign up page outside of the OAuth2 authorisation process. Click on the following link to see the values preloaded: https://go.nz.sandbox.zepto.money/business/sign_up?name=GeorgeCo&nickname=georgeco&first_name=George.

Sandbox Testing Details

Example failure object

{
  "failure": {
      "code": "E554-206",
      "title": "Account Not Found",
      "detail": "The target account number is incorrect."
  }
}

Try out your happy paths and not-so happy paths; the sandbox is a great place to get started without transferring actual funds. All transactions are simulated and no communication with financial institutions is performed.

The sandbox works on a 1 minute cycle to better illustrate how transactions are received and the lifecyle they go through. In other words, every minute, we simulate communicating with financial institutions and update statuses and events accordingly.

Failed transactions will contain the following information inside the event:

Failure Code
Failure Title
Failure Details

DE Transaction failures

Using failure codes

To simulate a transaction failure, create a Payment or Payment Request with an amount corresponding to the desired failure code.

For example:

Amount $1.50 will cause the credit transaction to fail, triggering the credit failure code E554-150 (Voided By Admin).
Amount $2.06 will cause the debit transaction to fail, triggering the debit failure code E554-206 (Account Not Found).

Example scenarios

Initiate a transaction which is voided by an administrator:
- Initiate a Payment for $1.50.
- Zepto will mimic a successful debit from your bank account.
- Zepto will mimic a failure to credit the contact's bank account.
- Zepto will automatically create a payout_reversal credit transaction back to your bank account.
Request payment from a contact with an invalid account number:
- Initiate a Payment Request for $2.06.
- Zepto will mimic a failure to debit the contact's bank account.

Configuration

Scopes

Scopes define the level of access granted via the OAuth2 authorisation process. As a best practice, only use the scopes your application will require.

Scope	Description
`public`	View user's public information
`agreements`	Manage user's Agreements
`bank_accounts`	Manage user's Bank Accounts
`contacts`	Manage user's Contacts
`payments`	Manage user's Payments
`payment_requests`	Manage user's Payment Requests
`refunds`	Manage user's Refunds
`transactions`	Access user's Transactions
`webhooks`	Manage user's Webhook events
`offline_access`	Create non-expiring access tokens for user

Please use offline_access with discretion, as you'll have no direct way to invalidate the token. Please contact Zepto immediately if any token may have potentially been compromised.

Pagination

Example response headers

Link: <http://api.nz.sandbox.zepto.money/contacts?page=2>; rel="next"
Per-Page: 25

Pagination information can be located in the response headers: Link & Per-Page
All collection endpoints are paginated to Per-Page: 25 by default. (100 per page is max, any value above will revert to 100)
You can control the pagination by including per_page=x and/or page=x in the endpoint URL params.

The Link header will be optionally present if a "next page" is available to navigate to. The next page link is identified with rel="next"

Legacy Pagination Some existing users may still be on a transitional legacy version of pagination.
The Legacy version returns some extra deprecated header values: Total plus rel="last" & rel="prev" in Link.
Please transition to only using the rel="next" from the Link header, as all other values are deprecated.

Remitter

Example request

{
  "...": "...",
  "metadata": {
   "remitter": "CustomRem"
   }
}

You can elect to assign a remitter name on a per-request basis when submitting Payments & Payment Requests. Simply append the remitter key and a value within the metadata key.

For Payments, the party being credited will see the designated remitter name along the entry on their bank statement.
For Payment Requests, the party being debited will see the designated remitter name along the entry on their bank statement.

The remitter name MUST be between 3 and 16 characters.

Aggregation

Zepto will automatically aggregate debits that are:

From the same bank account; and
Have the same description; and
Initiated by the same Zepto account. Likewise for credits:
To the same bank account; and
Have the same description; and
Initiated by the same Zepto account.

Should you prefer debit aggregation to be disabled, please contact support@zepto.com.au. Note that additional charges may apply.

Webhooks

Example response

{
  "event": {
    "type": "object.action",
    "at": "yyyy-mm-ddThh:mm:ssZ",
    "who": {
      "account_id": "x",
      "bank_account_id": "x"
    }
  },
  "data": [
    {}
  ]
}

Please refer to our help centre article on webhooks for more information and an overview of what you can achieve with webhooks.

We support two main categories of webhooks:

Owner: These webhooks are managed by the owner of the Zepto account and only report on events owned by the Zepto account.
App: These webhooks are managed by the Zepto OAuth2 application owner and will report on events relating to any authorised Zepto account (limited by scope).

Name	Type	Required	Description
event	object	true	Webhook event details
» type	string	true	The webhook event key (list available in the webhook settings)
» at	string(date-time)	true	When the event occurred
» who	object	true	Who the webhook event relates to
»» account_id	string(uuid)	true	The Zepto account who's the owner of the event
»» bank_account_id	string(uuid)	true	The above Zepto account's bank account
data	[object]	true	Array of response bodies

Data schemas

Use the following table to discover what type of response schema to expect for for the data.[{}] component of the webhook delivery.

Event	Data schema
`agreement.*`	GetAnAgreementResponse
`contact.*`	GetAContactResponse
`credit.*`	ListAllTransactionsResponse
`creditor_debit.*`	ListAllTransactionsResponse
`debit.*`	ListAllTransactionsResponse
`debtor_credit.*`	ListAllTransactionsResponse
`payment.*`	GetAPaymentResponse
`payment_request.*`	GetAPaymentRequestResponse
`unassigned_agreement.*`	GetAnUnassignedAgreementResponse

Our Delivery Promises

We only consider a webhook event delivery as failed if we don't receive any http response code (2xx, 4xx, 5xx, etc.)
We will auto-retry failed deliveries every 5 minutes for 1 hour.
Delivery order for webhook events is not guaranteed.
We guarantee at least 1 delivery attempt.

For redelivery of webhooks, check out our Webhook/WebhookDelivery API endpoints.

Request ID

Example header

Split-Request-ID: 07f4e8c1-846b-5ec0-8a25-24c3bc5582b5

Zepto provides a Split-Request-ID header in the form of a UUID which uniquely identifies a webhook event. If the webhook event is retried/retransmitted by Zepto, the UUID will remain the same. This allows you to check if a webhook event has been previously handled/processed.

Checking Webhook Signatures

Example header

Split-Signature: 1514772000.93eee90206280b25e82b38001e23961cba4c007f4d925ba71ecc2d9804978635

Zepto signs the webhook events it sends to your endpoints. We do so by including a signature in each event’s Split-Signature header. This allows you to validate that the events were indeed sent by Zepto.

Before you can verify signatures, you need to retrieve your endpoint’s secret from your Webhooks settings. Each endpoint has its own unique secret; if you use multiple endpoints, you must obtain a secret for each one.

The Split-Signature header contains a timestamp and one or more signatures. All separated by . (dot).

Example code

# Shell example is not available

package main
import (
    "crypto/hmac"
    "crypto/sha256"
    "strings"
    "fmt"
    "encoding/hex"
)
func main() {
    secret := "1234"
    message := "full payload of the request"
    splitSignature := "1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f"

    data := strings.Split(splitSignature, ".")
    timestamp, givenSignature := data[0], data[1]

    signedPayload := timestamp + "." + message

    hash := hmac.New(sha256.New, []byte(secret))
    hash.Write([]byte(signedPayload))
    expectedSignature := hex.EncodeToString(hash.Sum(nil))

    fmt.Println(expectedSignature)
    // f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
    fmt.Println(givenSignature)
    // f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
}

import hashlib
import hmac

split_signature = '1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f'
secret = bytes('1234').encode('utf-8')
message = bytes('full payload of the request').encode('utf-8')

data = split_signature.split('.')
timestamp = data[0]
given_signature = data[1]

signed_payload = timestamp + '.' + message

expected_signature = hmac.new(secret, signed_payload, digestmod=hashlib.sha256).hexdigest()

print(expected_signature)
# > f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f

print(given_signature)
# > f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f

require 'openssl'

split_signature = '1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f'
secret = '1234'
message = 'full payload of the request'

timestamp, given_signature, *other = split_signature.split('.')
signed_payload = timestamp + '.' + message
expected_signature = OpenSSL::HMAC.hexdigest('sha256', secret, signed_payload)

puts(expected_signature)
# => f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
puts(given_signature)
# => f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f

var crypto = require('crypto')
var message = 'full payload of the request'
var secret = '1234'
var splitSignature = '1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f'

var data = splitSignature.split('.')
var timestamp = data[0]
var givenSignature = data[1]

var signedPayload = timestamp + '.' + message

var expectedSignature = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')

console.log(expectedSignature)
// f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
console.log(givenSignature)
// f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f

$split_signature = '1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f';
$secret = '1234';
$message = 'full payload of the request';

list($timestamp, $given_signature, $other) = explode('.', $split_signature);
$signed_payload = $timestamp . "." . $message;
$expected_signature = hash_hmac('sha256', $signed_payload, $secret, false);

echo $expected_signature; // f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
echo "\n";
echo $given_signature; // f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

class Main {
  public static void main(String[] args) {
    try {
      String splitSignature = "1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f";
      String secret = "1234";
      String message = "full payload of the request";

      String[] data = splitSignature.split("\\.");
      String timestamp = data[0];
      String givenSignature = data[1];

      String signedPayload = timestamp + "." + message;

      Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
      SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
      sha256_HMAC.init(secret_key);

      String expectedSignature = javax.xml.bind.DatatypeConverter.printHexBinary(sha256_HMAC.doFinal(signedPayload.getBytes())).toLowerCase();

      System.out.println(expectedSignature);
      // f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f

      System.out.println(givenSignature);
      // f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
    }
    catch (Exception e){
      System.out.println("Error");
    }
  }
}

Step 1. Extract the timestamp and signatures from the header

Split the header, using the . (dot) character as the separator, to get a list of elements.

Element	Description
`timestamp`	Unix time in seconds when the signature was created
`signature`	Request signature
`other`	Placeholder for future parameters (currently not used)

Step 2: Prepare the signed_payload string

You achieve this by concatenating:

The timestamp from the header (as a string)
The character . (dot)
The actual JSON payload (request body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

Step 4: Compare signatures

Compare the signature in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

Changelog

We take backwards compatibility seriously. The following list contains backwards compatible changes:

2023-04-20 - Changed the webhook retention period to 7 days Looking for more? Our docs are open sourced! https://github.com/zeptofs/nz-api-documentation

Agreements

An Agreement is an arrangement between two parties that allows them to agree on terms for which future Payment Requests will be auto-approved.

Zepto Agreements are managed on a per Contact basis, and if a Payment Request is sent for an amount that exceeds the terms of the agreement, it will not be created. Please refer to the What is an Agreement article in our knowledge base for an overview.

Lifecycle

An Agreement can have the following statuses:

Status	Description
`proposed`	Waiting for the Agreement to be accepted or declined.
`accepted`	The Agreement has been accepted and is active.
`cancelled`	The Agreement has been cancelled (The initiator or authoriser can cancel an Agreement).
`declined`	The Agreement has been declined.
`expended`	The Agreement has been expended (Only for single_use Unassigned Agreements).

Create KYC Trusted Agreement

Code samples

curl --request POST \
  --url https://api.nz.sandbox.zepto.money/agreements/kyc \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --data '{"authoriser":{"name":"John Doe","email":"john@supplies.com","phone":"02112345678","bank_account":{"account_number":"021234693049678"},"metadata":{"some_data":"stored on the authoriser contact"}},"terms":{"per_payout":{"min_amount":null,"max_amount":null},"per_frequency":{"days":null,"max_amount":null}},"metadata":{"your_customer_uid":"6041475e-c5b4-4abe-a8e9-e2c3620a0a3e","some_other_data":"stored on the agreement"}}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/agreements/kyc")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"authoriser\":{\"name\":\"John Doe\",\"email\":\"john@supplies.com\",\"phone\":\"02112345678\",\"bank_account\":{\"account_number\":\"021234693049678\"},\"metadata\":{\"some_data\":\"stored on the authoriser contact\"}},\"terms\":{\"per_payout\":{\"min_amount\":null,\"max_amount\":null},\"per_frequency\":{\"days\":null,\"max_amount\":null}},\"metadata\":{\"your_customer_uid\":\"6041475e-c5b4-4abe-a8e9-e2c3620a0a3e\",\"some_other_data\":\"stored on the agreement\"}}"

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/agreements/kyc",
  "headers": {
    "content-type": "application/json",
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({
  authoriser: {
    name: 'John Doe',
    email: 'john@supplies.com',
    phone: '02112345678',
    bank_account: { account_number: '021234693049678' },
    metadata: { some_data: 'stored on the authoriser contact' }
  },
  terms: {
    per_payout: { min_amount: null, max_amount: null },
    per_frequency: { days: null, max_amount: null }
  },
  metadata: {
    your_customer_uid: '6041475e-c5b4-4abe-a8e9-e2c3620a0a3e',
    some_other_data: 'stored on the agreement'
  }
}));
req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

payload = "{\"authoriser\":{\"name\":\"John Doe\",\"email\":\"john@supplies.com\",\"phone\":\"02112345678\",\"bank_account\":{\"account_number\":\"021234693049678\"},\"metadata\":{\"some_data\":\"stored on the authoriser contact\"}},\"terms\":{\"per_payout\":{\"min_amount\":null,\"max_amount\":null},\"per_frequency\":{\"days\":null,\"max_amount\":null}},\"metadata\":{\"your_customer_uid\":\"6041475e-c5b4-4abe-a8e9-e2c3620a0a3e\",\"some_other_data\":\"stored on the agreement\"}}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("POST", "/agreements/kyc", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.post("https://api.nz.sandbox.zepto.money/agreements/kyc")
  .header("content-type", "application/json")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .body("{\"authoriser\":{\"name\":\"John Doe\",\"email\":\"john@supplies.com\",\"phone\":\"02112345678\",\"bank_account\":{\"account_number\":\"021234693049678\"},\"metadata\":{\"some_data\":\"stored on the authoriser contact\"}},\"terms\":{\"per_payout\":{\"min_amount\":null,\"max_amount\":null},\"per_frequency\":{\"days\":null,\"max_amount\":null}},\"metadata\":{\"your_customer_uid\":\"6041475e-c5b4-4abe-a8e9-e2c3620a0a3e\",\"some_other_data\":\"stored on the agreement\"}}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"authoriser":{"name":"John Doe","email":"john@supplies.com","phone":"02112345678","bank_account":{"account_number":"021234693049678"},"metadata":{"some_data":"stored on the authoriser contact"}},"terms":{"per_payout":{"min_amount":null,"max_amount":null},"per_frequency":{"days":null,"max_amount":null}},"metadata":{"your_customer_uid":"6041475e-c5b4-4abe-a8e9-e2c3620a0a3e","some_other_data":"stored on the agreement"}}');

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/agreements/kyc');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/agreements/kyc"

    payload := strings.NewReader("{\"authoriser\":{\"name\":\"John Doe\",\"email\":\"john@supplies.com\",\"phone\":\"02112345678\",\"bank_account\":{\"account_number\":\"021234693049678\"},\"metadata\":{\"some_data\":\"stored on the authoriser contact\"}},\"terms\":{\"per_payout\":{\"min_amount\":null,\"max_amount\":null},\"per_frequency\":{\"days\":null,\"max_amount\":null}},\"metadata\":{\"your_customer_uid\":\"6041475e-c5b4-4abe-a8e9-e2c3620a0a3e\",\"some_other_data\":\"stored on the agreement\"}}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("content-type", "application/json")
    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

POST /agreements/kyc

Creates a KYC Trusted Agreement, which also finds or creates the given authoriser and associated bank account. Requests are automatically idempotent, which means resending the same payload will return the currently live Agreement.

The format of the account number should be BB-bbbb-AAAAAAA-SSS where:

B is the bank number (2 digits) and b is the branch number (4 digits). Both constitute the prefix or the bank code.
A is the account number (7 digits) which is right justified.
S is the suffix (2-3 digits). When a bank displays the suffix as two digits, a leading zero is added to pad the suffix to three digits; i.e. BB-bbbb-AAAAAAA-SS becomes BB-bbbb-AAAAAAA-0SS.

Body parameter

{
  "authoriser": {
    "name": "John Doe",
    "email": "john@supplies.com",
    "phone": "02112345678",
    "bank_account": {
      "account_number": "021234693049678"
    },
    "metadata": {
      "some_data": "stored on the authoriser contact"
    }
  },
  "terms": {
    "per_payout": {
      "min_amount": null,
      "max_amount": null
    },
    "per_frequency": {
      "days": null,
      "max_amount": null
    }
  },
  "metadata": {
    "your_customer_uid": "6041475e-c5b4-4abe-a8e9-e2c3620a0a3e",
    "some_other_data": "stored on the agreement"
  }
}

Parameters

Parameter	In	Type	Required	Description
body	body	CreateKYCTrustedAgreementRequest	true	No description
» authoriser	body	AddAnAnyoneContactRequest	true	No description
»» name	body	string	true	The name of the Contact (140 max. characters)
»» email	body	string	true	The email of the Contact (256 max. characters)
»» phone	body	string	true	The phone of the Contact. Must be a valid New Zealand mobile number in ITU-T E.164 or national format
»» account_number	body	string	true	The bank account number of the Contact (15-16 characters)
»» metadata	body	Metadata	false	Use for your custom data and certain Zepto customisations.
» terms	body	Terms	true	Terms
»» per_payout	body	PerPayout	true	No description
»»» min_amount	body	integer	true	Minimum amount in cents a Payment Request can be in order to be auto-approved. Specify `null` for no limit.
»»» max_amount	body	integer	true	Maximum amount in cents a Payment Request can be in order to be auto-approved. Specify `null` for no limit.
»» per_frequency	body	PerFrequency	true	No description
»»» days	body	integer	true	Amount of days to apply against the frequency. Specify `null` for no limit.
»»» max_amount	body	integer	true	Maximum amount in cents the total of all PRs can be for the duration of the frequency. Specify `null` for no limit.
»» metadata	body	Metadata	false	Use for your custom data and certain Zepto customisations.

Example responses

201 Response

{
  "data": {
    "ref": "A.ci",
    "initiator_id": "6a0a05c4-8ad9-495d-bcf9-66a7d0046909",
    "authoriser_id": "9fa1be8d-40fb-4bf6-9743-577a1d5a3775",
    "contact_id": "bea8107a-a5b5-4719-92ec-8389ad7aa619",
    "bank_account_id": "91dbef6d-b596-4387-a36c-5a8497822b97",
    "status": "accepted",
    "responded_at": "2018-04-30T04:43:52Z",
    "created_at": "2018-04-30T04:43:52Z",
    "terms": {
      "per_payout": {
        "max_amount": null,
        "min_amount": null
      },
      "per_frequency": {
        "days": null,
        "max_amount": null
      }
    },
    "metadata": {
      "your_customer_uid": "6041475e-c5b4-4abe-a8e9-e2c3620a0a3e",
      "some_other_data": "stored on the agreement"
    }
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	CreateKYCTrustedAgreementResponse

List Agreements

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/agreements/outgoing \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/agreements/outgoing")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/agreements/outgoing",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/agreements/outgoing", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/agreements/outgoing")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/agreements/outgoing');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/agreements/outgoing"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /agreements/outgoing

By default, all outgoing Agreements will be returned. You can apply filters to your query to customise the returned Agreements.

Parameters

Parameter	In	Type	Required	Description
page	query	string	false	Page of results to return, single value, exact match
per_page	query	string	false	Number of results per page, single value, exact match
authoriser_id	query	string	false	Authoriser ID (`Contact.data.account.id`), single value, exact match
contact_id	query	string	false	Contact ID (`Contact.data.id`), single value, exact match
status	query	array[string]	false	Exact match

Enumerated Values

Parameter	Value
status	proposed
status	accepted
status	declined
status	cancelled

Example responses

200 Response

{
  "data": [
    {
      "ref": "A.4",
      "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
      "authoriser_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
      "contact_id": "a80ac411-c8fb-45c0-9557-607c54649907",
      "bank_account_id": "fa80ac411-c8fb-45c0-9557-607c54649907",
      "status": "proposed",
      "status_reason": null,
      "responded_at": null,
      "created_at": "2017-03-20T00:53:27Z",
      "terms": {
        "per_payout": {
          "max_amount": 10000,
          "min_amount": 1
        },
        "per_frequency": {
          "days": 7,
          "max_amount": 1000000
        }
      }
    },
    {
      "ref": "A.3",
      "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
      "authoriser_id": "56df206a-aaff-471a-b075-11882bc8906a",
      "contact_id": "a80ac411-c8fb-45c0-9557-607c54649907",
      "bank_account_id": "fa80ac411-c8fb-45c0-9557-607c54649907",
      "status": "proposed",
      "status_reason": null,
      "responded_at": null,
      "created_at": "2017-03-16T22:51:48Z",
      "terms": {
        "per_payout": {
          "max_amount": 5000,
          "min_amount": 0
        },
        "per_frequency": {
          "days": "1",
          "max_amount": 10000
        }
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	ListOutgoingAgreementsResponse

Response Headers

Status	Header	Type	Format	Description
200	Link	string		Contains pagination link for next page of collection, if next page exists.
200	Per-Page	integer		Contains the current maximum items in collection. Defaults to 25

Get an Agreement

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/agreements/A.2 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/agreements/A.2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/agreements/A.2",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/agreements/A.2", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/agreements/A.2")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/agreements/A.2');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/agreements/A.2"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /agreements/{agreement_ref}

Get a single Agreement by its reference

Parameters

Parameter	In	Type	Required	Description
agreement_ref	path	string	true	Single value, exact match

Example responses

200 Response

{
  "data": {
    "ref": "A.2",
    "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
    "authoriser_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
    "contact_id": "0d290763-bd5a-4b4d-a8ce-06c64c4a697b",
    "bank_account_id": "fb9381ec-22af-47fd-8998-804f947aaca3",
    "status": "approved",
    "status_reason": null,
    "responded_at": "2017-03-20T02:13:11Z",
    "created_at": "2017-03-20T00:53:27Z",
    "terms": {
      "per_payout": {
        "max_amount": 10000,
        "min_amount": 1
      },
      "per_frequency": {
        "days": 7,
        "max_amount": 1000000
      }
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	GetAgreementResponse

Cancel an Agreement

Code samples

curl --request DELETE \
  --url https://api.nz.sandbox.zepto.money/agreements/A.2 \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/agreements/A.2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "DELETE",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/agreements/A.2",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = { 'authorization': "Bearer {access-token}" }

conn.request("DELETE", "/agreements/A.2", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.delete("https://api.nz.sandbox.zepto.money/agreements/A.2")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/agreements/A.2');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/agreements/A.2"

    req, _ := http.NewRequest("DELETE", url, nil)

    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

DELETE /agreements/{agreement_ref}

An Agreement can be cancelled by the initiator at any time whilst the authoriser (Agreement recipient) can only cancel a previously accepted Agreement.

Parameters

Parameter	In	Type	Required	Description
agreement_ref	path	string	true	Single value, exact match

Responses

Status	Meaning	Description	Schema
204	No Content	No Content	None

Bank Accounts

Your currently linked up bank accounts.

List all Bank Accounts

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/bank_accounts \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/bank_accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/bank_accounts",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/bank_accounts", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/bank_accounts")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/bank_accounts');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/bank_accounts"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /bank_accounts

By default, all Bank Accounts will be returned.

Example responses

200 Response

{
  "data": [
    {
      "id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
      "bank_name": "Bank of New Zealand",
      "account_number": "021234693049678",
      "status": "active",
      "title": "NZ.020100.3993013'",
      "available_balance": null
    },
    {
      "id": "56df206a-aaff-471a-b075-11882bc8906a",
      "bank_name": "Bank of New Zealand",
      "account_number": "0212341059493024",
      "status": "active",
      "title": "Trust Account",
      "available_balance": null
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	ListAllBankAccountsResponse

Response Headers

Status	Header	Type	Format	Description
200	Link	string		Contains pagination link for next page of collection, if next page exists.
200	Per-Page	integer		Contains the current maximum items in collection. Defaults to 25

Contacts

Your Contacts form an address book of parties with whom you can interact. In order to initiate any type of transaction you must first have the party in your Contact list.

Add a Contact

Code samples

curl --request POST \
  --url https://api.nz.sandbox.zepto.money/contacts/anyone \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --data '{"name":"Hunter Thompson","email":"hunter@batcountry.com","phone":"+64211234567","account_number":"021234693049678","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/contacts/anyone")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"name\":\"Hunter Thompson\",\"email\":\"hunter@batcountry.com\",\"phone\":\"+64211234567\",\"account_number\":\"021234693049678\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/contacts/anyone",
  "headers": {
    "content-type": "application/json",
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({
  name: 'Hunter Thompson',
  email: 'hunter@batcountry.com',
  phone: '+64211234567',
  account_number: '021234693049678',
  metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

payload = "{\"name\":\"Hunter Thompson\",\"email\":\"hunter@batcountry.com\",\"phone\":\"+64211234567\",\"account_number\":\"021234693049678\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("POST", "/contacts/anyone", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.post("https://api.nz.sandbox.zepto.money/contacts/anyone")
  .header("content-type", "application/json")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .body("{\"name\":\"Hunter Thompson\",\"email\":\"hunter@batcountry.com\",\"phone\":\"+64211234567\",\"account_number\":\"021234693049678\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"name":"Hunter Thompson","email":"hunter@batcountry.com","phone":"+64211234567","account_number":"021234693049678","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/contacts/anyone');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/contacts/anyone"

    payload := strings.NewReader("{\"name\":\"Hunter Thompson\",\"email\":\"hunter@batcountry.com\",\"phone\":\"+64211234567\",\"account_number\":\"021234693049678\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("content-type", "application/json")
    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

POST /contacts/anyone

Use this endpoint when you want to pay somebody.

The format of the account number should be BB-bbbb-AAAAAAA-SSS where:

B is the bank number (2 digits) and b is the branch number (4 digits). Both constitute the prefix or the bank code.
A is the account number (7 digits) which is right justified.
S is the suffix (2-3 digits). When a bank displays the suffix as two digits, a leading zero is added to pad the suffix to three digits; i.e. BB-bbbb-AAAAAAA-SS becomes BB-bbbb-AAAAAAA-0SS.

Body parameter

{
  "name": "Hunter Thompson",
  "email": "hunter@batcountry.com",
  "phone": "+64211234567",
  "account_number": "021234693049678",
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Parameters

Parameter	In	Type	Required	Description
body	body	AddAnAnyoneContactRequest	true	No description
» name	body	string	true	The name of the Contact (140 max. characters)
» email	body	string	true	The email of the Contact (256 max. characters)
» phone	body	string	true	The phone of the Contact. Must be a valid New Zealand mobile number in ITU-T E.164 or national format
» account_number	body	string	true	The bank account number of the Contact (15-16 characters)
» metadata	body	Metadata	false	Use for your custom data and certain Zepto customisations.

Example responses

201 Response

{
  "data": {
    "id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
    "name": "Hunter Thompson",
    "email": "hunter@batcountry.com",
    "phone": "+64211234567",
    "type": "anyone",
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    },
    "bank_account": {
      "id": "55afddde-4296-4daf-8e49-7ba481ef9608",
      "account_number": "021234693049678",
      "bank_name": "Bank of New Zealand",
      "state": "active",
      "blocks": {
        "debits_blocked": false,
        "credits_blocked": false
      }
    }
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	AddAnAnyoneContactResponse

List all Contacts

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/contacts \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/contacts",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/contacts", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/contacts")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/contacts');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/contacts"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /contacts

By default, all Contacts will be returned. You can apply filters to your query to customise the returned Contact list.

Parameters

Parameter	In	Type	Required	Description
page	query	string	false	Page of results to return, single value, exact match
per_page	query	string	false	Number of results per page, single value, exact match
name	query	string	false	Single value, string search
nickname	query	string	false	Single value, string search
email	query	string	false	Single value, string search
bank_account_id	query	string	false	Single value, exact match
bank_account_account_number	query	string	false	Single value, exact match

Example responses

200 Response

{
  "data": [
    {
      "id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
      "name": "Outstanding Tours Pty Ltd",
      "email": "accounts@outstandingtours.com.au",
      "phone": "0226644022",
      "type": "Zepto account",
      "bank_account": {
        "id": "095c5ab7-7fa8-40fd-b317-cddbbf4c8fbc",
        "account_number": "021234671453378",
        "bank_name": "Bank of New Zealand",
        "state": "active",
        "blocks": {
          "debits_blocked": false,
          "credits_blocked": false
        }
      }
    },
    {
      "id": "49935c67-c5df-4f00-99f4-1413c18a89a0",
      "name": "Adventure Dudes Pty Ltd",
      "email": "accounts@adventuredudes.com.au",
      "phone": "+64276143146",
      "type": "Zepto account",
      "bank_account": {
        "id": "861ff8e4-7acf-4897-9e53-e7c5ae5f7cc0",
        "account_number": "021234471453444",
        "bank_name": "Bank of New Zealand",
        "state": "active",
        "blocks": {
          "debits_blocked": false,
          "credits_blocked": false
        }
      }
    },
    {
      "id": "eb3266f9-e172-4b6c-b802-fe5ac4d3250a",
      "name": "Surfing World Pty Ltd",
      "email": "accounts@surfingworld.com.au",
      "phone": "0270345344",
      "type": "Zepto account",
      "bank_account": {
        "id": null,
        "account_number": null,
        "bank_name": null,
        "state": "disabled",
        "blocks": {
          "debits_blocked": false,
          "credits_blocked": false
        }
      }
    },
    {
      "id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
      "name": "Hunter Thompson",
      "email": "hunter@batcountry.com",
      "phone": "+64211234567",
      "type": "anyone",
      "bank_account": {
        "id": "55afddde-4296-4daf-8e49-7ba481ef9608",
        "account_number": "021234693049678",
        "bank_name": "Bank of New Zealand",
        "state": "pending_verification",
        "blocks": {
          "debits_blocked": false,
          "credits_blocked": false
        }
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	ListAllContactsResponse

Response Headers

Status	Header	Type	Format	Description
200	Link	string		Contains pagination link for next page of collection, if next page exists.
200	Per-Page	integer		Contains the current maximum items in collection. Defaults to 25

Get a Contact

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /contacts/{id}

Get a single Contact by its ID

Parameters

Parameter	In	Type	Required	Description
id	path	string(UUID)	true	Contact ID (`Contact.data.id`)

Example responses

200 Response

{
  "data": {
    "id": "55afddde-4296-4daf-8e49-7ba481ef9608",
    "ref": "CNT.123",
    "name": "Outstanding Tours Pty Ltd",
    "email": "accounts@outstandingtours.com.au",
    "phone": "0211234567",
    "type": "anyone",
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    },
    "bank_account": {
      "id": "fcabeacb-2ef6-4b27-ba19-4f6fa0d57dcb",
      "account_number": "021234693049678",
      "bank_name": "Bank of New Zealand",
      "state": "active",
      "blocks": {
        "debits_blocked": false,
        "credits_blocked": false
      }
    },
    "anyone_account": {
      "id": "31a05f81-25a2-4085-92ef-0d16d0263bff"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	GetAContactResponse
404	Not Found	Not Found	None

Remove a Contact

Code samples

curl --request DELETE \
  --url https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608 \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "DELETE",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = { 'authorization': "Bearer {access-token}" }

conn.request("DELETE", "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.delete("https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608"

    req, _ := http.NewRequest("DELETE", url, nil)

    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

DELETE /contacts/{id}

Parameters

Parameter	In	Type	Required	Description
id	path	string(UUID)	true	Contact ID (`Contact.data.id`)

Responses

Status	Meaning	Description	Schema
204	No Content	No description	None

Update a Contact

Code samples

curl --request PATCH \
  --url https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --data '{"name":"My very own alias","email":"updated@email.com","phone":"0226644022","account_number":"200111930276531","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Patch.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"name\":\"My very own alias\",\"email\":\"updated@email.com\",\"phone\":\"0226644022\",\"account_number\":\"200111930276531\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "PATCH",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608",
  "headers": {
    "content-type": "application/json",
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({
  name: 'My very own alias',
  email: 'updated@email.com',
  phone: '0226644022',
  account_number: '200111930276531',
  metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

payload = "{\"name\":\"My very own alias\",\"email\":\"updated@email.com\",\"phone\":\"0226644022\",\"account_number\":\"200111930276531\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("PATCH", "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.patch("https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")
  .header("content-type", "application/json")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .body("{\"name\":\"My very own alias\",\"email\":\"updated@email.com\",\"phone\":\"0226644022\",\"account_number\":\"200111930276531\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"name":"My very own alias","email":"updated@email.com","phone":"0226644022","account_number":"200111930276531","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608');
$request->setRequestMethod('PATCH');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/contacts/55afddde-4296-4daf-8e49-7ba481ef9608"

    payload := strings.NewReader("{\"name\":\"My very own alias\",\"email\":\"updated@email.com\",\"phone\":\"0226644022\",\"account_number\":\"200111930276531\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")

    req, _ := http.NewRequest("PATCH", url, payload)

    req.Header.Add("content-type", "application/json")
    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

PATCH /contacts/{id}

You can update the name, email, bank account and metadata of any Contact.

Body parameter

{
  "name": "My very own alias",
  "email": "updated@email.com",
  "phone": "0226644022",
  "account_number": "200111930276531",
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Parameters

Parameter	In	Type	Required	Description
id	path	string	true	Contact ID (`Contact.data.id`)
body	body	UpdateAContactRequest	true	No description
» name	body	string	false	The name of the Contact
» email	body	string	false	The email of the Contact
» phone	body	string	false	The phone number of the Contact
» account_number	body	string	false	The bank account number of the Contact
» metadata	body	Metadata	false	Use for your custom data and certain Zepto customisations.

Example responses

200 Response

{
  "data": {
    "id": "fcabeacb-2ef6-4b27-ba19-4f6fa0d57dcb",
    "name": "My very own alias",
    "email": "updated@email.com",
    "phone": "0226644022",
    "type": "anyone",
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    },
    "bank_account": {
      "id": "55afddde-4296-4daf-8e49-7ba481ef9608",
      "account_number": "200111930276531",
      "bank_name": "Zepto SANDBOX Bank",
      "state": "active",
      "blocks": {
        "debits_blocked": false,
        "credits_blocked": false
      }
    },
    "anyone_account": {
      "id": "63232c0a-a783-4ae9-ae73-f0974fe1e345"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	UpdateAContactResponse
404	Not Found	Not Found	None

Payment Requests

A Payment Request (PR) is used to collect funds, via direct debit, from one of your Contacts (as long as there is an accepted Agreement in place).

Applicable scenarios

You send a Payment Request to a Contact in order to collect funds:
1. Given there is an Agreement in place and the Payment Request is within the terms of the Agreement, then it will be automatically approved; or
2. Given the Payment Request is not within the terms of the Agreement, then it will not be created; or
3. There is no Agreement in place, then it will not be created.

Lifecycle

A Payment Request can have the following statuses:

Status	Description
`unverified`	Waiting for available funds response.
`approved`	The debtor has approved the Payment Request.
`declined`	The debtor has declined the Payment Request.
`cancelled`	The creditor has cancelled the Payment Request.

Request Payment

Code samples

curl --request POST \
  --url https://api.nz.sandbox.zepto.money/payment_requests \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: {unique-uuid-per-payment-request}' \
  --data '{"description":"Visible to both initiator and authoriser","matures_at":"2016-12-19T02:10:56.000Z","amount":99000,"authoriser_contact_id":"de86472c-c027-4735-a6a7-234366a27fc7","your_bank_account_id":"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/payment_requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["idempotency-key"] = '{unique-uuid-per-payment-request}'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"description\":\"Visible to both initiator and authoriser\",\"matures_at\":\"2016-12-19T02:10:56.000Z\",\"amount\":99000,\"authoriser_contact_id\":\"de86472c-c027-4735-a6a7-234366a27fc7\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/payment_requests",
  "headers": {
    "content-type": "application/json",
    "accept": "application/json",
    "idempotency-key": "{unique-uuid-per-payment-request}",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({
  description: 'Visible to both initiator and authoriser',
  matures_at: '2016-12-19T02:10:56.000Z',
  amount: 99000,
  authoriser_contact_id: 'de86472c-c027-4735-a6a7-234366a27fc7',
  your_bank_account_id: '9c70871d-8e36-4c3e-8a9c-c0ee20e7c679',
  metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

payload = "{\"description\":\"Visible to both initiator and authoriser\",\"matures_at\":\"2016-12-19T02:10:56.000Z\",\"amount\":99000,\"authoriser_contact_id\":\"de86472c-c027-4735-a6a7-234366a27fc7\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'idempotency-key': "{unique-uuid-per-payment-request}",
    'authorization': "Bearer {access-token}"
    }

conn.request("POST", "/payment_requests", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.post("https://api.nz.sandbox.zepto.money/payment_requests")
  .header("content-type", "application/json")
  .header("accept", "application/json")
  .header("idempotency-key", "{unique-uuid-per-payment-request}")
  .header("authorization", "Bearer {access-token}")
  .body("{\"description\":\"Visible to both initiator and authoriser\",\"matures_at\":\"2016-12-19T02:10:56.000Z\",\"amount\":99000,\"authoriser_contact_id\":\"de86472c-c027-4735-a6a7-234366a27fc7\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"description":"Visible to both initiator and authoriser","matures_at":"2016-12-19T02:10:56.000Z","amount":99000,"authoriser_contact_id":"de86472c-c027-4735-a6a7-234366a27fc7","your_bank_account_id":"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/payment_requests');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'idempotency-key' => '{unique-uuid-per-payment-request}',
  'accept' => 'application/json',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/payment_requests"

    payload := strings.NewReader("{\"description\":\"Visible to both initiator and authoriser\",\"matures_at\":\"2016-12-19T02:10:56.000Z\",\"amount\":99000,\"authoriser_contact_id\":\"de86472c-c027-4735-a6a7-234366a27fc7\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("content-type", "application/json")
    req.Header.Add("accept", "application/json")
    req.Header.Add("idempotency-key", "{unique-uuid-per-payment-request}")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

POST /payment_requests

We strongly recommend to supply an Idempotency-Key header when performing this request to ensure you can safely retry the action in case of an issue. If a header value is omitted or is different to one provided previously, we will be treating a request as a new operation which may lead to a duplicate funds collection. To understand more on how to make idempotent requests, please refer to our Idempotent requests guide.

Body parameter

{
  "description": "Visible to both initiator and authoriser",
  "matures_at": "2016-12-19T02:10:56.000Z",
  "amount": 99000,
  "authoriser_contact_id": "de86472c-c027-4735-a6a7-234366a27fc7",
  "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Parameters

Parameter	In	Type	Required	Description
Idempotency-Key	header	string	false	Idempotency key to support safe retries for 24h
body	body	MakeAPaymentRequestRequest	true	No description
» description	body	string	true	Description visible to the initiator (payee). The first 9 characters supplied will be visible to the authoriser (payer)
» matures_at	body	string(date-time)	true	Date & time in UTC ISO8601 that the Payment will be processed if the request is approved. (If the request is approved after this point in time, it will be processed straight away)
» amount	body	integer	true	Amount in cents to pay the initiator (Min: 1 - Max: 99999999999)
» authoriser_contact_id	body	string	true	The Contact the payment will be requested from (`Contact.data.id`)
» your_bank_account_id	body	string(uuid)	false	Specify where we should settle the funds for this transaction. If omitted, your primary bank account will be used.
» metadata	body	object	false	Use for your custom data and certain Zepto customisations. Stored against generated transactions and included in associated webhook payloads.

Example responses

200 Response

{
  "data": {
    "ref": "PR.39p1",
    "initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
    "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
    "authoriser_id": "970e4526-67d9-4ed9-b554-f5cf390ab775",
    "authoriser_contact_id": "de86472c-c027-4735-a6a7-234366a27fc7",
    "contact_initiated": false,
    "schedule_ref": null,
    "status": "pending_approval",
    "status_reason": null,
    "matures_at": "2021-12-25T00:00:00Z",
    "responded_at": null,
    "created_at": "2021-12-19T02:10:56Z",
    "credit_ref": null,
    "payout": {
      "amount": 99000,
      "description": "Premium Package for 4",
      "matures_at": "2021-12-25T00:00:00Z"
    },
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Created	MakeAPaymentRequestResponse
422	Unprocessable Entity	When a payment is requested from an Anyone Contact with no valid Agreement	MakeAPaymentRequestWithNoAgreementResponse

Get a Payment Request

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/payment_requests/PR.3 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/payment_requests/PR.3")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/payment_requests/PR.3",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/payment_requests/PR.3", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/payment_requests/PR.3")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/payment_requests/PR.3');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/payment_requests/PR.3"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /payment_requests/{payment_request_ref}

Parameters

Parameter	In	Type	Required	Description
payment_request_ref	path	string	true	Single value, exact match

Example responses

200 Response

{
  "data": {
    "ref": "PR.88me",
    "initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
    "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
    "authoriser_id": "970e4526-67d9-4ed9-b554-f5cf390ab775",
    "authoriser_contact_id": "de86472c-c027-4735-a6a7-234366a27fc7",
    "contact_initiated": false,
    "schedule_ref": null,
    "status": "approved",
    "status_reason": null,
    "matures_at": "2021-11-25T00:00:00Z",
    "responded_at": "2021-11-19T02:38:04Z",
    "created_at": "2021-11-19T02:10:56Z",
    "credit_ref": "C.b6tf",
    "payout": {
      "amount": 1200,
      "description": "Xbox Live subscription",
      "matures_at": "2021-11-25T00:00:00Z"
    },
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	GetAPaymentRequestResponse

Cancel a Payment Request

Code samples

curl --request DELETE \
  --url https://api.nz.sandbox.zepto.money/payment_requests/PR.3 \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/payment_requests/PR.3")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "DELETE",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/payment_requests/PR.3",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = { 'authorization': "Bearer {access-token}" }

conn.request("DELETE", "/payment_requests/PR.3", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.delete("https://api.nz.sandbox.zepto.money/payment_requests/PR.3")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/payment_requests/PR.3');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/payment_requests/PR.3"

    req, _ := http.NewRequest("DELETE", url, nil)

    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

DELETE /payment_requests/{payment_request_ref}

A Payment Request can be cancelled as long as the associated transaction's state is maturing or matured.

Parameters

Parameter	In	Type	Required	Description
payment_request_ref	path	string	true	Single value, exact match

Responses

Status	Meaning	Description	Schema
204	No Content	No Content	None

List Collections

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/payment_requests/collections \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/payment_requests/collections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/payment_requests/collections",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/payment_requests/collections", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/payment_requests/collections")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/payment_requests/collections');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/payment_requests/collections"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /payment_requests/collections

Payment Requests where you are the creditor and are collecting funds from your debtor using traditional direct-debit.

Parameters

Parameter	In	Type	Required	Description
page	query	string	false	Page of results to return, single value, exact match
per_page	query	string	false	Number of results per page, single value, exact match

Example responses

200 Response

{
  "data": [
    {
      "ref": "PR.84t6",
      "initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
      "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
      "authoriser_id": "de86472c-c027-4735-a6a7-234366a27fc7",
      "authoriser_contact_id": "fb6a9252-3818-44dc-b5aa-2195391a746f",
      "contact_initiated": false,
      "schedule_ref": "PRS.89t3",
      "status": "approved",
      "status_reason": null,
      "matures_at": "2021-07-18T02:10:00Z",
      "responded_at": "2021-07-18T02:10:00Z",
      "created_at": "2021-07-18T02:10:00Z",
      "credit_ref": "C.6gr7",
      "payout": {
        "amount": 4999,
        "description": "Subscription Payment",
        "matures_at": "2021-07-18T02:10:00Z"
      }
    },
    {
      "ref": "PR.45h7",
      "initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
      "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
      "authoriser_id": "de86472c-c027-4735-a6a7-234366a27fc7",
      "authoriser_contact_id": "fb6a9252-3818-44dc-b5aa-2195391a746f",
      "contact_initiated": false,
      "schedule_ref": null,
      "status": "pending_approval",
      "status_reason": null,
      "matures_at": "2021-03-09T16:58:00Z",
      "responded_at": null,
      "created_at": "2021-03-09T16:58:00Z",
      "credit_ref": null,
      "payout": {
        "amount": 3000,
        "description": "Membership fees",
        "matures_at": "2021-03-09T16:58:00Z"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	ListPaymentRequestCollectionsResponse

Response Headers

Status	Header	Type	Format	Description
200	Link	string		Contains pagination link for next page of collection, if next page exists.
200	Per-Page	integer		Contains the current maximum items in collection. Defaults to 25

Payments

A Payment is used to disburse funds to your Contacts.

Lifecycle

Example payout reversal response

{
  "data": [
  {
    "ref": "C.3",
    "parent_ref": "PB.1",
    "type": "credit",
    "category": "payout_reversal",
    "created_at": "2021-04-07T23:15:00Z",
    "matures_at": "2021-04-07T23:15:00Z",
    "cleared_at": null,
    "bank_ref": null,
    "status": "maturing",
    "status_changed_at": "2016-12-08T23:15:00Z",
    "party_contact_id": "26297f44-c5e1-40a1-9864-3e0b0754c32a",
    "party_name": "Sanford-Rees",
    "party_nickname": "sanford-rees-8",
    "description": "Payout reversal of D.1 for Sanford-Rees due to no account or incorrect account number"
      "amount": 1,
    "reversal_details": {
      "source_debit_ref": "D.1",
      "source_credit_failure": {
        "code": "E554-199",
        "title": "Unknown BECS Error",
        "detail": "An unknown BECS error occurred. Please contact Zepto for assistance."
      }
    }
  }
  ]
}

A Payment is simply a group of Payouts, therefore it does not have a particular status. Its Payouts however have their status regularly updated. For a list of possible Payout statuses check out the Transactions.

Payout Reversal

When Zepto is unable to credit funds to a recipient, we will automatically create a payout reversal credit back to the payer. Furthermore, within the payout reversal credit, Zepto will include details in the description and under the reversal_details key as to why the original credit to the recipient failed.

Make a Payment

Code samples

curl --request POST \
  --url https://api.nz.sandbox.zepto.money/payments \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: {unique-uuid-per-payment}' \
  --data '{"description":"The SuperPackage","matures_at":"2021-06-13T00:00:00Z","your_bank_account_id":"83623359-e86e-440c-9780-432a3bc3626f","payouts":[{"amount":30000,"description":"A tandem skydive jump SB23094","recipient_contact_id":"48b89364-1577-4c81-ba02-96705895d457","metadata":{"invoice_ref":"BILL-0001","invoice_id":"c80a9958-e805-47c0-ac2a-c947d7fd778d","custom_key":"Custom string","another_custom_key":"Maybe a URL"}}],"metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["idempotency-key"] = '{unique-uuid-per-payment}'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"description\":\"The SuperPackage\",\"matures_at\":\"2021-06-13T00:00:00Z\",\"your_bank_account_id\":\"83623359-e86e-440c-9780-432a3bc3626f\",\"payouts\":[{\"amount\":30000,\"description\":\"A tandem skydive jump SB23094\",\"recipient_contact_id\":\"48b89364-1577-4c81-ba02-96705895d457\",\"metadata\":{\"invoice_ref\":\"BILL-0001\",\"invoice_id\":\"c80a9958-e805-47c0-ac2a-c947d7fd778d\",\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}],\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/payments",
  "headers": {
    "content-type": "application/json",
    "accept": "application/json",
    "idempotency-key": "{unique-uuid-per-payment}",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({
  description: 'The SuperPackage',
  matures_at: '2021-06-13T00:00:00Z',
  your_bank_account_id: '83623359-e86e-440c-9780-432a3bc3626f',
  payouts: [
    {
      amount: 30000,
      description: 'A tandem skydive jump SB23094',
      recipient_contact_id: '48b89364-1577-4c81-ba02-96705895d457',
      metadata: {
        invoice_ref: 'BILL-0001',
        invoice_id: 'c80a9958-e805-47c0-ac2a-c947d7fd778d',
        custom_key: 'Custom string',
        another_custom_key: 'Maybe a URL'
      }
    }
  ],
  metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

payload = "{\"description\":\"The SuperPackage\",\"matures_at\":\"2021-06-13T00:00:00Z\",\"your_bank_account_id\":\"83623359-e86e-440c-9780-432a3bc3626f\",\"payouts\":[{\"amount\":30000,\"description\":\"A tandem skydive jump SB23094\",\"recipient_contact_id\":\"48b89364-1577-4c81-ba02-96705895d457\",\"metadata\":{\"invoice_ref\":\"BILL-0001\",\"invoice_id\":\"c80a9958-e805-47c0-ac2a-c947d7fd778d\",\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}],\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'idempotency-key': "{unique-uuid-per-payment}",
    'authorization': "Bearer {access-token}"
    }

conn.request("POST", "/payments", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.post("https://api.nz.sandbox.zepto.money/payments")
  .header("content-type", "application/json")
  .header("accept", "application/json")
  .header("idempotency-key", "{unique-uuid-per-payment}")
  .header("authorization", "Bearer {access-token}")
  .body("{\"description\":\"The SuperPackage\",\"matures_at\":\"2021-06-13T00:00:00Z\",\"your_bank_account_id\":\"83623359-e86e-440c-9780-432a3bc3626f\",\"payouts\":[{\"amount\":30000,\"description\":\"A tandem skydive jump SB23094\",\"recipient_contact_id\":\"48b89364-1577-4c81-ba02-96705895d457\",\"metadata\":{\"invoice_ref\":\"BILL-0001\",\"invoice_id\":\"c80a9958-e805-47c0-ac2a-c947d7fd778d\",\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}],\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"description":"The SuperPackage","matures_at":"2021-06-13T00:00:00Z","your_bank_account_id":"83623359-e86e-440c-9780-432a3bc3626f","payouts":[{"amount":30000,"description":"A tandem skydive jump SB23094","recipient_contact_id":"48b89364-1577-4c81-ba02-96705895d457","metadata":{"invoice_ref":"BILL-0001","invoice_id":"c80a9958-e805-47c0-ac2a-c947d7fd778d","custom_key":"Custom string","another_custom_key":"Maybe a URL"}}],"metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/payments');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'idempotency-key' => '{unique-uuid-per-payment}',
  'accept' => 'application/json',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/payments"

    payload := strings.NewReader("{\"description\":\"The SuperPackage\",\"matures_at\":\"2021-06-13T00:00:00Z\",\"your_bank_account_id\":\"83623359-e86e-440c-9780-432a3bc3626f\",\"payouts\":[{\"amount\":30000,\"description\":\"A tandem skydive jump SB23094\",\"recipient_contact_id\":\"48b89364-1577-4c81-ba02-96705895d457\",\"metadata\":{\"invoice_ref\":\"BILL-0001\",\"invoice_id\":\"c80a9958-e805-47c0-ac2a-c947d7fd778d\",\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}],\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("content-type", "application/json")
    req.Header.Add("accept", "application/json")
    req.Header.Add("idempotency-key", "{unique-uuid-per-payment}")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

POST /payments

We strongly recommend to supply an Idempotency-Key header when performing this request to ensure you can safely retry the action in case of an issue. If a header value is omitted or is different to one provided previously, we will be treating a request as a new operation which may lead to duplicate payments. To understand more on how to make idempotent requests, please refer to our Idempotent requests guide.

Body parameter

{
  "description": "The SuperPackage",
  "matures_at": "2021-06-13T00:00:00Z",
  "your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
  "payouts": [
    {
      "amount": 30000,
      "description": "A tandem skydive jump SB23094",
      "recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
      "metadata": {
        "invoice_ref": "BILL-0001",
        "invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
        "custom_key": "Custom string",
        "another_custom_key": "Maybe a URL"
      }
    }
  ],
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Parameters

Parameter	In	Type	Required	Description
Idempotency-Key	header	string	false	Idempotency key to support safe retries for 24h
body	body	MakeAPaymentRequest	true	No description
» description	body	string	true	User description. Only visible to the payer
» matures_at	body	string(date-time)	true	Date & time in UTC ISO8601 the Payment should be processed. (Can not be earlier than the start of current day in NZST)
» your_bank_account_id	body	string	true	Specify where we should take the funds for this transaction. If omitted, your primary bank account will be used.
» payouts	body	[Payout]	true	One Payout object only
»» Payout	body	Payout	false	The actual Payout
»»» amount	body	integer	true	Amount in cents to pay the recipient
»»» description	body	string	true	Description that both the payer and recipient can see. For Direct Entry payments, the payout recipient will see the first 9 characters of this description.
»»» recipient_contact_id	body	string	true	Contact to pay (`Contact.data.id`)
»»» metadata	body	Metadata	false	Use for your custom data and certain Zepto customisations. Stored against generated transactions and included in associated webhook payloads.
»» metadata	body	Metadata	false	Use for your custom data and certain Zepto customisations.

Example responses

201 Response

{
  "data": {
    "ref": "PB.1",
    "your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
    "payouts": [
      {
        "ref": "D.1",
        "recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
        "batch_description": "The SuperPackage",
        "matures_at": "2016-09-13T23:50:44Z",
        "created_at": "2016-09-10T23:50:44Z",
        "status": "maturing",
        "amount": 30000,
        "description": "A tandem skydive jump SB23094",
        "from_id": "83623359-e86e-440c-9780-432a3bc3626f",
        "to_id": "21066764-c103-4e7f-b436-4cee7db5f400",
        "metadata": {
          "invoice_ref": "BILL-0001",
          "invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
          "custom_key": "Custom string",
          "another_custom_key": "Maybe a URL"
        }
      }
    ],
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	MakeAPaymentResponse

List all Payments

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/payments \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/payments",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/payments", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/payments")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/payments');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/payments"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /payments

Parameters

Parameter	In	Type	Required	Description
page	query	string	false	Page of results to return, single value, exact match
per_page	query	string	false	Number of results per page, single value, exact match

Example responses

200 Response

{
  "data": [
    {
      "ref": "PB.1",
      "your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
      "payouts": [
        {
          "ref": "D.1",
          "recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
          "batch_description": "This description is only available to the payer",
          "matures_at": "2016-09-13T23:50:44Z",
          "created_at": "2016-09-10T23:50:44Z",
          "status": "maturing",
          "amount": 30000,
          "description": "The recipient will see this description",
          "from_id": "83623359-e86e-440c-9780-432a3bc3626f",
          "to_id": "21066764-c103-4e7f-b436-4cee7db5f400",
          "metadata": {
            "invoice_ref": "BILL-0001",
            "invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
            "custom_key": "Custom string",
            "another_custom_key": "Maybe a URL"
          }
        },
        {
          "ref": "D.2",
          "recipient_contact_id": "dc6f1e60-3803-43ca-a200-7d641816f57f",
          "batch_description": "This description is only available to the payer",
          "matures_at": "2016-09-13T23:50:44Z",
          "created_at": "2016-09-10T23:50:44Z",
          "status": "maturing",
          "amount": 30000,
          "description": "The recipient will see this description",
          "from_id": "48b89364-1577-4c81-ba02-96705895d457",
          "to_id": "f989d9cd-87fc-4c73-b0a4-1eb0e8768d3b"
        }
      ],
      "metadata": {
        "custom_key": "Custom string",
        "another_custom_key": "Maybe a URL"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	ListAllPaymentsResponse

Response Headers

Status	Header	Type	Format	Description
200	Link	string		Contains pagination link for next page of collection, if next page exists.
200	Per-Page	integer		Contains the current maximum items in collection. Defaults to 25

Get a Payment

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/payments/PB.1 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/payments/PB.1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/payments/PB.1",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/payments/PB.1", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/payments/PB.1")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/payments/PB.1');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/payments/PB.1"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /payments/{payment_ref}

Get a single payment by its reference

Parameters

Parameter	In	Type	Required	Description
payment_ref	path	string	true	Payment reference

Example responses

200 Response

{
  "data": {
    "ref": "PB.1",
    "your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
    "payouts": [
      {
        "ref": "D.1",
        "recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
        "batch_description": "The SuperPackage",
        "matures_at": "2016-09-13T23:50:44Z",
        "created_at": "2016-09-10T23:50:44",
        "status": "maturing",
        "amount": 30000,
        "description": "A tandem skydive jump SB23094",
        "from_id": "83623359-e86e-440c-9780-432a3bc3626f",
        "to_id": "21066764-c103-4e7f-b436-4cee7db5f400",
        "metadata": {
          "invoice_ref": "BILL-0001",
          "invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
          "custom_key": "Custom string",
          "another_custom_key": "Maybe a URL"
        }
      }
    ],
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	GetAPaymentResponse

Payouts

This endpoint gives you some control over a transaction:

After it has been created; and
Before it has been submitted to the banks; or

Void a Payment

Code samples

curl --request DELETE \
  --url https://api.nz.sandbox.zepto.money/payouts/D.48 \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --data false

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/payouts/D.48")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "false"

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "DELETE",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/payouts/D.48",
  "headers": {
    "content-type": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

payload = "false"

headers = {
    'content-type': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("DELETE", "/payouts/D.48", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.delete("https://api.nz.sandbox.zepto.money/payouts/D.48")
  .header("content-type", "application/json")
  .header("authorization", "Bearer {access-token}")
  .body("false")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('false');

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/payouts/D.48');
$request->setRequestMethod('DELETE');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/payouts/D.48"

    payload := strings.NewReader("false")

    req, _ := http.NewRequest("DELETE", url, payload)

    req.Header.Add("content-type", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

DELETE /payouts/{ref}

You can void any Payment from your account that has not yet matured.

Body parameter

false

Parameters

Parameter	In	Type	Required	Description
ref	path	string	true	Payment debit reference number e.g D.48

Responses

Status	Meaning	Description	Schema
204	No Content	No Content	None

Refunds

Refunds can be issued for any successfully completed Payment Request transaction. This includes Payment Requests for direct debit payments.

This allows you to return any funds that were previously collected or received into one of your bank accounts.

Issue a Refund

Code samples

curl --request POST \
  --url https://api.nz.sandbox.zepto.money/credits/string/refunds \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: {unique-uuid-per-refund}' \
  --data '{"amount":500,"reason":"Because reason","your_bank_account_id":"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/credits/string/refunds")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["idempotency-key"] = '{unique-uuid-per-refund}'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"amount\":500,\"reason\":\"Because reason\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/credits/string/refunds",
  "headers": {
    "content-type": "application/json",
    "accept": "application/json",
    "idempotency-key": "{unique-uuid-per-refund}",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({
  amount: 500,
  reason: 'Because reason',
  your_bank_account_id: '9c70871d-8e36-4c3e-8a9c-c0ee20e7c679',
  metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

payload = "{\"amount\":500,\"reason\":\"Because reason\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'idempotency-key': "{unique-uuid-per-refund}",
    'authorization': "Bearer {access-token}"
    }

conn.request("POST", "/credits/string/refunds", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.post("https://api.nz.sandbox.zepto.money/credits/string/refunds")
  .header("content-type", "application/json")
  .header("accept", "application/json")
  .header("idempotency-key", "{unique-uuid-per-refund}")
  .header("authorization", "Bearer {access-token}")
  .body("{\"amount\":500,\"reason\":\"Because reason\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"amount":500,"reason":"Because reason","your_bank_account_id":"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/credits/string/refunds');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'idempotency-key' => '{unique-uuid-per-refund}',
  'accept' => 'application/json',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/credits/string/refunds"

    payload := strings.NewReader("{\"amount\":500,\"reason\":\"Because reason\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("content-type", "application/json")
    req.Header.Add("accept", "application/json")
    req.Header.Add("idempotency-key", "{unique-uuid-per-refund}")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

POST /credits/{credit_ref}/refunds

Certain rules apply to the issuance of a refund:

Must be applied against a successfully cleared Payment Request
Many refunds may be created against the original Payment Request
The total refunded amount must not exceed the original value

We strongly recommend to supply an Idempotency-Key header when performing this request to ensure you can safely retry the action in case of an issue. If a header value is omitted or is different to one provided previously, we will be treating a request as a new operation which may lead to duplicate refunds. To understand more on how to make idempotent requests, please refer to our Idempotent requests guide.

Body parameter

{
  "amount": 500,
  "reason": "Because reason",
  "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Parameters

Parameter	In	Type	Required	Description
Idempotency-Key	header	string	false	Idempotency key to support safe retries for 24h
credit_ref	path	string	true	The credit reference number e.g C.625v
body	body	IssueARefundRequest	true	No description
» amount	body	integer	true	Amount in cents refund (Min: 1 - Max: 99999999999)
» reason	body	string	false	Reason for the refund. First 9 characters are visible to both parties.
» your_bank_account_id	body	string(uuid)	false	Specify where we should take the funds for this transaction. If omitted, your primary bank account will be used.
» metadata	body	Metadata	false	Use for your custom data and certain Zepto customisations.

Example responses

200 Response

{
  "data": {
    "ref": "PRF.7f4",
    "for_ref": "C.1gf22",
    "debit_ref": "D.63hgf",
    "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
    "created_at": "2021-06-01T07:20:24Z",
    "amount": 500,
    "reason": "Subscription refund",
    "contacts": {
      "source_contact_id": "194b0237-6c2c-4705-b4fb-308274b14eda",
      "target_contact_id": "3694ff53-32ea-40ae-8392-821e48d7bd5a"
    },
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Created	IssueARefundResponse

List Refunds

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/refunds/outgoing \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/refunds/outgoing")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/refunds/outgoing",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/refunds/outgoing", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/refunds/outgoing")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/refunds/outgoing');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/refunds/outgoing"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /refunds/outgoing

Parameters

Parameter	In	Type	Required	Description
page	query	string	false	Page of results to return, single value, exact match
per_page	query	string	false	Number of results per page, single value, exact match

Example responses

200 Response

{
  "data": [
    {
      "ref": "PRF.2",
      "for_ref": "C.5",
      "debit_ref": "D.5a",
      "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
      "created_at": "2017-05-09T04:45:26Z",
      "amount": 5,
      "reason": "Because reason",
      "metadata": {
        "custom_key": "Custom string",
        "another_custom_key": "Maybe a URL"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	ListOutgoingRefundsResponse

Response Headers

Status	Header	Type	Format	Description
200	Link	string		Contains pagination link for next page of collection, if next page exists.
200	Per-Page	integer		Contains the current maximum items in collection. Defaults to 25

Retrieve a Refund

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/refunds/PRF.75f \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/refunds/PRF.75f")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/refunds/PRF.75f",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/refunds/PRF.75f", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/refunds/PRF.75f")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/refunds/PRF.75f');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/refunds/PRF.75f"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /refunds/{refund_ref}

Get a single Refund by its reference

Parameters

Parameter	In	Type	Required	Description
refund_ref	path	string	true	Single value, exact match

Example responses

200 Response

{
  "data": {
    "ref": "PRF.1",
    "for_ref": "C.59",
    "debit_ref": "D.hi",
    "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
    "created_at": "2017-05-08T07:20:24Z",
    "amount": 500,
    "reason": "Because reason",
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	RetrieveARefundResponse

Transactions

By default, the transactions endpoint provides a detailed look at all past, current and future debits & credits related to your account.

Want to also know about the debits & credits applied to the other party? No problem! Use the both_parties=true query string.

Lifecycle

A transaction (debit or credit) can have the following statuses:

Status	Description
`maturing`	The maturation date has not yet been reached.
`matured`	The maturation date has been reached and the transaction is eligible for processing.
`preprocessing`	The transaction is undergoing pre-checks before being sent to the bank.
`processing`	The transaction has been submitted to the bank.
`clearing`	Waiting for confirmation from the bank that the transaction has succeeded.
`cleared`	The transaction is complete.
`rejected`	The bank has rejected the transaction due to incorrect bank account details.
`returned`	The transaction did not successfully clear.
`voided`	The transaction has been cancelled and is no longer eligible for processing.
`pending_verification`	The bank account must be verified before the transaction can proceed.
`paused`	The transaction has temporary been paused by Zepto pending internal review.

Failure codes

Example response

{
  "data": [
    {
      "ref": "D.3",
      "parent_ref": null,
      "type": "debit",
      "category": "payout_refund",
      "created_at": "2021-04-07T23:15:00Z",
      "matures_at": "2021-04-10T23:15:00Z",
      "cleared_at": null,
      "bank_ref": null,
      "status": "returned",
      "status_changed_at": "2021-04-08T23:15:00Z",
      "failure" : {
        "code": "E554-251",
        "title": "Voided By Initiator",
        "detail": "The transaction was voided by its initiator.",
      },
      "failure_details": "Wrong amount - approved by Stacey"
      "party_contact_id": "26297f44-c5e1-40a1-9864-3e0b0754c32a",
      "party_name": "Sanford-Rees",
      "party_nickname": "sanford-rees-8",
      "description": null,
      "amount": 1,
      "bank_account_id": "56df206a-aaff-471a-b075-11882bc8906a"
    }
  ]
}

The rejected, returned & voided statuses are always accompanied by a failure code, title and detail as listed below. '544' denotes ISO 3166-1 numeric code for New Zealand.

Credit failures

Code	Title	Detail
E554-150	Voided By Admin	The transaction was voided by an administrator.
E554-151	Voided By Initiator	The transaction was voided by its initiator.
E554-152	Insufficient Funds	There were insufficient funds to complete the transaction.
E554-153	System Error	The transaction was unable to complete. Please contact Zepto for assistance.
E554-154	Account Blocked	The target account is blocked and cannot receive funds.
E554-199	Unknown BECS Error	An unknown BECS error occurred. Please contact Zepto for assistance.

Debit failures

Code	Title	Detail
E554-201	No Authority	The target account doesn't have a direct debit authority.
E554-202	Authority Cancelled	The customer has cancelled your direct debit authority. Please refer to customer.
E554-203	Payment Limit Exceeded	The transaction exceeds the payment limit allowed for the target account's direct debit authority.
E554-204	Dishonoured Insufficient Funds	There were insufficient funds to complete the transaction.
E554-205	Payment Stopped	The transaction has been stopped. Please refer to customer.
E554-206	Account Not Found	The target account number is incorrect.
E554-207	Account Closed	The target account is closed.
E554-208	Account Transferred	The target account has been moved.
E554-250	Voided By Admin	The transaction was voided by an administrator.
E554-251	Voided By Initiator	The transaction was voided by its initiator.
E554-252	Insufficient Funds	There were insufficient funds to complete the transaction.
E554-253	System Error	The transaction was unable to complete. Please contact Zepto for assistance.
E554-299	Unknown BECS Error	An unknown BECS error occurred. Please contact Zepto for assistance.

List all transactions

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/transactions \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/transactions",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/transactions", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/transactions")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/transactions');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/transactions"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /transactions

By default, Zepto will search and return all transactions created in the last 30 days. You can adjust this up to 1 year by defining the min_created_date query string parameter defined below.

Parameters

Parameter	In	Type	Required	Description
page	query	string	false	Page of results to return, single value, exact match
per_page	query	string	false	Number of results per page, single value, exact match
ref (debit or credit)	query	string	false	Single value, exact match
parent_ref	query	string	false	Single value, exact match
bank_ref	query	string	false	Single value, exact match
both_parties	query	boolean	false	Single value, exact match. Will also list debits & credits applied to the other party
status	query	array[string]	false	Multiple values, exact match
category	query	array[string]	false	Multiple values, exact match
type	query	array[string]	false	Multiple values, exact match
other_party	query	string	false	Single value, string search. Cannot be combine with `both_parties` query string
other_party_bank_ref	query	string	false	Single value, exact match
party_contact_id	query	string	false	Single value, exact match. Cannot be combine with `both_parties` query string
description	query	string	false	Single value, string search
min_amount	query	integer	false	Cents, single value, exact match
max_amount	query	integer	false	Cents, single value, exact match
min_created_date	query	string(date-time)	false	Date/time UTC ISO 8601 format, single value, exact match
max_created_date	query	string(date-time)	false	Date/time UTC ISO 8601 format, single value, exact match
min_matured_date	query	string(date-time)	false	Date/time UTC ISO 8601 format, single value, exact match
max_matured_date	query	string(date-time)	false	Date/time UTC ISO 8601 format, single value, exact match
min_cleared_date	query	string(date-time)	false	Date/time UTC ISO 8601 format, single value, exact match
max_cleared_date	query	string(date-time)	false	Date/time UTC ISO 8601 format, single value, exact match
min_status_changed_date	query	string(date-time)	false	Date/time UTC ISO 8601 format, single value, exact match
max_status_changed_date	query	string(date-time)	false	Date/time UTC ISO 8601 format, single value, exact match

Enumerated Values

Parameter	Value
status	maturing
status	matured
status	preprocessing
status	processing
status	clearing
status	cleared
status	rejected
status	returned
status	voided
status	pending_verification
status	paused
category	payout
category	payout_refund
category	invoice
type	debit
type	credit

Example responses

200 Response

{
  "data": [
    {
      "ref": "D.3",
      "parent_ref": null,
      "type": "debit",
      "category": "payout_refund",
      "created_at": "2021-04-07T23:15:00Z",
      "matures_at": "2021-04-07T23:15:00Z",
      "cleared_at": "2021-04-10T23:15:00Z",
      "bank_ref": "DT.9a",
      "status": "cleared",
      "status_changed_at": "2021-04-10T23:15:00Z",
      "party_contact_id": "31354923-b1e9-4d65-b03c-415ead89cbf3",
      "party_name": "Sanford-Rees",
      "party_nickname": null,
      "party_bank_ref": "CT.11",
      "description": null,
      "amount": 20000,
      "bank_account_id": "56df206a-aaff-471a-b075-11882bc8906a",
      "channels": [
        "direct_entry"
      ],
      "current_channel": "direct_entry"
    },
    {
      "ref": "D.2",
      "parent_ref": "PB.2",
      "type": "debit",
      "category": "payout",
      "created_at": "2016-12-06T23:15:00Z",
      "matures_at": "2016-12-09T23:15:00Z",
      "cleared_at": null,
      "bank_ref": null,
      "status": "maturing",
      "status_changed_at": "2016-12-06T23:15:00Z",
      "party_contact_id": "3c6e31d3-1dc1-448b-9512-0320bc44fdcf",
      "party_name": "Gutmann-Schmidt",
      "party_nickname": null,
      "party_bank_ref": null,
      "description": "Batteries for hire",
      "amount": 2949299,
      "bank_account_id": "56df206a-aaff-471a-b075-11882bc8906a",
      "channels": [
        "direct_entry"
      ],
      "current_channel": "direct_entry"
    },
    {
      "ref": "C.2",
      "parent_ref": "PB.s0z",
      "type": "credit",
      "category": "payout",
      "created_at": "2016-12-05T23:15:00Z",
      "matures_at": "2016-12-06T23:15:00Z",
      "cleared_at": "2016-12-09T23:15:00Z",
      "bank_ref": "CT.1",
      "status": "cleared",
      "status_changed_at": "2016-12-09T23:15:00Z",
      "party_contact_id": "33c6e31d3-1dc1-448b-9512-0320bc44fdcf",
      "party_name": "Price and Sons",
      "party_nickname": "price-and-sons-2",
      "party_bank_ref": null,
      "description": "Online purchase",
      "amount": 19999,
      "bank_account_id": "c2e329ae-606f-4311-a9ab-a751baa1915c",
      "channels": [
        "direct_entry"
      ],
      "current_channel": "direct_entry",
      "metadata": {
        "customer_id": "xur4492",
        "product_ref": "TSXL392110x"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	ListAllTransactionsResponse

Unassigned Agreements

An agreement with no preset authoriser that can only be accepted once and must be accepted within a predefined time period.

Unassigned Agreements are shared using the generated link available in the response body. You can then include it in an email, text message, embed it in an iFrame, etc...

Please refer to the Unassigned Agreement article in our knowledge base for more information.

Propose an Unassigned Agreement

Code samples

curl --request POST \
  --url https://api.nz.sandbox.zepto.money/unassigned_agreements \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --data '{"expiry_in_seconds":60,"single_use":false,"terms":{"per_payout":{"min_amount":null,"max_amount":10000},"per_frequency":{"days":7,"max_amount":1000000}},"metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/unassigned_agreements")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"expiry_in_seconds\":60,\"single_use\":false,\"terms\":{\"per_payout\":{\"min_amount\":null,\"max_amount\":10000},\"per_frequency\":{\"days\":7,\"max_amount\":1000000}},\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/unassigned_agreements",
  "headers": {
    "content-type": "application/json",
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({
  expiry_in_seconds: 60,
  single_use: false,
  terms: {
    per_payout: { min_amount: null, max_amount: 10000 },
    per_frequency: { days: 7, max_amount: 1000000 }
  },
  metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

payload = "{\"expiry_in_seconds\":60,\"single_use\":false,\"terms\":{\"per_payout\":{\"min_amount\":null,\"max_amount\":10000},\"per_frequency\":{\"days\":7,\"max_amount\":1000000}},\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"

headers = {
    'content-type': "application/json",
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("POST", "/unassigned_agreements", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.post("https://api.nz.sandbox.zepto.money/unassigned_agreements")
  .header("content-type", "application/json")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .body("{\"expiry_in_seconds\":60,\"single_use\":false,\"terms\":{\"per_payout\":{\"min_amount\":null,\"max_amount\":10000},\"per_frequency\":{\"days\":7,\"max_amount\":1000000}},\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"expiry_in_seconds":60,"single_use":false,"terms":{"per_payout":{"min_amount":null,"max_amount":10000},"per_frequency":{"days":7,"max_amount":1000000}},"metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/unassigned_agreements');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/unassigned_agreements"

    payload := strings.NewReader("{\"expiry_in_seconds\":60,\"single_use\":false,\"terms\":{\"per_payout\":{\"min_amount\":null,\"max_amount\":10000},\"per_frequency\":{\"days\":7,\"max_amount\":1000000}},\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("content-type", "application/json")
    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

POST /unassigned_agreements

Create an Unassigned Agreement.

You can set any of the term metrics to null if you wish them to not have a limit.

Body parameter

{
  "expiry_in_seconds": 60,
  "single_use": false,
  "terms": {
    "per_payout": {
      "min_amount": null,
      "max_amount": 10000
    },
    "per_frequency": {
      "days": 7,
      "max_amount": 1000000
    }
  },
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Parameters

Parameter	In	Type	Required	Description
body	body	ProposeUnassignedAgreementRequest	true	No description
» expiry_in_seconds	body	integer	true	The amount of time in seconds before the Unassigned Agreement can no longer be accepted.
» single_use	body	boolean	false	Optionally propose a single use agreement. When the Unassigned Agreement is accepted and a Payment Request is approved according to the Agreement terms, the agreement will automatically become `expended`. The proposed agreement must have equal max/min `per_payout` amounts and `null` `per_frequency` amounts. Furthermore, we will automatically check that the authoriser's bank account has sufficient funds to honour the agreement terms.
» terms	body	Terms	true	Terms
»» per_payout	body	PerPayout	true	No description
»»» min_amount	body	integer	true	Minimum amount in cents a Payment Request can be in order to be auto-approved. Specify `null` for no limit.
»»» max_amount	body	integer	true	Maximum amount in cents a Payment Request can be in order to be auto-approved. Specify `null` for no limit.
»» per_frequency	body	PerFrequency	true	No description
»»» days	body	integer	true	Amount of days to apply against the frequency. Specify `null` for no limit.
»»» max_amount	body	integer	true	Maximum amount in cents the total of all PRs can be for the duration of the frequency. Specify `null` for no limit.
»» metadata	body	Metadata	false	Use for your custom data and certain Zepto customisations.

Example responses

200 Response

{
  "data": {
    "ref": "A.4k",
    "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
    "status": "proposed",
    "responded_at": null,
    "created_at": "2017-03-20T00:53:27Z",
    "terms": {
      "per_payout": {
        "max_amount": 10000,
        "min_amount": null
      },
      "per_frequency": {
        "days": 7,
        "max_amount": 1000000
      }
    },
    "assignment_expires_at": "2017-03-20T00:54:27Z",
    "link": "https://go.nz.sandbox.zepto.money/unassigned_agreements/b61fc159-8779-4a17-a826-e398e3e7e211/invitation",
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Created	ProposeUnassignedAgreementResponse

List all Unassigned Agreements

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/unassigned_agreements \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/unassigned_agreements")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/unassigned_agreements",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/unassigned_agreements", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/unassigned_agreements")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/unassigned_agreements');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/unassigned_agreements"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /unassigned_agreements

Will return all Unassigned Agreements that have not yet been accepted.

Parameters

Parameter	In	Type	Required	Description
page	query	string	false	Page of results to return, single value, exact match
per_page	query	string	false	Number of results per page, single value, exact match

Example responses

200 Response

{
  "data": [
    {
      "ref": "A.4k",
      "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
      "status": "proposed",
      "responded_at": null,
      "created_at": "2017-03-20T00:53:27Z",
      "terms": {
        "per_payout": {
          "max_amount": 10000,
          "min_amount": null
        },
        "per_frequency": {
          "days": 7,
          "max_amount": 1000000
        }
      },
      "assignment_expires_at": "2017-03-20T00:54:27Z",
      "link": "https://go.nz.sandbox.zepto.money/unassigned_agreements/b61fc159-8779-4a17-a826-e398e3e7e211/invitation"
    },
    {
      "ref": "A.7ea",
      "initiator_id": "b61fc159-8779-4a17-a826-e398e3e7e211",
      "status": "proposed",
      "responded_at": null,
      "created_at": "2017-03-21T00:53:27Z",
      "terms": {
        "per_payout": {
          "max_amount": null,
          "min_amount": null
        },
        "per_frequency": {
          "days": null,
          "max_amount": null
        }
      },
      "assignment_expires_at": "2017-03-21T00:54:27Z",
      "link": "https://go.nz.sandbox.zepto.money/unassigned_agreements/4e2728cc-b4ba-42c2-a6c3-26a7758de58d/invitation"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	ListUnassignedAgreementsResponse

Response Headers

Status	Header	Type	Format	Description
200	Link	string		Contains pagination link for next page of collection, if next page exists.
200	Per-Page	integer		Contains the current maximum items in collection. Defaults to 25

Get an Unassigned Agreement

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/unassigned_agreements/A.4k \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/unassigned_agreements/A.4k")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/unassigned_agreements/A.4k",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/unassigned_agreements/A.4k", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/unassigned_agreements/A.4k")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/unassigned_agreements/A.4k');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/unassigned_agreements/A.4k"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /unassigned_agreements/{unassigned_agreement_ref}

Get a single Unassigned Agreement by its reference.

Parameters

Parameter	In	Type	Required	Description
unassigned_agreement_ref	path	string	true	Single value, exact match

Example responses

200 Response

{
  "data": {
    "ref": "A.4k",
    "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
    "status": "proposed",
    "responded_at": null,
    "created_at": "2017-03-20T00:53:27Z",
    "terms": {
      "per_payout": {
        "max_amount": 10000,
        "min_amount": null
      },
      "per_frequency": {
        "days": 7,
        "max_amount": 1000000
      }
    },
    "assignment_expires_at": "2017-03-20T00:54:27Z",
    "link": "https://go.nz.sandbox.zepto.money/unassigned_agreements/b61fc159-8779-4a17-a826-e398e3e7e211/invitation"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	GetUnassignedAgreementResponse

Delete an Unassigned Agreement

Code samples

curl --request DELETE \
  --url https://api.nz.sandbox.zepto.money/unassigned_agreements/A.2 \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/unassigned_agreements/A.2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "DELETE",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/unassigned_agreements/A.2",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = { 'authorization': "Bearer {access-token}" }

conn.request("DELETE", "/unassigned_agreements/A.2", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.delete("https://api.nz.sandbox.zepto.money/unassigned_agreements/A.2")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/unassigned_agreements/A.2');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/unassigned_agreements/A.2"

    req, _ := http.NewRequest("DELETE", url, nil)

    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

DELETE /unassigned_agreements/{unassigned_agreement_ref}

An Unassigned Agreement can be deleted at anytime as long as it has not yet been assigned an authoriser.

Parameters

Parameter	In	Type	Required	Description
unassigned_agreement_ref	path	string	true	Single value, exact match

Responses

Status	Meaning	Description	Schema
204	No Content	No Content	None

Users

All about the currently authenticated user.

Get user details

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/user \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/user")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/user",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/user", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/user")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/user');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/user"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /user

Example responses

200 Response

{
  "data": {
    "first_name": "Bear",
    "last_name": "Dog",
    "mobile_phone": 39536658,
    "email": "bear@dog.com",
    "account": {
      "name": "Dog Bones Inc",
      "nickname": "dog-bones-inc",
      "abn": "129959040",
      "phone": "0218495033",
      "street_address": "98 Acme Avenue",
      "suburb": "Lead",
      "postcode": "2478"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	GetUserDetailsResponse

Webhooks

List all webhooks

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/webhooks \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/webhooks",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/webhooks", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/webhooks")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/webhooks');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/webhooks"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /webhooks

List all your application's webhook configurations.

Example responses

200 Response

{
  "data": [
    {
      "id": "13bd760e-447f-4225-b801-0777a15da131",
      "url": "https://webhook.site/a9a3033b-90eb-44af-9ba3-29972435d10e",
      "signature_secret": "8fad2f5570e6bf0351728f727c5a8c770dda646adde049b866a7800d59",
      "events": [
        "debit.cleared",
        "credit.cleared"
      ]
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	ListAllWebhooksResponse
404	Not Found	Not Found	None

Response Headers

Status	Header	Type	Format	Description
200	Link	string		Contains pagination link for next page of collection, if next page exists.
200	Per-Page	integer		Contains the current maximum items in collection. Defaults to 25

List deliveries for a webhook

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/webhooks/31918dce-2dc3-405b-8d3c-fd3901b17e9f/deliveries \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/webhooks/31918dce-2dc3-405b-8d3c-fd3901b17e9f/deliveries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/webhooks/31918dce-2dc3-405b-8d3c-fd3901b17e9f/deliveries",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/webhooks/31918dce-2dc3-405b-8d3c-fd3901b17e9f/deliveries", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/webhooks/31918dce-2dc3-405b-8d3c-fd3901b17e9f/deliveries")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/webhooks/31918dce-2dc3-405b-8d3c-fd3901b17e9f/deliveries');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/webhooks/31918dce-2dc3-405b-8d3c-fd3901b17e9f/deliveries"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /webhooks/{webhook_id}/deliveries

NOTE: Webhook deliveries are stored for 7 days.

Parameters

Parameter	In	Type	Required	Description
webhook_id	path	string	true	Single value, exact match
ref	query	string	false	Filter deliveries by ref (`WebhookDelivery.data.ref`), single value, exact match
per_page	query	string	false	Number of results per page, single value, exact match
starting_after	query	string(uuid)	false	Display all webhook deliveries after this webhook delivery offset UUID, single value, exact match
event_type	query	string	false	See (Data schemas) for a list of possible values, single value, exact match
since	query	string(date-time)	false	Display all webhook deliveries after this date. Date/time UTC ISO 8601 format, single value, exact match
response_status_code	query	array[string]	false	Single value / multiple values separated by commas
state	query	array[string]	false	Filter deliveries by state, single value / multiple values separated by commas. See Our delivery promise

Enumerated Values

Parameter	Value
event_type	See (Data schemas)
response_status_code	2xx
response_status_code	4xx
response_status_code	5xx
state	pending
state	completed
state	retrying
state	failed

Example responses

200 Response

{
  "data": [
    {
      "id": "957d40a4-80f5-4dd2-8ada-8242d5ad66c1",
      "event_type": "payout_request.added",
      "state": "completed",
      "response_status_code": 200,
      "created_at": "2021-09-02T02:24:50.000Z",
      "payload_data_summary": [
        {
          "ref": "PR.ct5b"
        }
      ]
    },
    {
      "id": "29bb9835-7c69-4ecb-bf96-197d089d0ec3",
      "event_type": "creditor_debit.scheduled",
      "state": "completed",
      "response_status_code": 200,
      "created_at": "2021-09-02T02:24:50.000Z",
      "payload_data_summary": [
        {
          "ref": "D.hyy9"
        },
        {
          "ref": "D.6st93"
        }
      ]
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	GetWebhookDeliveriesResponse
404	Not Found	Not Found	None

Response Headers

Status	Header	Type	Format	Description
200	Link	string		Contains pagination link for next page of collection, if next page exists.
200	Per-Page	integer		Contains the current maximum items in collection. Defaults to 25

Get a Webhook Delivery

Code samples

curl --request GET \
  --url https://api.nz.sandbox.zepto.money/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("GET", "/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://api.nz.sandbox.zepto.money/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

GET /webhook_deliveries/{id}

Get a single webhook delivery by ID.

Parameters

Parameter	In	Type	Required	Description
id	path	string(UUID)	true	WebhookDelivery ID (`WebhookDelivery.data.id`)

Example responses

200 Response

{
  "data": {
    "id": "957d40a4-80f5-4dd2-8ada-8242d5ad66c1",
    "webhook_id": "13bd760e-447f-4225-b801-0777a15da131",
    "event_type": "payout_request.added",
    "state": "completed",
    "payload": {
      "data": [
        {
          "ref": "PR.ct5b",
          "payout": {
            "amount": 1501,
            "matures_at": "2021-09-02T02:24:49.000Z",
            "description": "Payment from Incoming Test Payment Contact 014209 12345678 (Test Payment)"
          },
          "status": "approved",
          "created_at": "2021-09-02T02:24:49.000Z",
          "credit_ref": "C.p2rt",
          "matures_at": "2021-09-02T02:24:49.000Z",
          "initiator_id": "b50a6e92-a5e1-4175-b560-9e4c9a9bb4b9",
          "responded_at": "2021-09-02T02:24:49.000Z",
          "schedule_ref": null,
          "authoriser_id": "780f186c-80fd-42b9-97d5-650d99a0bc99",
          "status_reason": null,
          "your_bank_account_id": "b50a6e92-a5e1-4175-b560-9e4c9a9bb4b9",
          "authoriser_contact_id": "590be205-6bae-4070-a9af-eb50d514cec5",
          "authoriser_contact_initiated": true
        },
        {
          "event": {
            "at": "2021-09-02T02:24:49.000Z",
            "who": {
              "account_id": "20f4e3f8-2efc-48a9-920b-541515f1c9e3",
              "account_type": "Account",
              "bank_account_id": "b50a6e92-a5e1-4175-b560-9e4c9a9bb4b9",
              "bank_account_type": "BankAccount"
            },
            "type": "payment_request.added"
          }
        }
      ]
    }
  },
  "response_status_code": 200,
  "created_at": "2021-09-02T02:24:50.000Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	GetAWebhookDeliveryResponse
404	Not Found	Not Found	None

Resend a Webhook Delivery

Code samples

curl --request POST \
  --url https://api.nz.sandbox.zepto.money/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f/redeliver \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access-token}'

require 'uri'
require 'net/http'

url = URI("https://api.nz.sandbox.zepto.money/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f/redeliver")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'

response = http.request(request)
puts response.read_body

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "api.nz.sandbox.zepto.money",
  "port": null,
  "path": "/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f/redeliver",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("api.nz.sandbox.zepto.money")

headers = {
    'accept': "application/json",
    'authorization': "Bearer {access-token}"
    }

conn.request("POST", "/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f/redeliver", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.post("https://api.nz.sandbox.zepto.money/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f/redeliver")
  .header("accept", "application/json")
  .header("authorization", "Bearer {access-token}")
  .asString();

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.nz.sandbox.zepto.money/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f/redeliver');
$request->setRequestMethod('POST');
$request->setHeaders(array(
  'authorization' => 'Bearer {access-token}',
  'accept' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://api.nz.sandbox.zepto.money/webhook_deliveries/31918dce-2dc3-405b-8d3c-fd3901b17e9f/redeliver"

    req, _ := http.NewRequest("POST", url, nil)

    req.Header.Add("accept", "application/json")
    req.Header.Add("authorization", "Bearer {access-token}")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

POST /webhook_deliveries/{id}/redeliver

Use this endpoint to resend a failed webhook delivery.

Parameters

Parameter	In	Type	Required	Description
id	path	string(UUID)	true	WebhookDelivery ID (`WebhookDelivery.data.id`)

Example responses

202 Response

{
  "data": {
    "id": "957d40a4-80f5-4dd2-8ada-8242d5ad66c1",
    "webhook_id": "13bd760e-447f-4225-b801-0777a15da131",
    "state": "pending"
  }
}

Responses

Status	Meaning	Description	Schema
202	Accepted	Accepted	RedeliverAWebhookDeliveryResponse

Schemas

CreateKYCTrustedAgreementRequest

{
  "authoriser": {
    "name": "John Doe",
    "email": "john@supplies.com",
    "phone": "02112345678",
    "bank_account": {
      "account_number": "021234693049678"
    },
    "metadata": {
      "some_data": "stored on the authoriser contact"
    }
  },
  "terms": {
    "per_payout": {
      "min_amount": null,
      "max_amount": null
    },
    "per_frequency": {
      "days": null,
      "max_amount": null
    }
  },
  "metadata": {
    "your_customer_uid": "6041475e-c5b4-4abe-a8e9-e2c3620a0a3e",
    "some_other_data": "stored on the agreement"
  }
}

Properties

Create a KYC Trusted Agreement (request)

Name	Type	Required	Description
authoriser	AddAnAnyoneContactRequest	true	No description
terms	Terms	true	No description
metadata	Metadata	false	No description

CreateKYCTrustedAgreementResponse

{
  "data": {
    "ref": "A.ci",
    "initiator_id": "6a0a05c4-8ad9-495d-bcf9-66a7d0046909",
    "authoriser_id": "9fa1be8d-40fb-4bf6-9743-577a1d5a3775",
    "contact_id": "bea8107a-a5b5-4719-92ec-8389ad7aa619",
    "bank_account_id": "91dbef6d-b596-4387-a36c-5a8497822b97",
    "status": "accepted",
    "responded_at": "2018-04-30T04:43:52Z",
    "created_at": "2018-04-30T04:43:52Z",
    "terms": {
      "per_payout": {
        "max_amount": null,
        "min_amount": null
      },
      "per_frequency": {
        "days": null,
        "max_amount": null
      }
    },
    "metadata": {
      "your_customer_uid": "6041475e-c5b4-4abe-a8e9-e2c3620a0a3e",
      "some_other_data": "stored on the agreement"
    }
  }
}

Properties

Create a KYC Trusted Agreement (response)

Name	Type	Required	Description
data	object	true	No description

GetAgreementResponse

{
  "data": {
    "ref": "A.2",
    "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
    "authoriser_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
    "contact_id": "0d290763-bd5a-4b4d-a8ce-06c64c4a697b",
    "bank_account_id": "fb9381ec-22af-47fd-8998-804f947aaca3",
    "status": "approved",
    "status_reason": null,
    "responded_at": "2017-03-20T02:13:11Z",
    "created_at": "2017-03-20T00:53:27Z",
    "terms": {
      "per_payout": {
        "max_amount": 10000,
        "min_amount": 1
      },
      "per_frequency": {
        "days": 7,
        "max_amount": 1000000
      }
    }
  }
}

Properties

Get an Agreement (response)

Name	Type	Required	Description
data	object	true	No description
» ref	string	true	The Agreement reference (Min: 3 - Max: 18)
» initiator_id	string(uuid)	true	Your Zepto account ID
» authoriser_id	string(uuid)	true	The authoriser's account ID (AnyoneAccount)
» contact_id	string(uuid)	true	The contact ID representing the authoriser within Zepto
» bank_account_id	string(uuid)	true	The authoriser's bank account ID
» status	string	true	The status of the Agreement
» status_reason	string	true	The reason the agreement was cancelled. This is a free text field.
» responded_at	string(date-time)	true	The date-time when the Agreement status changed
» created_at	string(date-time)	true	The date-time when the Agreement was created
» terms	Terms	true	No description
» metadata	object	false	Your custom keyed data

Enumerated Values

Property	Value
status	proposed
status	accepted
status	cancelled
status	declined
status	expended

ListOutgoingAgreementsResponse

{
  "data": [
    {
      "ref": "A.4",
      "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
      "authoriser_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
      "contact_id": "a80ac411-c8fb-45c0-9557-607c54649907",
      "bank_account_id": "fa80ac411-c8fb-45c0-9557-607c54649907",
      "status": "proposed",
      "status_reason": null,
      "responded_at": null,
      "created_at": "2017-03-20T00:53:27Z",
      "terms": {
        "per_payout": {
          "max_amount": 10000,
          "min_amount": 1
        },
        "per_frequency": {
          "days": 7,
          "max_amount": 1000000
        }
      }
    },
    {
      "ref": "A.3",
      "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
      "authoriser_id": "56df206a-aaff-471a-b075-11882bc8906a",
      "contact_id": "a80ac411-c8fb-45c0-9557-607c54649907",
      "bank_account_id": "fa80ac411-c8fb-45c0-9557-607c54649907",
      "status": "proposed",
      "status_reason": null,
      "responded_at": null,
      "created_at": "2017-03-16T22:51:48Z",
      "terms": {
        "per_payout": {
          "max_amount": 5000,
          "min_amount": 0
        },
        "per_frequency": {
          "days": "1",
          "max_amount": 10000
        }
      }
    }
  ]
}

Properties

List outgoing Agreements (response)

Name	Type	Required	Description
data	[object]	true	No description

ListAllBankAccountsResponse

{
  "data": [
    {
      "id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
      "bank_name": "Bank of New Zealand",
      "account_number": "021234693049678",
      "status": "active",
      "title": "NZ.020100.3993013'",
      "available_balance": null
    },
    {
      "id": "56df206a-aaff-471a-b075-11882bc8906a",
      "bank_name": "Bank of New Zealand",
      "account_number": "0212341059493024",
      "status": "active",
      "title": "Trust Account",
      "available_balance": null
    }
  ]
}

Properties

List all Bank Accounts (response)

Name	Type	Required	Description
data	[object]	true	No description

Terms

{
  "per_payout": {
    "min_amount": 0,
    "max_amount": 10000
  },
  "per_frequency": {
    "days": 7,
    "max_amount": 1000000
  }
}

Properties

Agreement terms

Name	Type	Required	Description
per_payout	PerPayout	true	No description
per_frequency	PerFrequency	true	No description

PerPayout

{
  "min_amount": 0,
  "max_amount": 10000
}

Properties

Per payout terms

Name	Type	Required	Description
min_amount	integer	true	Minimum amount in cents a Payment Request can be in order to be auto-approved. Specify `null` for no limit.
max_amount	integer	true	Maximum amount in cents a Payment Request can be in order to be auto-approved. Specify `null` for no limit.

PerFrequency

{
  "days": 7,
  "max_amount": 1000000
}

Properties

Per frequency terms

Name	Type	Required	Description
days	integer	true	Amount of days to apply against the frequency. Specify `null` for no limit.
max_amount	integer	true	Maximum amount in cents the total of all PRs can be for the duration of the frequency. Specify `null` for no limit.

ListAllContactsResponse

{
  "data": [
    {
      "id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
      "name": "Outstanding Tours Pty Ltd",
      "email": "accounts@outstandingtours.com.au",
      "phone": "0226644022",
      "type": "Zepto account",
      "bank_account": {
        "id": "095c5ab7-7fa8-40fd-b317-cddbbf4c8fbc",
        "account_number": "021234671453378",
        "bank_name": "Bank of New Zealand",
        "state": "active",
        "blocks": {
          "debits_blocked": false,
          "credits_blocked": false
        }
      }
    },
    {
      "id": "49935c67-c5df-4f00-99f4-1413c18a89a0",
      "name": "Adventure Dudes Pty Ltd",
      "email": "accounts@adventuredudes.com.au",
      "phone": "+64276143146",
      "type": "Zepto account",
      "bank_account": {
        "id": "861ff8e4-7acf-4897-9e53-e7c5ae5f7cc0",
        "account_number": "021234471453444",
        "bank_name": "Bank of New Zealand",
        "state": "active",
        "blocks": {
          "debits_blocked": false,
          "credits_blocked": false
        }
      }
    },
    {
      "id": "eb3266f9-e172-4b6c-b802-fe5ac4d3250a",
      "name": "Surfing World Pty Ltd",
      "email": "accounts@surfingworld.com.au",
      "phone": "0270345344",
      "type": "Zepto account",
      "bank_account": {
        "id": null,
        "account_number": null,
        "bank_name": null,
        "state": "disabled",
        "blocks": {
          "debits_blocked": false,
          "credits_blocked": false
        }
      }
    },
    {
      "id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
      "name": "Hunter Thompson",
      "email": "hunter@batcountry.com",
      "phone": "+64211234567",
      "type": "anyone",
      "bank_account": {
        "id": "55afddde-4296-4daf-8e49-7ba481ef9608",
        "account_number": "021234693049678",
        "bank_name": "Bank of New Zealand",
        "state": "pending_verification",
        "blocks": {
          "debits_blocked": false,
          "credits_blocked": false
        }
      }
    }
  ]
}

Properties

List all Contacts (response)

Name	Type	Required	Description
data	[object]	true	No description

AddAnAnyoneContactRequest

{
  "name": "Hunter Thompson",
  "email": "hunter@batcountry.com",
  "phone": "+64211234567",
  "account_number": "021234693049678",
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Properties

Add a Contact (request)

Name	Type	Required	Description
name	string	true	The name of the Contact (140 max. characters)
email	string	true	The email of the Contact (256 max. characters)
phone	string	true	The phone of the Contact. Must be a valid New Zealand mobile number in ITU-T E.164 or national format
account_number	string	true	The bank account number of the Contact (15-16 characters)
metadata	Metadata	false	No description

AddAnAnyoneContactResponse

{
  "data": {
    "id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
    "name": "Hunter Thompson",
    "email": "hunter@batcountry.com",
    "phone": "+64211234567",
    "type": "anyone",
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    },
    "bank_account": {
      "id": "55afddde-4296-4daf-8e49-7ba481ef9608",
      "account_number": "021234693049678",
      "bank_name": "Bank of New Zealand",
      "state": "active",
      "blocks": {
        "debits_blocked": false,
        "credits_blocked": false
      }
    }
  }
}

Properties

Add a Contact (response)

Name	Type	Required	Description
data	object	true	No description

GetAContactResponse

{
  "data": {
    "id": "55afddde-4296-4daf-8e49-7ba481ef9608",
    "ref": "CNT.123",
    "name": "Outstanding Tours Pty Ltd",
    "email": "accounts@outstandingtours.com.au",
    "phone": "0211234567",
    "type": "anyone",
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    },
    "bank_account": {
      "id": "fcabeacb-2ef6-4b27-ba19-4f6fa0d57dcb",
      "account_number": "021234693049678",
      "bank_name": "Bank of New Zealand",
      "state": "active",
      "blocks": {
        "debits_blocked": false,
        "credits_blocked": false
      }
    },
    "anyone_account": {
      "id": "31a05f81-25a2-4085-92ef-0d16d0263bff"
    }
  }
}

Properties

Get a Contact (response)

Name	Type	Required	Description
data	object	true	No description
» id	string(uuid)	true	The Contact ID
» ref	string(string)	true	The Contact ref
» name	string	true	The Contact name (Min: 3 - Max: 140)
» email	string(email)	true	The Contact email (Min: 6 - Max: 256)
» phone	string	true	The Contact phone (ITU E.123 or national format)
» metadata	Metadata	true	No description
» bank_account	object	true	No description
»» id	string(uuid)	false	The Bank Account ID
»» account_number	string	false	The Bank Account number (Min: 5 - Max: 9)
»» state	string	false	The bank account state
»» blocks	object	false	No description
»»» debits_blocked	boolean	false	Used by Zepto admins. Defines whether the bank account is blocked from being debited
»»» credits_blocked	boolean	false	Used by Zepto admins. Defined Whether this bank account is blocked from being credited
»» anyone_account	object	true	No description

Enumerated Values

Property	Value
state	active
state	removed

UpdateAContactRequest

{
  "name": "My very own alias",
  "email": "updated@email.com",
  "phone": "0226644022",
  "account_number": "200111930276531",
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Properties

Update a Contact (request)

Name	Type	Required	Description
name	string	false	The name of the Contact
email	string	false	The email of the Contact
phone	string	false	The phone number of the Contact
account_number	string	false	The bank account number of the Contact
metadata	Metadata	false	No description

UpdateAContactResponse

{
  "data": {
    "id": "fcabeacb-2ef6-4b27-ba19-4f6fa0d57dcb",
    "name": "My very own alias",
    "email": "updated@email.com",
    "phone": "0226644022",
    "type": "anyone",
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    },
    "bank_account": {
      "id": "55afddde-4296-4daf-8e49-7ba481ef9608",
      "account_number": "200111930276531",
      "bank_name": "Zepto SANDBOX Bank",
      "state": "active",
      "blocks": {
        "debits_blocked": false,
        "credits_blocked": false
      }
    },
    "anyone_account": {
      "id": "63232c0a-a783-4ae9-ae73-f0974fe1e345"
    }
  }
}

Properties

Update a Contact (response)

Name	Type	Required	Description
data	object	true	No description

MakeAPaymentRequest

{
  "description": "The SuperPackage",
  "matures_at": "2021-06-13T00:00:00Z",
  "your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
  "payouts": [
    {
      "amount": 30000,
      "description": "A tandem skydive jump SB23094",
      "recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
      "metadata": {
        "invoice_ref": "BILL-0001",
        "invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
        "custom_key": "Custom string",
        "another_custom_key": "Maybe a URL"
      }
    }
  ],
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Properties

Make a Payment (request)

Name	Type	Required	Description
description	string	true	User description. Only visible to the payer
matures_at	string(date-time)	true	Date & time in UTC ISO8601 the Payment should be processed. (Can not be earlier than the start of current day in NZST)
your_bank_account_id	string	true	Specify where we should take the funds for this transaction. If omitted, your primary bank account will be used.
payouts	[Payout]	true	One Payout object only
metadata	Metadata	false	No description

Payout

{
  "amount": 30000,
  "description": "A tandem skydive jump SB23094",
  "recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
  "metadata": null
}

Properties

Payout

Name	Type	Required	Description
amount	integer	true	Amount in cents to pay the recipient
description	string	true	Description that both the payer and recipient can see. For Direct Entry payments, the payout recipient will see the first 9 characters of this description.
recipient_contact_id	string	true	Contact to pay (`Contact.data.id`)
metadata	Metadata	false	Use for your custom data and certain Zepto customisations. Stored against generated transactions and included in associated webhook payloads.

VoidAPayoutRequest

{
  "details": "Incorrect recipient"
}

Properties

Void a Payout (request)

Name	Type	Required	Description
details	string	false	Optional details about why the payout has been voided

Metadata

{
  "custom_key": "Custom string",
  "another_custom_key": "Maybe a URL"
}

Properties

Metadata

None

MakeAPaymentResponse

{
  "data": {
    "ref": "PB.1",
    "your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
    "payouts": [
      {
        "ref": "D.1",
        "recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
        "batch_description": "The SuperPackage",
        "matures_at": "2016-09-13T23:50:44Z",
        "created_at": "2016-09-10T23:50:44Z",
        "status": "maturing",
        "amount": 30000,
        "description": "A tandem skydive jump SB23094",
        "from_id": "83623359-e86e-440c-9780-432a3bc3626f",
        "to_id": "21066764-c103-4e7f-b436-4cee7db5f400",
        "metadata": {
          "invoice_ref": "BILL-0001",
          "invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
          "custom_key": "Custom string",
          "another_custom_key": "Maybe a URL"
        }
      }
    ],
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Properties

Make a Payment (response)

Name	Type	Required	Description
data	object	true	No description

ListAllPaymentsResponse

{
  "data": [
    {
      "ref": "PB.1",
      "your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
      "payouts": [
        {
          "ref": "D.1",
          "recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
          "batch_description": "This description is only available to the payer",
          "matures_at": "2016-09-13T23:50:44Z",
          "created_at": "2016-09-10T23:50:44Z",
          "status": "maturing",
          "amount": 30000,
          "description": "The recipient will see this description",
          "from_id": "83623359-e86e-440c-9780-432a3bc3626f",
          "to_id": "21066764-c103-4e7f-b436-4cee7db5f400",
          "metadata": {
            "invoice_ref": "BILL-0001",
            "invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
            "custom_key": "Custom string",
            "another_custom_key": "Maybe a URL"
          }
        },
        {
          "ref": "D.2",
          "recipient_contact_id": "dc6f1e60-3803-43ca-a200-7d641816f57f",
          "batch_description": "This description is only available to the payer",
          "matures_at": "2016-09-13T23:50:44Z",
          "created_at": "2016-09-10T23:50:44Z",
          "status": "maturing",
          "amount": 30000,
          "description": "The recipient will see this description",
          "from_id": "48b89364-1577-4c81-ba02-96705895d457",
          "to_id": "f989d9cd-87fc-4c73-b0a4-1eb0e8768d3b"
        }
      ],
      "metadata": {
        "custom_key": "Custom string",
        "another_custom_key": "Maybe a URL"
      }
    }
  ]
}

Properties

List all Payments (response)

Name	Type	Required	Description
data	[object]	true	No description

GetAPaymentResponse

{
  "data": {
    "ref": "PB.1",
    "your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
    "payouts": [
      {
        "ref": "D.1",
        "recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
        "batch_description": "The SuperPackage",
        "matures_at": "2016-09-13T23:50:44Z",
        "created_at": "2016-09-10T23:50:44",
        "status": "maturing",
        "amount": 30000,
        "description": "A tandem skydive jump SB23094",
        "from_id": "83623359-e86e-440c-9780-432a3bc3626f",
        "to_id": "21066764-c103-4e7f-b436-4cee7db5f400",
        "metadata": {
          "invoice_ref": "BILL-0001",
          "invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
          "custom_key": "Custom string",
          "another_custom_key": "Maybe a URL"
        }
      }
    ],
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Properties

Get a Payment (response)

Name	Type	Required	Description
data	object	true	No description

MakeAPaymentRequestRequest

{
  "description": "Visible to both initiator and authoriser",
  "matures_at": "2016-12-19T02:10:56.000Z",
  "amount": 99000,
  "authoriser_contact_id": "de86472c-c027-4735-a6a7-234366a27fc7",
  "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Properties

Make a Payment Request (request)

Name	Type	Required	Description
description	string	true	Description visible to the initiator (payee). The first 9 characters supplied will be visible to the authoriser (payer)
matures_at	string(date-time)	true	Date & time in UTC ISO8601 that the Payment will be processed if the request is approved. (If the request is approved after this point in time, it will be processed straight away)
amount	integer	true	Amount in cents to pay the initiator (Min: 1 - Max: 99999999999)
authoriser_contact_id	string	true	The Contact the payment will be requested from (`Contact.data.id`)
your_bank_account_id	string(uuid)	false	Specify where we should settle the funds for this transaction. If omitted, your primary bank account will be used.
metadata	object	false	Use for your custom data and certain Zepto customisations. Stored against generated transactions and included in associated webhook payloads.

MakeAPaymentRequestResponse

{
  "data": {
    "ref": "PR.39p1",
    "initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
    "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
    "authoriser_id": "970e4526-67d9-4ed9-b554-f5cf390ab775",
    "authoriser_contact_id": "de86472c-c027-4735-a6a7-234366a27fc7",
    "contact_initiated": false,
    "schedule_ref": null,
    "status": "pending_approval",
    "status_reason": null,
    "matures_at": "2021-12-25T00:00:00Z",
    "responded_at": null,
    "created_at": "2021-12-19T02:10:56Z",
    "credit_ref": null,
    "payout": {
      "amount": 99000,
      "description": "Premium Package for 4",
      "matures_at": "2021-12-25T00:00:00Z"
    },
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Properties

Make a Payment Request (response)

Name	Type	Required	Description
data	object	true	No description
» ref	string	true	The Payment Request reference (PR.*) (Min: 4 - Max: 8)
» initiator_id	string(uuid)	true	Your bank account ID where the funds will settle (Min: 36 - Max: 36)
» your_bank_account_id	string(uuid)	true	Your bank account ID where the funds will settle (alias of `initiator_id`) (Min: 36 - Max: 36)
» authoriser_id	string(uuid)	true	The debtor's bank account ID (Min: 36 - Max: 36)
» authoriser_contact_id	string(uuid)	true	The contact ID representing the debtor within Zepto (Min: 36 - Max: 36)
» contact_initiated	boolean	true	Initiated by Contact or Merchant
» schedule_ref	string	true	The schedule that generated the Payment request if applicable (Min: 0 - Max: 8)
» status	string	true	The status of the Payment Request
» status_reason	string	true	Only used when the `status` is `declined` due to prechecking. (Min: 0 - Max: 280)
» matures_at	string(date-time)	true	The date-time when the Payment Request is up for processing (Min: 20 - Max: 20)
» responded_at	string(date-time)	true	The date-time when the Payment Request status changed (Min: 0 - Max: 20)
» created_at	string(date-time)	true	The date-time when the Payment Request was created (Min: 20 - Max: 20)
» credit_ref	string	true	The resulting credit entry reference (available once approved) (Min: 4 - Max: 8)
» payout	object	true	No description
»» amount	integer	true	Amount in cents (Min: 1 - Max: 99999999999)
»» description	string	true	Payment Request description (Min: 1 - Max: 280)
»» matures_at	string(date-time)	true	The date-time when the Payment Request is up for processing (Min: 20 - Max: 20)
» metadata	object	false	Your custom keyed data

Enumerated Values

Property	Value
status	pending_approval
status	unverified
status	approved
status	declined
status	cancelled
status_reason	The balance of the nominated bank account for this Payment Request is not available.
status_reason	The nominated bank account for this Payment Request has insufficient funds.

MakeAPaymentRequestWithNoAgreementResponse

{
  "errors": "Authoriser contact (de86472c-c027-4735-a6a7-234366a27fc7) is not a Zepto account holder and therefore must have a valid agreement in place before a Payment Request can be issued."
}

Properties

Make a Payment Request to an Anyone Contact with no valid Agreement (response)

Name	Type	Required	Description
errors	string	true	No description

GetAPaymentRequestResponse

{
  "data": {
    "ref": "PR.88me",
    "initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
    "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
    "authoriser_id": "970e4526-67d9-4ed9-b554-f5cf390ab775",
    "authoriser_contact_id": "de86472c-c027-4735-a6a7-234366a27fc7",
    "contact_initiated": false,
    "schedule_ref": null,
    "status": "approved",
    "status_reason": null,
    "matures_at": "2021-11-25T00:00:00Z",
    "responded_at": "2021-11-19T02:38:04Z",
    "created_at": "2021-11-19T02:10:56Z",
    "credit_ref": "C.b6tf",
    "payout": {
      "amount": 1200,
      "description": "Xbox Live subscription",
      "matures_at": "2021-11-25T00:00:00Z"
    },
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Properties

Get a Payment Request (response)

Name	Type	Required	Description
data	object	true	No description
» ref	string	true	The Payment Request reference (PR.*) (Min: 4 - Max: 8)
» initiator_id	string(uuid)	true	Your bank account ID where the funds will settle (Min: 36 - Max: 36)
» your_bank_account_id	string(uuid)	true	Your bank account ID where the funds will settle (alias of `initiator_id`) (Min: 36 - Max: 36)
» authoriser_id	string(uuid)	true	The debtor's bank account ID (Min: 36 - Max: 36)
» authoriser_contact_id	string(uuid)	true	The contact ID representing the debtor within Zepto (Min: 36 - Max: 36)
» schedule_ref	string	true	The schedule that generated the Payment request if applicable (Min: 0 - Max: 8)
» status	string	true	The status of the Payment Request
» status_reason	string	true	Only used when the `status` is `declined` due to prechecking. (Min: 0 - Max: 280)
» matures_at	string(date-time)	true	The date-time when the Payment Request is up for processing (Min: 20 - Max: 20)
» responded_at	string(date-time)	true	The date-time when the Payment Request status changed (Min: 0 - Max: 20)
» created_at	string(date-time)	true	The date-time when the Payment Request was created (Min: 20 - Max: 20)
» credit_ref	string	false	The resulting credit entry reference (available once approved) (Min: 4 - Max: 8)
» payout	object	true	No description
»» amount	integer	true	Amount in cents (Min: 1 - Max: 99999999999)
»» description	string	true	Payment Request description (Min: 1 - Max: 280)
»» matures_at	string(date-time)	true	The date-time when the Payment Request is up for processing (Min: 20 - Max: 20)
» metadata	object	false	Your custom keyed data

Enumerated Values

Property	Value
status	pending_approval
status	unverified
status	approved
status	declined
status	cancelled
status_reason	The balance of the nominated bank account for this Payment Request is not available.
status_reason	The nominated bank account for this Payment Request has insufficient funds.

ListPaymentRequestCollectionsResponse

{
  "data": [
    {
      "ref": "PR.84t6",
      "initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
      "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
      "authoriser_id": "de86472c-c027-4735-a6a7-234366a27fc7",
      "authoriser_contact_id": "fb6a9252-3818-44dc-b5aa-2195391a746f",
      "contact_initiated": false,
      "schedule_ref": "PRS.89t3",
      "status": "approved",
      "status_reason": null,
      "matures_at": "2021-07-18T02:10:00Z",
      "responded_at": "2021-07-18T02:10:00Z",
      "created_at": "2021-07-18T02:10:00Z",
      "credit_ref": "C.6gr7",
      "payout": {
        "amount": 4999,
        "description": "Subscription Payment",
        "matures_at": "2021-07-18T02:10:00Z"
      }
    },
    {
      "ref": "PR.45h7",
      "initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
      "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
      "authoriser_id": "de86472c-c027-4735-a6a7-234366a27fc7",
      "authoriser_contact_id": "fb6a9252-3818-44dc-b5aa-2195391a746f",
      "contact_initiated": false,
      "schedule_ref": null,
      "status": "pending_approval",
      "status_reason": null,
      "matures_at": "2021-03-09T16:58:00Z",
      "responded_at": null,
      "created_at": "2021-03-09T16:58:00Z",
      "credit_ref": null,
      "payout": {
        "amount": 3000,
        "description": "Membership fees",
        "matures_at": "2021-03-09T16:58:00Z"
      }
    }
  ]
}

Properties

List Collections (response)

Name	Type	Required	Description
data	[object]	true	No description
» ref	string	true	The Payment Reference reference (PR.*)
» initiator_id	string(uuid)	true	Your bank account ID where the funds will settle
» your_bank_account_id	string(uuid)	true	Your bank account ID where the funds will settle (alias of `initiator_id`)
» authoriser_id	string(uuid)	true	The debtor's bank account ID
» authoriser_contact_id	string(uuid)	true	The contact ID representing the debtor within Zepto
» contact_initiated	boolean	true	Initiated by Contact or Merchant
» schedule_ref	string	true	The schedule that generated the Payment request if applicable
» status	string	true	The status of the Payment Request
» status_reason	string	true	Only used when the `status` is `declined` due to prechecking.
» matures_at	string(date-time)	true	The date-time when the Payment Request is up for processing
» responded_at	string(date-time)	true	The date-time when the Payment Request status changed
» created_at	string(date-time)	true	The date-time when the Payment Request was created
» credit_ref	string	true	The resulting credit entry reference (available once approved)
» payout	object	true	No description
»» amount	integer	true	Amount in cents (Min: 1 - Max: 99999999999)
»» description	string	true	Payment Request description
»» matures_at	string(date-time)	true	The date-time when the Payment Request is up for processing
» metadata	[object]	false	Your custom keyed data

Enumerated Values

Property	Value
status	pending_approval
status	unverified
status	approved
status	declined
status	cancelled
status_reason	The balance of the nominated bank account for this Payment Request is not available.
status_reason	The nominated bank account for this Payment Request has insufficient funds.

IssueARefundRequest

{
  "amount": 500,
  "reason": "Because reason",
  "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Properties

Issue a Refund (request)

Name	Type	Required	Description
amount	integer	true	Amount in cents refund (Min: 1 - Max: 99999999999)
reason	string	false	Reason for the refund. First 9 characters are visible to both parties.
your_bank_account_id	string(uuid)	false	Specify where we should take the funds for this transaction. If omitted, your primary bank account will be used.
metadata	Metadata	false	No description

IssueARefundResponse

{
  "data": {
    "ref": "PRF.7f4",
    "for_ref": "C.1gf22",
    "debit_ref": "D.63hgf",
    "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
    "created_at": "2021-06-01T07:20:24Z",
    "amount": 500,
    "reason": "Subscription refund",
    "contacts": {
      "source_contact_id": "194b0237-6c2c-4705-b4fb-308274b14eda",
      "target_contact_id": "3694ff53-32ea-40ae-8392-821e48d7bd5a"
    },
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Properties

Issue a Refund (response)

Name	Type	Required	Description
data	object	true	No description
» ref	string(uuid)	true	The Refund request reference (PRF.*) (Min: 5 - Max: 9)
» for_ref	string	true	The associated credit reference (C.*)
» debit_ref	string	true	The associated debit reference (C.*)
» your_bank_account_id	string	true	The source bank/float account (UUID)
» created_at	string(date-time)	true	The date-time when the Payment Request was created
» amount	integer	true	The amount value provided (Min: 1 - Max: 99999999999)
» channels	array	false	The requested payment channel(s) to be used, in order. (direct_entry)
» reason	string	true	Reason for the refund

ListOutgoingRefundsResponse

{
  "data": [
    {
      "ref": "PRF.2",
      "for_ref": "C.5",
      "debit_ref": "D.5a",
      "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
      "created_at": "2017-05-09T04:45:26Z",
      "amount": 5,
      "reason": "Because reason",
      "metadata": {
        "custom_key": "Custom string",
        "another_custom_key": "Maybe a URL"
      }
    }
  ]
}

Properties

List outgoing Refunds (response)

Name	Type	Required	Description
data	[object]	true	No description

RetrieveARefundResponse

{
  "data": {
    "ref": "PRF.1",
    "for_ref": "C.59",
    "debit_ref": "D.hi",
    "your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
    "created_at": "2017-05-08T07:20:24Z",
    "amount": 500,
    "reason": "Because reason",
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Properties

Retrieve a Refund (response)

Name	Type	Required	Description
data	object	true	No description

RetryPayoutResponse

{
  "data": {
    "ref": "C.2",
    "parent_ref": "PR.039a",
    "type": "credit",
    "category": "payout",
    "created_at": "2016-12-05T23:15:00Z",
    "matures_at": "2016-12-06T23:15:00Z",
    "cleared_at": null,
    "bank_ref": null,
    "status": "maturing",
    "status_changed_at": "2016-12-05T23:15:00Z",
    "party_contact_id": "33c6e31d3-1dc1-448b-9512-0320bc44fdcf",
    "party_name": "Price and Sons",
    "party_nickname": "price-and-sons-2",
    "party_bank_ref": null,
    "description": "Money for jam",
    "amount": 1
  }
}

Properties

Retry a payout (response)

Name	Type	Required	Description
data	[object]	true	No description

ListAllTransactionsResponse

{
  "data": [
    {
      "ref": "D.3",
      "parent_ref": null,
      "type": "debit",
      "category": "payout_refund",
      "created_at": "2021-04-07T23:15:00Z",
      "matures_at": "2021-04-07T23:15:00Z",
      "cleared_at": "2021-04-10T23:15:00Z",
      "bank_ref": "DT.9a",
      "status": "cleared",
      "status_changed_at": "2021-04-10T23:15:00Z",
      "party_contact_id": "31354923-b1e9-4d65-b03c-415ead89cbf3",
      "party_name": "Sanford-Rees",
      "party_nickname": null,
      "party_bank_ref": "CT.11",
      "description": null,
      "amount": 20000,
      "bank_account_id": "56df206a-aaff-471a-b075-11882bc8906a",
      "channels": [
        "direct_entry"
      ],
      "current_channel": "direct_entry"
    },
    {
      "ref": "D.2",
      "parent_ref": "PB.2",
      "type": "debit",
      "category": "payout",
      "created_at": "2016-12-06T23:15:00Z",
      "matures_at": "2016-12-09T23:15:00Z",
      "cleared_at": null,
      "bank_ref": null,
      "status": "maturing",
      "status_changed_at": "2016-12-06T23:15:00Z",
      "party_contact_id": "3c6e31d3-1dc1-448b-9512-0320bc44fdcf",
      "party_name": "Gutmann-Schmidt",
      "party_nickname": null,
      "party_bank_ref": null,
      "description": "Batteries for hire",
      "amount": 2949299,
      "bank_account_id": "56df206a-aaff-471a-b075-11882bc8906a",
      "channels": [
        "direct_entry"
      ],
      "current_channel": "direct_entry"
    },
    {
      "ref": "C.2",
      "parent_ref": "PB.s0z",
      "type": "credit",
      "category": "payout",
      "created_at": "2016-12-05T23:15:00Z",
      "matures_at": "2016-12-06T23:15:00Z",
      "cleared_at": "2016-12-09T23:15:00Z",
      "bank_ref": "CT.1",
      "status": "cleared",
      "status_changed_at": "2016-12-09T23:15:00Z",
      "party_contact_id": "33c6e31d3-1dc1-448b-9512-0320bc44fdcf",
      "party_name": "Price and Sons",
      "party_nickname": "price-and-sons-2",
      "party_bank_ref": null,
      "description": "Online purchase",
      "amount": 19999,
      "bank_account_id": "c2e329ae-606f-4311-a9ab-a751baa1915c",
      "channels": [
        "direct_entry"
      ],
      "current_channel": "direct_entry",
      "metadata": {
        "customer_id": "xur4492",
        "product_ref": "TSXL392110x"
      }
    }
  ]
}

Properties

List all transactions (response)

Name	Type	Required	Description
data	[TransactionResponse]	true	No description

TransactionResponse

{
  "ref": "C.2",
  "parent_ref": "PB.s0z",
  "type": "credit",
  "category": "payout",
  "created_at": "2016-12-05T23:15:00Z",
  "matures_at": "2016-12-06T23:15:00Z",
  "cleared_at": "2016-12-09T23:15:00Z",
  "bank_ref": "CT.1",
  "status": "cleared",
  "status_changed_at": "2016-12-09T23:15:00Z",
  "party_contact_id": "33c6e31d3-1dc1-448b-9512-0320bc44fdcf",
  "party_name": "Price and Sons",
  "party_nickname": "price-and-sons-2",
  "party_bank_ref": null,
  "description": "Online purchase",
  "amount": 19999,
  "bank_account_id": "c2e329ae-606f-4311-a9ab-a751baa1915c",
  "channels": [
    "direct_entry"
  ],
  "current_channel": "direct_entry",
  "metadata": {
    "customer_id": "xur4492",
    "product_ref": "TSXL392110x"
  }
}

Properties

A transaction (response)

Name	Type	Required	Description
ref	string	true	The ref of the transaction (`C.` or `D.`)
parent_ref	string	true	The ref of the parent of this transaction
type	string	true	The type of the transaction
category	string	true	The category of the transaction
created_at	string(date-time)	true	When the transaction was created
matures_at	string(date-time)	false	When the transaction was processed
cleared_at	string(date-time)	true	When the transaction was cleared
bank_ref	string	true	The ref that is sent to the bank
status	string	true	The status of the transaction (see Transactions/Lifecycle for more info)
status_changed_at	string	true	When the status was last changed
failure_details	string	false	Details if a failure occured
failure	Failure	false	No description
party_contact_id	string(uuid)	true	The transaction party's contact ID
party_name	string	true	The transaction party's name
party_nickname	string	true	The transaction party's nickname
party_bank_ref	string	true	The transaction party's bank ref
description	string	true	The transaction's description
amount	integer	true	Amount in cents (Min: 1 - Max: 99999999999)
bank_account_id	string(uuid)	true	The bank account ID of this transaction
channels	array	true	Which payment channels this transaction can use (only `direct_entry` in NZ)
current_channel	string	true	The current payment channel in use for this transaction
reversal_details	object	false	Reversal details (see Payments/Lifecyle for more info)
» source_debit_ref	string	false	The source debit ref of the reversal
» source_credit_failure	Failure	false	No description
metadata	Metadata	false	No description

Enumerated Values

Property	Value
type	credit
type	debit
category	payout
category	payout_refund
category	invoice
category	payout_reversal
category	transfer
category	recovery
status	maturing
status	matured
status	preprecessing
status	processing
status	clearing
status	cleared
status	rejected
status	returned
status	voided
status	pending_verification
status	paused
current_channel	direct_entry

Failure

{
  "code": "E554-206",
  "title": "Account Not Found",
  "detail": "The target account number is incorrect."
}

Properties

Failure object (see Transaction/Failure codes for more info)

Name	Type	Required	Description
code	string	true	No description
title	string	true	No description
detail	string	true	No description

ProposeUnassignedAgreementRequest

{
  "expiry_in_seconds": 60,
  "single_use": false,
  "terms": {
    "per_payout": {
      "min_amount": null,
      "max_amount": 10000
    },
    "per_frequency": {
      "days": 7,
      "max_amount": 1000000
    }
  },
  "metadata": {
    "custom_key": "Custom string",
    "another_custom_key": "Maybe a URL"
  }
}

Properties

Propose an Unassigned Agreement (request)

Name	Type	Required	Description
expiry_in_seconds	integer	true	The amount of time in seconds before the Unassigned Agreement can no longer be accepted.
single_use	boolean	false	Optionally propose a single use agreement. When the Unassigned Agreement is accepted and a Payment Request is approved according to the Agreement terms, the agreement will automatically become `expended`. The proposed agreement must have equal max/min `per_payout` amounts and `null` `per_frequency` amounts. Furthermore, we will automatically check that the authoriser's bank account has sufficient funds to honour the agreement terms.
terms	Terms	true	No description
metadata	Metadata	false	No description

ProposeUnassignedAgreementResponse

{
  "data": {
    "ref": "A.4k",
    "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
    "status": "proposed",
    "responded_at": null,
    "created_at": "2017-03-20T00:53:27Z",
    "terms": {
      "per_payout": {
        "max_amount": 10000,
        "min_amount": null
      },
      "per_frequency": {
        "days": 7,
        "max_amount": 1000000
      }
    },
    "assignment_expires_at": "2017-03-20T00:54:27Z",
    "link": "https://go.nz.sandbox.zepto.money/unassigned_agreements/b61fc159-8779-4a17-a826-e398e3e7e211/invitation",
    "metadata": {
      "custom_key": "Custom string",
      "another_custom_key": "Maybe a URL"
    }
  }
}

Properties

Propose an Unassigned Agreement (response)

Name	Type	Required	Description
data	object	true	No description

ListUnassignedAgreementsResponse

{
  "data": [
    {
      "ref": "A.4k",
      "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
      "status": "proposed",
      "responded_at": null,
      "created_at": "2017-03-20T00:53:27Z",
      "terms": {
        "per_payout": {
          "max_amount": 10000,
          "min_amount": null
        },
        "per_frequency": {
          "days": 7,
          "max_amount": 1000000
        }
      },
      "assignment_expires_at": "2017-03-20T00:54:27Z",
      "link": "https://go.nz.sandbox.zepto.money/unassigned_agreements/b61fc159-8779-4a17-a826-e398e3e7e211/invitation"
    },
    {
      "ref": "A.7ea",
      "initiator_id": "b61fc159-8779-4a17-a826-e398e3e7e211",
      "status": "proposed",
      "responded_at": null,
      "created_at": "2017-03-21T00:53:27Z",
      "terms": {
        "per_payout": {
          "max_amount": null,
          "min_amount": null
        },
        "per_frequency": {
          "days": null,
          "max_amount": null
        }
      },
      "assignment_expires_at": "2017-03-21T00:54:27Z",
      "link": "https://go.nz.sandbox.zepto.money/unassigned_agreements/4e2728cc-b4ba-42c2-a6c3-26a7758de58d/invitation"
    }
  ]
}

Properties

List Unassigned Agreements (response)

Name	Type	Required	Description
data	[object]	true	No description

GetUnassignedAgreementResponse

{
  "data": {
    "ref": "A.4k",
    "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
    "status": "proposed",
    "responded_at": null,
    "created_at": "2017-03-20T00:53:27Z",
    "terms": {
      "per_payout": {
        "max_amount": 10000,
        "min_amount": null
      },
      "per_frequency": {
        "days": 7,
        "max_amount": 1000000
      }
    },
    "assignment_expires_at": "2017-03-20T00:54:27Z",
    "link": "https://go.nz.sandbox.zepto.money/unassigned_agreements/b61fc159-8779-4a17-a826-e398e3e7e211/invitation"
  }
}

Properties

Get an Unassigned Agreement (response)

Name	Type	Required	Description
data	object	true	No description

GetUserDetailsResponse

{
  "data": {
    "first_name": "Bear",
    "last_name": "Dog",
    "mobile_phone": 39536658,
    "email": "bear@dog.com",
    "account": {
      "name": "Dog Bones Inc",
      "nickname": "dog-bones-inc",
      "abn": "129959040",
      "phone": "0218495033",
      "street_address": "98 Acme Avenue",
      "suburb": "Lead",
      "postcode": "2478"
    }
  }
}

Properties

Get User details (response)

Name	Type	Required	Description
data	object	true	No description

SimulateIncomingDEPaymentRequest

{
  "to_account_number": "888888888888888",
  "amount": 10000
}

Properties

Name	Type	Required	Description
to_account_number	string	true	Zepto float account number
amount	integer	true	Amount in cents (Min: 1 - Max: 99999999999)
payment_reference	string	false	Max 18 characters. Default: "simulated-de-pymt"
from_account_number	string	false	Default: "123456789012345"
debtor_name	string	false	Max 16 characters. Default: "Simulated Debtor"

AddATransferRequest

{
  "from_bank_account_id": "a79423b2-3827-4cf5-9eda-dc02a298d005",
  "to_bank_account_id": "0921a719-c79d-4ffb-91b6-1b30ab77d14d",
  "amount": 100000,
  "description": "Float account balance adjustment",
  "matures_at": "2021-06-06T00:00:00Z"
}

Properties

Name	Type	Required	Description
from_bank_account_id	string	true	The source float/bank account (UUID)
to_bank_account_id	string	true	The destination float/bank account (UUID)
amount	integer	true	Amount in cents (Min: 1 - Max: 99999999999)
description	string	true	Description for the Transfer
matures_at	string(date-time)	true	Date & time in UTC ISO8601 the Transfer should be processed. (Can not be earlier than the start of current day in NZST)

AddATransferResponse

{
  "data": {
    "ref": "T.11ub",
    "from_bank_account_id": "a79423b2-3827-4cf5-9eda-dc02a298d005",
    "to_bank_account_id": "0921a719-c79d-4ffb-91b6-1b30ab77d14d",
    "amount": 100000,
    "description": "Float account balance adjustment",
    "matures_at": "2021-06-06T00:00:00Z"
  }
}

Properties

Name	Type	Required	Description
data	object	true	No description
» ref	string	true	The Transfer request reference (T.*) (Min: 4 - Max: 8)
» from_bank_account_id	string	true	The source bank/float account (UUID)
» to_bank_account_id	string	true	The destination bank/float account (UUID
» amount	integer	true	The amount value provided (Min: 1 - Max: 99999999999)
» description	string	true	Description for the Transfer
» matures_at	string(date-time)	true	Date & time in UTC ISO8601 the Transfer should be processed. (Can not be earlier than the start of current day in NZST)

GetATransferResponse

{
  "data": {
    "ref": "T.87xp",
    "from_bank_account_id": "a79423b2-3827-4cf5-9eda-dc02a298d005",
    "to_bank_account_id": "0921a719-c79d-4ffb-91b6-1b30ab77d14d",
    "amount": 47000,
    "description": "Deposit from my bank account",
    "matures_at": "2021-06-03T00:00:00Z"
  }
}

Properties

Name	Type	Required	Description
data	object	true	No description
» ref	string(uuid)	true	The Transfer request reference (T.*) (Min: 4 - Max: 8)
» initiator_id	string	false	Initiating Zepto Account
» from_bank_account_id	string	true	The source bank/float account (UUID)
» to_bank_account_id	string	true	The destination bank/float account (UUID
» amount	integer	true	The amount value provided (Min: 1 - Max: 99999999999)
» description	string	true	Description for the Transfer
» matures_at	string(date-time)	true	Date & time in UTC ISO8601 the Transfer should be processed. (Can not be earlier than the start of current day in NZST)

ListAllWebhooksResponse

{
  "data": [
    {
      "id": "13bd760e-447f-4225-b801-0777a15da131",
      "url": "https://webhook.site/a9a3033b-90eb-44af-9ba3-29972435d10e",
      "signature_secret": "8fad2f5570e6bf0351728f727c5a8c770dda646adde049b866a7800d59",
      "events": [
        "debit.cleared",
        "credit.cleared"
      ]
    }
  ]
}

Properties

List all Webhooks (response)

Name	Type	Required	Description
data	[object]	true	No description

GetWebhookDeliveriesResponse

{
  "data": [
    {
      "id": "957d40a4-80f5-4dd2-8ada-8242d5ad66c1",
      "event_type": "payout_request.added",
      "state": "completed",
      "response_status_code": 200,
      "created_at": "2021-09-02T02:24:50.000Z",
      "payload_data_summary": [
        {
          "ref": "PR.ct5b"
        }
      ]
    },
    {
      "id": "29bb9835-7c69-4ecb-bf96-197d089d0ec3",
      "event_type": "creditor_debit.scheduled",
      "state": "completed",
      "response_status_code": 200,
      "created_at": "2021-09-02T02:24:50.000Z",
      "payload_data_summary": [
        {
          "ref": "D.hyy9"
        },
        {
          "ref": "D.6st93"
        }
      ]
    }
  ]
}

Properties

Name	Type	Required	Description
data	[object]	false	No description

GetAWebhookDeliveryResponse

{
  "data": {
    "id": "957d40a4-80f5-4dd2-8ada-8242d5ad66c1",
    "webhook_id": "13bd760e-447f-4225-b801-0777a15da131",
    "event_type": "payout_request.added",
    "state": "completed",
    "payload": {
      "data": [
        {
          "ref": "PR.ct5b",
          "payout": {
            "amount": 1501,
            "matures_at": "2021-09-02T02:24:49.000Z",
            "description": "Payment from Incoming Test Payment Contact 014209 12345678 (Test Payment)"
          },
          "status": "approved",
          "created_at": "2021-09-02T02:24:49.000Z",
          "credit_ref": "C.p2rt",
          "matures_at": "2021-09-02T02:24:49.000Z",
          "initiator_id": "b50a6e92-a5e1-4175-b560-9e4c9a9bb4b9",
          "responded_at": "2021-09-02T02:24:49.000Z",
          "schedule_ref": null,
          "authoriser_id": "780f186c-80fd-42b9-97d5-650d99a0bc99",
          "status_reason": null,
          "your_bank_account_id": "b50a6e92-a5e1-4175-b560-9e4c9a9bb4b9",
          "authoriser_contact_id": "590be205-6bae-4070-a9af-eb50d514cec5",
          "authoriser_contact_initiated": true
        },
        {
          "event": {
            "at": "2021-09-02T02:24:49.000Z",
            "who": {
              "account_id": "20f4e3f8-2efc-48a9-920b-541515f1c9e3",
              "account_type": "Account",
              "bank_account_id": "b50a6e92-a5e1-4175-b560-9e4c9a9bb4b9",
              "bank_account_type": "BankAccount"
            },
            "type": "payment_request.added"
          }
        }
      ]
    }
  },
  "response_status_code": 200,
  "created_at": "2021-09-02T02:24:50.000Z"
}

Properties

Get a WebhookDelivery (response)

Name	Type	Required	Description
data	object	true	No description
» id	string(uuid)	false	The Webhook Delivery ID
» webhook_id	string(uuid)	false	The Webhook ID
» state	string	false	The state of the webhook delivery.
» payload	object	false	Could be anything
» created_at	string(date-time)	false	When the webhook delivery was created

Enumerated Values

Property	Value
state	pending
state	completed
state	retrying
state	failed

RedeliverAWebhookDeliveryResponse

{
  "data": {
    "id": "957d40a4-80f5-4dd2-8ada-8242d5ad66c1",
    "webhook_id": "13bd760e-447f-4225-b801-0777a15da131",
    "state": "pending"
  }
}

Properties

Resend a WebhookDelivery (response)

Name	Type	Required	Description
data	object	true	No description