Zepto Contacts (Receivable) API

openapi: 3.2.0
info:
  title: Zepto Contacts (Receivable) API
  contact:
    email: support@zepto.com.au
  description: Zepto allows you to make, get and manage payments using nothing but bank accounts.
  version: '1.0'
servers:
- url: https://api.sandbox.zeptopayments.com
  description: Sandbox API server
- url: https://api.zeptopayments.com
  description: Production API server
security:
- bearerAuth: []
tags:
- name: Contacts (Receivable)
paths:
  /contacts/receivable:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    post:
      tags:
      - Contacts (Receivable)
      summary: Add a Receivable Contact
      description: '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.


        To enable this feature, please contact our support team with the following information:


        Your full legal business name


        A legally owned domain name: for your PayID email addresses


        alias_name: the business name that will be displayed to your customers upon PayID resolution. We suggest using a shortened name appropriate for mobile displays


        There are two strategies supported for PayID assignment when creating this type of Contact:


        On-demand PayID: provide a payid_email 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 payid_details.state will always be pending. It will transition to active 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.


        Pooled PayID: provide your payid_email_domain 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 payid_email and payid_email_domain will ignore your pool and use the "On-demand PayID" strategy instead.


        While unlikely, it is possible that we will be unable to register the given PayID. In this case payid_details.state will transition to failed.


        You can simulate this path in sandbox by adding +failure to your payid_email e.g test+failure@zeptopayments.com


        You can test receiving payments to a Receivable Contact in our sandbox environment using the PayID simulation endpoint.'
      operationId: AddAReceivableContact
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAReceivableContactRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddAReceivableContactResponse'
        '404':
          description: Not Found
  /contacts/{contact_id}/receivable/disable:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    post:
      tags:
      - Contacts (Receivable)
      summary: Disable a Receivable Contact
      description: 'This endpoint should be used to Disable a Receivable Contact.


        This will reject all payments made to the relevant Account number or PayID and return them to your customer. Payments made via DE and NPP will be rejected.'
      operationId: DisableAReceivableContact
      parameters:
      - name: contact_id
        in: path
        description: Receivable Contact ID (`ReceivableContact.data.id`)
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: UUID
        example: 2d2429c2-b868-455e-80ef-915df7c115a7
      responses:
        '204':
          description: No Content (success)
        '400':
          description: Bad Request (errors)
        '404':
          description: Not Found
  /contacts/{contact_id}/receivable/activate:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    post:
      tags:
      - Contacts (Receivable)
      summary: Reactivate a Receivable Contact
      description: 'This endpoint should be used to Reactivate a Receivable Contact that has been previously Disabled.


        This will once again allow you to receive funds from your customer via both DE and NPP channels.'
      operationId: ActivateAReceivableContact
      parameters:
      - name: contact_id
        in: path
        description: Receivable Contact ID (`ReceivableContact.data.id`)
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: UUID
        example: 2d2429c2-b868-455e-80ef-915df7c115a7
      responses:
        '204':
          description: No Content (success)
        '400':
          description: Bad Request (errors)
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: string
              examples:
                Contact is not receivable:
                  summary: Contact is not receivable
                  value:
                    errors: Contact is not receivable
                PayID is not disabled:
                  summary: PayID is not disabled
                  value:
                    errors: Contact must be 'disabled' but is '{status}'.
                Contact blocked by a Zepto admin:
                  summary: Contact blocked by a Zepto admin
                  value:
                    errors: This receivable contact can only be enabled by Zepto support. Please contact Zepto for further information
                Bank account not blocked:
                  summary: Bank account not blocked
                  value:
                    errors: Bank account must be blocked.
                Bank account already unblocked:
                  summary: Bank account already unblocked
                  value:
                    errors: Bank account is already unblocked
                Bank account already unblocked for credits:
                  summary: Bank account already unblocked for credits
                  value:
                    errors: Bank account is already unblocked for credits
                Bank account already unblocked for debits:
                  summary: Bank account already unblocked for debits
                  value:
                    errors: Bank account is already unblocked for debits
        '404':
          description: Not Found
  /contacts/{contact_id}/receivable:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    patch:
      tags:
      - Contacts (Receivable)
      summary: Update a Receivable Contact
      description: 'You can update the PayID name of a Receivable Contact.


        The Receivable Contact you are updating must be active.'
      operationId: UpdateAReceivableContact
      parameters:
      - name: contact_id
        in: path
        description: Receivable Contact ID (`ReceivableContact.data.id`)
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: UUID
        example: 2d2429c2-b868-455e-80ef-915df7c115a7
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAReceivableContactRequest'
        required: true
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request (errors)
        '404':
          description: Not Found
components:
  parameters:
    ZeptoAPIVersion:
      name: Zepto-API-Version
      in: header
      required: false
      schema:
        type: string
        pattern: ^\d{8}$
        default: '20250101'
        example: '20260101'
      description: API version in YYYYMMDD format. Defaults to 20250101 (legacy) when omitted.
  schemas:
    AddAReceivableContactResponse:
      title: Add a Receivable Contact (response)
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
              minLength: 3
              maxLength: 140
              description: 'Contact name (Min: 3 - Max: 140)'
            email:
              type: string
              minLength: 6
              maxLength: 256
              description: 'Contact email (Min: 6 - Max: 256)'
            type:
              type: string
              description: Fixed to 'anyone'
            metadata:
              $ref: '#/components/schemas/Metadata'
            bank_account:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                account_number:
                  type: string
                  minLength: 5
                  maxLength: 9
                  description: 'Zepto generated account number (Min: 5 - Max: 9)'
                branch_code:
                  type: string
                  minLength: 6
                  maxLength: 6
                  description: 'Zepto branch code (Min: 6 - Max: 6)'
                bank_name:
                  type: string
                  description: Fixed to 'Zepto Float Acount'
                state:
                  type: string
                  description: Fixed to 'Active'
                  enum:
                  - active
                  - removed
                iav_provider:
                  type:
                  - string
                  - 'null'
                  description: Always null
                iav_status:
                  type:
                  - string
                  - 'null'
                  description: Always null
                blocks:
                  type: object
                  properties:
                    debits_blocked:
                      type: boolean
                      description: Used by Zepto admins. Defines whether the bank account is blocked from being debited
                    credits_blocked:
                      type: boolean
                      description: Used by Zepto admins. Defined Whether this bank account is blocked from being credited
            anyone_account:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
            payid_details:
              type: object
              properties:
                alias_value:
                  type: string
                  format: email
                  minLength: 6
                  maxLength: 256
                  description: The PayID email
                alias_type:
                  type: string
                  description: Type of PayID. Fixed to `email`
                alias_name:
                  type: string
                  minLength: 3
                  maxLength: 140
                  description: Your merchant's alias_name
                state:
                  type: string
                  description: Pending -> Active or Failed -> Deregistered (Contact removed)
                  enum:
                  - pending
                  - active
                  - failed
                  - deregistered
      example:
        data:
          id: 6a7ed958-f1e8-42dc-8c02-3901d7057357
          name: Delphine Jestin
          email: delphine@gmail.com
          type: anyone
          metadata:
            custom_key: Custom string
            another_custom_key: Maybe a URL
          bank_account:
            id: 55afddde-4296-4daf-8e49-7ba481ef9608
            account_number: '1408281'
            branch_code: '802919'
            bank_name: Zepto Float Account
            state: active
            iav_provider: null
            iav_status: null
            blocks:
              debits_blocked: false
              credits_blocked: false
          anyone_account:
            id: 77be6ecc-5fa7-454b-86d6-02a5f147878d
          payid_details:
            alias_value: delphine_123@merchant.com.au
            alias_type: email
            alias_name: your merchant's alias_name
            state: pending
    Metadata:
      title: Metadata
      type: object
      description: Use for your custom data and certain Zepto customisations.
      properties: {}
      example:
        custom_key: Custom string
        another_custom_key: Maybe a URL
    UpdateAReceivableContactRequest:
      title: Update a Receivable Contact (request)
      type: object
      required:
      - payid_name
      properties:
        payid_name:
          type: string
          pattern: ^[ -~]+$
          description: The PayID name of the Receivable Contact
      example:
        payid_name: Bob Smith
    AddAReceivableContactRequest:
      title: Add a Receivable Contact (request)
      required:
      - name
      - email
      type: object
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 140
          pattern: ^[ -~]+$
          description: 'Contact name (Min: 3 - Max: 140)'
        email:
          type: string
          minLength: 6
          maxLength: 256
          description: 'Contact email (Min: 6 - Max: 256)'
        payid_email:
          type: string
          minLength: 6
          maxLength: 256
          description: 'Contact PayID email (Min: 6 - Max: 256)'
        payid_email_domain:
          type: string
          minLength: 3
          maxLength: 254
          description: 'PayID pool email domain (Min: 3 - Max: 254)'
        metadata:
          $ref: '#/components/schemas/Metadata'
      example:
        name: Delphine Jestin
        email: delphine@gmail.com
        payid_email: delphine_123@merchant.com.au
        metadata:
          custom_key: Custom string
          another_custom_key: Maybe a URL
  securitySchemes:
    bearerAuth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          refreshUrl: /oauth/token
          scopes:
            public: Access your public information
            contacts: Manage your contacts
            payments: Manage your payments
            payment_requests: Manage your payment requests
            refunds: Manage your refunds
            agreements: Manage your agreements
            transactions: Access your transaction history
            open_agreements: Manage your open agreements
            transfers: Manage your Transfers