Zepto Payments API

openapi: 3.2.0
info:
  title: Zepto Payments API
  contact:
    email: support@zepto.com.au
  version: '1.0'
  description: 'Operations tagged Payments across 2 of this provider''s published API definitions: zepto-payments-pay-to.yml, zepto-payments-zepto.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: Zepto Sandbox
  url: https://api.sandbox.zeptopayments.com
- description: Zepto Production
  url: https://api.zeptopayments.com
security:
- bearerAuth: []
tags:
- name: Payments
  description: Make payments using an existing agreement
paths:
  /payto/payments:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    post:
      summary: create payment
      tags:
      - Payments
      parameters: []
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/payto.payment'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Generic validation error:
                  summary: Generic validation error
                  value:
                    errors:
                    - title: Validation Failed
                      detail: The value for `invalid_key` is not allowed
              schema:
                $ref: '#/components/schemas/payto.generic_errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              examples:
                Amount over maximum for agreement:
                  summary: Amount over maximum for agreement
                  value:
                    errors:
                    - code: ZPPAY12
                      title: Amount over maximum
                      detail: The payment amount is larger than the maximum specified in the agreement
                The given creditor account cannot accept funds via NPP:
                  summary: The given creditor account cannot accept funds via NPP
                  value:
                    errors:
                    - code: ZPUNP02
                      title: Invalid creditor account
                      detail: The given creditor account cannot accept funds via NPP
                Over daily limit:
                  summary: Over daily limit
                  value:
                    errors:
                    - code: ZPPAY01
                      title: Over daily limit
                      detail: This Payment would cause you to exceed your current daily limit of $1,000.00
                Amount incorrect:
                  summary: Amount incorrect
                  value:
                    errors:
                    - code: ZPPAY15
                      title: Amount incorrect
                      detail: The payment amount does not match the amount specified in the agreement
                Last payment date mismatch:
                  summary: Last payment date mismatch
                  value:
                    errors:
                    - code: ZPPAY13
                      title: After last payment date
                      detail: The last payment date specified in the agreement has already passed
                    - code: ZPPAY20
                      title: Last payment date mismatch
                      detail: The payment date does not match the last payment date specified in the agreement
                First payment date mismatch:
                  summary: First payment date mismatch
                  value:
                    errors:
                    - code: ZPPAY14
                      title: First payment date mismatch
                      detail: The payment date does not match the first payment date specified in the agreement
                First payment date incorrect:
                  summary: First payment date incorrect
                  value:
                    errors:
                    - code: ZPPAY18
                      title: First payment amount incorrect
                      detail: The payment amount does not match the first payment amount specified in the agreement
                Last payment amount incorrect:
                  summary: Last payment amount incorrect
                  value:
                    errors:
                    - code: ZPPAY19
                      title: Last payment amount incorrect
                      detail: The payment amount does not match the last payment amount specified in the agreement
                Last payment made:
                  summary: Last payment made
                  value:
                    errors:
                    - code: ZPPAY21
                      title: Last payment made
                      detail: No further payments can be created for this agreement, as the last payment has been made
                Too many payments:
                  summary: Too many payments
                  value:
                    errors:
                    - code: ZPPAY17
                      title: Too many payments
                      detail: The maximum number of payments has already been reached for the current frequency period, according to the terms of the agreement
                Last payment param not given for balloon payment:
                  summary: Last payment param not given for balloon payment
                  value:
                    errors:
                    - code: ZPPAY09
                      title: Last payment required for balloon
                      detail: The last payment parameter must be specified for a payment against a balloon type agreement
                Last payment param given for non balloon payment:
                  summary: Last payment param given for non balloon payment
                  value:
                    errors:
                    - code: ZPPAY10
                      title: Last payment given for non-balloon
                      detail: The last payment parameter must only be specified for a payment against a balloon type agreement
                Agreement cannot be found:
                  summary: Agreement cannot be found
                  value:
                    errors:
                    - code: ZPPAY22
                      title: Agreement not found
                      detail: No agreement could be found for the given agreement UID
                Alias resolution not enabled:
                  summary: Alias resolution not enabled
                  value:
                    errors:
                    - code: ZPUNP09
                      title: Alias resolution not enabled
                      detail: Account not enabled for alias resolution services
                Custom debtor not allowed:
                  summary: Custom debtor not allowed
                  value:
                    errors:
                    - code: ZPPAY25
                      title: Custom debtor not allowed
                      detail: Not permitted to provide custom debtor party values that differ from agreement
              schema:
                $ref: '#/components/schemas/payto.unprocessable_payment_errors'
        '401':
          description: unauthorized
          content:
            application/json:
              examples:
                Unauthorised access token:
                  summary: Unauthorised access token
                  value:
                    errors:
                    - title: Unauthorised access token
                      detail: Access token is expired or not valid
                      links:
                        about: https://docs.zeptopayments.com/docs/zepto-api#authentication-and-authorisation
              schema:
                $ref: '#/components/schemas/payto.generic_errors'
        '403':
          description: forbidden
        '500':
          description: Internal Server Error
      requestBody:
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/payto.payment_request'
      callbacks:
        payto_payment.settled:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_payment.settled
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_payment.settled'
              responses:
                '200':
                  description: OK
        payto_payment.failed:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_payment.failed
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_payment.failed'
              responses:
                '200':
                  description: OK
        payto_payment.pending:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_payment.pending
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_payment.pending'
              responses:
                '200':
                  description: OK
        payto_payment.under_investigation:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_payment.under_investigation
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_payment.under_investigation'
              responses:
                '200':
                  description: OK
    get:
      summary: list payments
      parameters:
      - name: per_page
        description: Number of results per page
        in: query
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
      - name: starting_after
        description: Opaque pagination cursor value. Set by following "next" links.
        in: query
        schema:
          type: string
      - name: state
        description: Filter payments by state. Multiple values can be separated by commas.
        in: query
        explode: false
        schema:
          type: array
          items:
            enum:
            - created
            - submitting
            - pending
            - under_investigation
            - failed
            - settled
      - name: min_created_date
        description: Filter by minimum created_at date. ISO8601 format.
        example: '2022-01-01'
        in: query
        schema:
          type: string
          format: date
      - name: max_created_date
        description: Filter by maximum created_at date. ISO8601 format.
        example: '2022-01-31'
        in: query
        schema:
          type: string
          format: date
      - name: agreement_uid
        description: Filter payments by agreement.
        example: biz_agreement_000123
        in: query
        schema:
          type: string
      - name: agreement_initiator_name
        description: Filter payments by initiator name. The filtering is case sensitive and must be an exact match.
        example: Jane's Flowers
        in: query
        schema:
          type: string
      - name: refunds
        description: Filter payments by whether or not they are facilitating a refund.
        example: included
        in: query
        schema:
          type: string
          enum:
          - included
          - excluded
          - only
      tags:
      - Payments
      responses:
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              examples:
                Non integer per_page:
                  summary: Non integer per_page
                  value:
                    errors:
                    - code: ZPPGN00
                      title: One or more paramaters are invalid
                      detail: The `per_page` param is not valid.
                No record with ID matching starting_after param:
                  summary: No record with ID matching starting_after param
                  value:
                    errors:
                    - code: ZPPGN00
                      title: One or more paramaters are invalid
                      detail: Could not find a record for the given `starting_after` param.
              schema:
                $ref: '#/components/schemas/payto.unprocessable_pagination_errors'
        '200':
          description: successful
          content:
            application/json:
              examples:
                Successful request:
                  summary: Successful request
                  value:
                    links: {}
                    data:
                    - uid: biz_payment_0000000000860
                      agreement_uid: biz_agreement_0000000001350
                      state: settled
                      amount: 12345
                      last_payment: null
                      priority: unattended
                      reference: null
                      description: null
                      creditor:
                        party_name: Mr Creditor
                        ultimate_party_name: Ultimate Mr Creditor
                        account_identifier:
                          type: bban
                          value: 123456-456789
                      creditor_reference: null
                      debtor:
                        ultimate_party_name: Ms Debtor
                        party_name: Ms Debtor
                        account_identifier:
                          type: bban
                          value: 123456-456789
                      failure: null
                      created_at: '2022-02-01T09:41:00+11:00'
                      metadata:
                        custom_key: custom_value
                      source_payto_refund_uid: null
                      links:
                        self: https://api.zeptopayments.com/payto/payments/biz_payment_0000000000860
                        agreement: https://api.zeptopayments.com/payto/agreements/biz_agreement_0000000001350
                        source_refund: null
                    - uid: biz_payment_0000000000850
                      agreement_uid: biz_agreement_0000000001350
                      state: settled
                      amount: 12345
                      last_payment: null
                      priority: unattended
                      reference: null
                      description: null
                      creditor:
                        party_name: Mr Creditor
                        ultimate_party_name: Ultimate Mr Creditor
                        account_identifier:
                          type: bban
                          value: 123456-456789
                      creditor_reference: null
                      debtor:
                        ultimate_party_name: Ms Debtor
                        party_name: Ms Debtor
                        account_identifier:
                          type: bban
                          value: 123456-456789
                      failure: null
                      created_at: '2022-02-01T09:41:00+11:00'
                      metadata:
                        custom_key: custom_value
                      source_payto_refund_uid: null
                      links:
                        self: https://api.zeptopayments.com/payto/payments/biz_payment_0000000000850
                        agreement: https://api.zeptopayments.com/payto/agreements/biz_agreement_0000000001350
                        source_refund: null
                    - uid: biz_payment_0000000000840
                      agreement_uid: biz_agreement_0000000001350
                      state: settled
                      amount: 12345
                      last_payment: null
                      priority: unattended
                      reference: null
                      description: null
                      creditor:
                        party_name: Mr Creditor
                        ultimate_party_name: Ultimate Mr Creditor
                        account_identifier:
                          type: bban
                          value: 123456-456789
                      creditor_reference: null
                      debtor:
                        ultimate_party_name: Ms Debtor
                        party_name: Ms Debtor
                        account_identifier:
                          type: bban
                          value: 123456-456789
                      failure: null
                      created_at: '2022-02-01T09:41:00+11:00'
                      metadata:
                        custom_key: custom_value
                      source_payto_refund_uid: null
                      links:
                        self: https://api.zeptopayments.com/payto/payments/biz_payment_0000000000840
                        agreement: https://api.zeptopayments.com/payto/agreements/biz_agreement_0000000001350
                        source_refund: null
              schema:
                type: object
                properties:
                  links:
                    $ref: '#/components/schemas/payto.pagination_links'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/payto.payment'
    servers:
    - description: Zepto Sandbox
      url: https://api.sandbox.zeptopayments.com
    - description: Zepto Production
      url: https://api.zeptopayments.com
  /payto/payments/{payment_uid}:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    - name: payment_uid
      in: path
      schema:
        type: string
        pattern: ^[A-Za-z0-9_~.-]{1,64}$
        description: A supplied unique ID
        example: Payment_00012345
      required: true
    get:
      summary: show payment
      tags:
      - Payments
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/payto.payment'
        '401':
          description: unauthorized
          content:
            application/json:
              examples:
                Unauthorised access token:
                  summary: Unauthorised access token
                  value:
                    errors:
                    - title: Unauthorised access token
                      detail: Access token is expired or not valid
                      links:
                        about: https://docs.zeptopayments.com/docs/zepto-api#authentication-and-authorisation
              schema:
                $ref: '#/components/schemas/payto.generic_errors'
        '403':
          description: forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
    servers:
    - description: Zepto Sandbox
      url: https://api.sandbox.zeptopayments.com
    - description: Zepto Production
      url: https://api.zeptopayments.com
  /payto/payments/{payment_uid}/retry:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    - name: payment_uid
      in: path
      schema:
        type: string
        pattern: ^[A-Za-z0-9_~.-]{1,64}$
        description: A supplied unique ID
        example: Payment_00012345
      required: true
    post:
      summary: retry payment
      tags:
      - Payments
      parameters: []
      description: Retry a failed payment as long as it has failed due to a [retryable]https://docs.zeptopayments.com/reference/payto-reason-codes) reason as indicated by the `retryable` boolean field within the payment's failure object. Payments may be retried up to 10 times while within the related agreement's validity begin and end dates. Additionally, payments can only be retried 5 times within a 24 hour period (the first submission is included in this count).
      responses:
        '202':
          description: successful
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Generic validation error:
                  summary: Generic validation error
                  value:
                    errors:
                    - title: Validation Failed
                      detail: The value for `unexpected_key` is not allowed
              schema:
                $ref: '#/components/schemas/payto.generic_errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              examples:
                Payment is not retryable:
                  summary: Payment is not retryable
                  value:
                    errors:
                    - code: ZPPRY00
                      title: Payment not retryable
                      detail: Payment is not in a retryable state
              schema:
                $ref: '#/components/schemas/payto.unprocessable_payment_retry_errors'
        '401':
          description: unauthorized
          content:
            application/json:
              examples:
                Unauthorised access token:
                  summary: Unauthorised access token
                  value:
                    errors:
                    - title: Unauthorised access token
                      detail: Access token is expired or not valid
                      links:
                        about: https://docs.zeptopayments.com/docs/zepto-api#authentication-and-authorisation
              schema:
                $ref: '#/components/schemas/payto.generic_errors'
        '403':
          description: forbidden
        '500':
          description: Internal Server Error
      requestBody:
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/payto.retry_payment_request'
      callbacks:
        payto_payment.settled:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_payment.settled
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_payment.settled'
              responses:
                '200':
                  description: OK
        payto_payment.failed:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_payment.failed
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_payment.failed'
              responses:
                '200':
                  description: OK
    servers:
    - description: Zepto Sandbox
      url: https://api.sandbox.zeptopayments.com
    - description: Zepto Production
      url: https://api.zeptopayments.com
  /payments:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    post:
      tags:
      - Payments
      summary: Make a Payment
      description: "To enable custom payment flows, the required payment channel can be selected by setting the _channel_ attribute to one of the following combinations:\n\n<ul>\n  <li>[\"new_payments_platform\"] - for faster payments 24/7/365</li>\n  <li>[\"direct_entry\"] - for slower traditional payments</li>\n  <li>[\"new_payments_platform\", \"direct_entry\"] - enables automatic channel switching if a payment fails on the NPP</li>\n</ul>\n<aside class=\"notice\">We now require supplying an <code>Idempotency-Key</code> header when performing this request to ensure you can safely retry the action in case of an issue. If the header value 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 <a href=\"https://docs.zeptopayments.com/v20260101/reference/idempotent-requests\">Idempotent requests guide</a>.</aside>\n"
      operationId: MakeAPayment
      parameters:
      - name: Idempotency-Key
        in: header
        description: Idempotency key to support safe retries for 24h
        required: true
        schema:
          type: string
        example: '{unique-uuid-per-payment}'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MakeAPaymentRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MakeAPaymentResponse'
        '400':
          description: Bad Request (errors)
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: string
              examples:
                Invalid channel:
                  summary: Invalid channel
                  value:
                    errors: 'Channels must be one of: new_payments_platform, direct_entry'
                Channel not supported by bank account:
                  summary: Channel not supported by bank account
                  value:
                    errors: Channels {channel} is not supported by your bank account. Please contact us for assistance
                Transaction limit exceeded:
                  summary: Transaction limit exceeded
                  value:
                    errors: The requested amount exceeds the {amount} limit per transaction. Please contact Zepto customer support.
                Limit exceeded:
                  summary: Limit exceeded
                  value:
                    errors: Amount must be less than or equal to 1000000000
                Invalid description format:
                  summary: Invalid description format
                  value:
                    errors: Description is in invalid format
                Mature date in the past:
                  summary: Mature date in the past
                  value:
                    errors: Matures at must not be in the past
                Not found bank account:
                  summary: Not found bank account
                  value:
                    errors: Your bank account not found
                Bank account not configured:
                  summary: Bank account not configured
                  value:
                    errors: Your bank account is not configured for payments
                Bank account removed:
                  summary: Bank account removed
                  value:
                    errors: Recipient contact (#{recipient_contact.id}) bank account has been removed
                Recipient bank account blocked:
                  summary: Recipient bank account blocked
                  value:
                    errors: Recipient contact (#{recipient_contact.id}) is blocked (reason)
                Different float accounts:
                  summary: Different float accounts
                  value:
                    errors: Recipient contact (#{recipient_contact.id}) must share the same control account
                Insufficient funds:
                  summary: Insufficient funds
                  value:
                    errors: Your bank account has insufficient funds
                Blocked bank account:
                  summary: Blocked bank account
                  value:
                    errors: Your bank account is blocked (reason)
                Inactive bank account:
                  summary: Inactive bank account
                  value:
                    errors: Your bank account not active
                Invalid purpose category:
                  summary: Invalid purpose category
                  value:
                    errors: 'Category purpose code must be one of: PENS, SALA, TAXS'
                Exceeded payout size:
                  summary: Exceeded payout size
                  value:
                    errors: Payouts size cannot be greater than 50
                Not filled end to end:
                  summary: Not filled end to end
                  value:
                    errors: End to end can't be blank
    get:
      tags:
      - Payments
      summary: List all Payments
      description: ''
      operationId: ListAllPayments
      parameters:
      - name: page
        in: query
        description: Page of results to return, single value, exact match
        style: form
        schema:
          type: string
        example: '1'
      - name: per_page
        in: query
        description: Number of results per page, single value, exact match
        style: form
        schema:
          type: string
        example: '100'
      responses:
        '200':
          description: OK
          headers:
            Link:
              $ref: '#/components/headers/Link'
            Per-Page:
              $ref: '#/components/headers/Per-Page'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAllPaymentsResponse'
    servers:
    - url: https://api.sandbox.zeptopayments.com
      description: Sandbox API server
    - url: https://api.zeptopayments.com
      description: Production API server
  /payments/{payment_ref}:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    get:
      tags:
      - Payments
      summary: Get a Payment
      description: Get a single payment by its reference
      operationId: GetAPayment
      parameters:
      - name: payment_ref
        in: path
        description: Payment reference
        required: true
        style: simple
        schema:
          type: string
        example: PB.1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAPaymentResponse'
    servers:
    - url: https://api.sandbox.zeptopayments.com
      description: Sandbox API server
    - url: https://api.zeptopayments.com
      description: Production API server
components:
  schemas:
    payto.account_identifier:
      type: object
      description: An identifier representing the parties account
      required:
      - type
      - value
      properties:
        type:
          type: string
          enum:
          - bban
          - alias_phone
          - alias_email
          - alias_abn
          - alias_organisation_identifier
        value:
          anyOf:
          - $ref: '#/components/schemas/payto.account_identifiers_bban'
          - $ref: '#/components/schemas/payto.account_identifiers_alias_email'
          - $ref: '#/components/schemas/payto.account_identifiers_alias_phone'
          - $ref: '#/components/schemas/payto.account_identifiers_alias_abn'
          - $ref: '#/components/schemas/payto.account_identifiers_alias_organisation_identifier'
    payto.payment:
      type: object
      additionalProperties: false
      required:
      - uid
      - agreement_uid
      - state
      - reference
      - description
      - priority
      - creditor
      - creditor_reference
      - debtor
      - amount
      - failure
      - created_at
      - links
      - last_payment
      - source_payto_refund_uid
      properties:
        uid:
          type: string
          pattern: ^[A-Za-z0-9_~.-]{1,64}$
          description: Supplied unique identifier for payment, maximum 64 characters containing only unreserved characters as defined in RFC3986. This identifier ensures payment uniqueness between integrator systems and Zepto.
          example: biz_20221231_G7MQWwkQZIP8vbfH
          minLength: 1
          maxLength: 64
        agreement_uid:
          type: string
          pattern: ^[A-Za-z0-9_~.-]{1,64}$
          description: A supplied unique ID
        

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zepto-payments/refs/heads/main/openapi/zepto-payments-payments-api-openapi.yml