---
title: "Add a Receivable Contact"
method: POST
path: "/contacts/receivable"
tags: ["Contacts (Receivable)"]
---

# Add a Receivable Contact

`POST /contacts/receivable`

Receive funds from a Contact by allowing them to pay to a personalised PayID or account number. Perfect for reconciling incoming funds to a customer, receiving funds instantly, eliminating human error & improving your customer's experience.


<aside class="notice">
  To enable this feature, please contact our support team with the following information:
    <li>Your full legal business name</li>
    <li>A legally owned domain name: for your PayID email addresses</li>
    <li><strong>alias_name</strong>: the business name that will be displayed to your customers upon PayID resolution. We suggest using a shortened name appropriate for mobile displays</li>
</aside>
<aside class="notice">
  There are two strategies supported for PayID assignment when creating this type of Contact:
  <li><strong>On-demand PayID</strong>: provide a <code>payid_email</code> and we'll create a contact and register a PayID with the given email address. The PayID registration process happens when the request is received. The initial response for <code>payid_details.state</code> will always be <code>pending</code>. It will transition to <code>active</code> when the PayID registration process is complete. This can take up to a few seconds. You can use webhooks to be informed of this state change.</li>
  <li><strong>Pooled PayID</strong>: provide your <code>payid_email_domain</code> and we'll create a contact and assign them a PayID from your pool. Pooled PayIDs are pre-registered. The PayID email value is generated using a random value and the email domain from your PayID pool configuration. Providing both <code>payid_email</code> and <code>payid_email_domain</code> will ignore your pool and use the "On-demand PayID" strategy instead.</li>
</aside>
<aside class="notice">
  While unlikely, it is possible that we will be unable to register the given PayID. In this case <code>payid_details.state</code> will transition to <code>failed</code>.

  You can simulate this path in sandbox by adding <code>+failure</code> to your <code>payid_email</code> e.g <code>test+failure@zeptopayments.com</code>
</aside>
<aside class="notice">
  You can test receiving payments to a Receivable Contact in our sandbox environment using the <a href="https://docs.zeptopayments.com/reference/simulateincomingpayidpayment">PayID simulation endpoint</a>.
</aside>

## Request body

- AddAReceivableContactRequest
  - `name` string, required — Contact name (Min: 3 - Max: 140)
  - `email` string, required — Contact email (Min: 6 - Max: 256)
  - `payid_email` string — Contact PayID email (Min: 6 - Max: 256)
  - `payid_email_domain` string — PayID pool email domain (Min: 3 - Max: 254)
  - `metadata` Metadata — Use for your custom data and certain Zepto customisations.

## Response `201`

Created

- AddAReceivableContactResponse
  - `data` object
    - `id` string, uuid
    - `name` string — Contact name (Min: 3 - Max: 140)
    - `email` string — Contact email (Min: 6 - Max: 256)
    - `type` string — Fixed to 'anyone'
    - `metadata` Metadata — Use for your custom data and certain Zepto customisations.
    - `bank_account` object
      - `id` string, uuid
      - `account_number` string — Zepto generated account number (Min: 5 - Max: 9)
      - `branch_code` string — Zepto branch code (Min: 6 - Max: 6)
      - `bank_name` string — Fixed to 'Zepto Float Acount'
      - `state` 'active' | 'removed' — Fixed to 'Active'
      - `iav_provider` string, nullable — Always null
      - `iav_status` string, nullable — Always null
      - `blocks` object
        - `debits_blocked` boolean — Used by Zepto admins. Defines whether the bank account is blocked from being debited
        - `credits_blocked` boolean — Used by Zepto admins. Defined Whether this bank account is blocked from being credited
    - `anyone_account` object
      - `id` string, uuid
    - `payid_details` object
      - `alias_value` string, email — The PayID email
      - `alias_type` string — Type of PayID. Fixed to `email`
      - `alias_name` string — Your merchant's alias_name
      - `state` 'pending' | 'active' | 'failed' | 'deregistered' — Pending -> Active or Failed -> Deregistered (Contact removed)

## Other responses

- `404` — Not Found

---

[API](https://skmtc.net/zeptopayments/apis/zepto-api.md) · [All operations](https://skmtc.net/zeptopayments/apis/zepto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zeptopayments/zepto-api/revisions/6353e9b9af6f/schema)