Zepto Agreement modification API

openapi: 3.2.0
info:
  title: Zepto PayTo Agreement modification API
  version: '20260101'
  description: Documentation for the Zepto PayTo API.
  termsOfService: https://www.zepto.com.au/terms-of-service/
  contact:
    email: support@zepto.com.au
servers:
- description: Zepto Sandbox
  url: https://api.sandbox.zeptopayments.com
- description: Zepto Production
  url: https://api.zeptopayments.com
security:
- bearerAuth: []
tags:
- name: Agreement modification
  description: Modify existing agreements
paths:
  /payto/agreements/{agreement_uid}/amendment:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    - name: agreement_uid
      in: path
      schema:
        type: string
        pattern: ^[A-Za-z0-9_~.-]{1,64}$
        description: A supplied unique ID
        example: Agreement_00012345
      required: true
    post:
      summary: create amendment
      tags:
      - Agreement modification
      description: 'Create an amendment for an existing Agreement.


        Any attributes of the existing Agreement that will no longer be relevant after the amendment has been applied must be set to `null` as part of the amendment.

        For example, when amending `payment_terms.type` from `"fixed"` to `"variable"`, `payment_terms.amount` must be set to `null`.

        '
      parameters: []
      responses:
        '202':
          description: accepted
        '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:
                Mandate in wrong state:
                  summary: Mandate in wrong state
                  value:
                    errors:
                    - code: ZPAMN00
                      title: Agreement not amendable
                      detail: Agreement must be active or suspended before it can be amended
                Mandate initiator missing ABN or ACN:
                  summary: Mandate initiator missing ABN or ACN
                  value:
                    errors:
                    - code: ZPAGR18
                      title: Initiator must include exactly one of ABN, ACN, or client_id
                      detail: You must provide exactly one of initiator ABN, ACN, or client_id
              schema:
                $ref: '#/components/schemas/payto.unprocessable_mandate_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
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      requestBody:
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/payto.amendment_request'
      callbacks:
        payto_agreement.amended:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.amended
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.amended'
              responses:
                '200':
                  description: OK
        payto_agreement.amendment_declined:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.amendment_declined
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.amendment_declined'
              responses:
                '200':
                  description: OK
        payto_agreement.amendment_expired:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.amendment_expired
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.amendment_expired'
              responses:
                '200':
                  description: OK
        payto_agreement.amendment_failed:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.amendment_failed
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.amendment_failed'
              responses:
                '200':
                  description: OK
    get:
      summary: show amendment
      tags:
      - Agreement modification
      description: This will return any in-progress amendment for an Agreement (e.g. no response from debtor). If the Agreement has no in-progress amendment, endpoint will return `404`
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                Successful request:
                  summary: Successful request
                  value:
                    data:
                      agreement_uid: biz_agreement_123
                      actor: initiator
                      changes:
                        description: A short description
                      resolution_requested_before: null
                      state: pending
                      failure: null
                      created_at: '2022-02-01T09:41:00+11:00'
                      links:
                        agreement: https://api.zeptopayments.com/payto/agreements/biz_agreement_123
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/payto.amendment'
        '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
  /payto/agreements/{agreement_uid}/amendment/recall:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    - name: agreement_uid
      in: path
      schema:
        type: string
        pattern: ^[A-Za-z0-9_~.-]{1,64}$
        description: A supplied unique ID
        example: Agreement_00012345
      required: true
    post:
      summary: create amendment_recall
      tags:
      - Agreement modification
      description: An in-progress amendment for an Agreement can be recalled if debtor has not responded yet. Once the amendment as been recalled a new amendment can be created.
      parameters: []
      responses:
        '202':
          description: accepted
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              examples:
                Recall already in progress:
                  summary: Recall already in progress
                  value:
                    errors:
                    - code: ZPARE01
                      title: Already processing
                      detail: There is already an in-progress recall for this amendment
              schema:
                $ref: '#/components/schemas/payto.unprocessable_amendment_recall_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:
              $ref: '#/components/schemas/payto.amendment_recall_request'
      callbacks:
        payto_agreement.amendment_recalled:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.amendment_recalled
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.amendment_recalled'
              responses:
                '200':
                  description: OK
        payto_agreement.amendment_recall_failed:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.amendment_recall_failed
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.amendment_recall_failed'
              responses:
                '200':
                  description: OK
  /payto/agreements/{agreement_uid}/cancellation:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    - name: agreement_uid
      in: path
      schema:
        type: string
        pattern: ^[A-Za-z0-9_~.-]{1,64}$
        description: A supplied unique ID
        example: Agreement_00012345
      required: true
    post:
      summary: cancel agreement
      tags:
      - Agreement modification
      parameters: []
      responses:
        '202':
          description: accepted
        '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:
                Mandate in incorrect state:
                  summary: Mandate in incorrect state
                  value:
                    errors:
                    - code: ZPCAN00
                      title: Incorrect agreement state
                      detail: Agreement can not be cancelled while in the 'cancelled' state
              schema:
                $ref: '#/components/schemas/payto.unprocessable_mandate_cancel_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
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      requestBody:
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/payto.cancellation_request'
      callbacks:
        payto_agreement.cancelled:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.cancelled
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.cancelled'
              responses:
                '200':
                  description: OK
        payto_agreement.cancellation_failed:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.cancellation_failed
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.cancellation_failed'
              responses:
                '200':
                  description: OK
  /payto/agreements/{agreement_uid}/suspension:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    - name: agreement_uid
      in: path
      schema:
        type: string
        pattern: ^[A-Za-z0-9_~.-]{1,64}$
        description: A supplied unique ID
        example: Agreement_00012345
      required: true
    post:
      summary: suspend agreement
      tags:
      - Agreement modification
      parameters: []
      responses:
        '202':
          description: accepted
        '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:
                Debtor's financial institution does not support PayTo:
                  summary: Debtor's financial institution does not support PayTo
                  value:
                    errors:
                    - code: ZPSUS00
                      title: Incorrect agreement state
                      detail: Agreement can not be suspended by the initiator while in the 'suspended' state
              schema:
                $ref: '#/components/schemas/payto.unprocessable_mandate_suspend_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
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      requestBody:
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/payto.suspension_request'
      callbacks:
        payto_agreement.suspended:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.suspended
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.suspended'
              responses:
                '200':
                  description: OK
        payto_agreement.suspension_failed:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.suspension_failed
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.suspension_failed'
              responses:
                '200':
                  description: OK
  /payto/agreements/{agreement_uid}/reactivation:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    - name: agreement_uid
      in: path
      schema:
        type: string
        pattern: ^[A-Za-z0-9_~.-]{1,64}$
        description: A supplied unique ID
        example: Agreement_00012345
      required: true
    post:
      summary: reactivate agreement
      tags:
      - Agreement modification
      parameters: []
      responses:
        '202':
          description: accepted
        '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:
                Agreement suspended by other party:
                  summary: Agreement suspended by other party
                  value:
                    errors:
                    - code: ZPREA00
                      title: Incorrect agreement state
                      detail: Agreement cannot be reactivated by the initiator whilst in the 'active' state (set by the initiator)
              schema:
                $ref: '#/components/schemas/payto.unprocessable_mandate_reactivate_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
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      requestBody:
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/payto.reactivation_request'
      callbacks:
        payto_agreement.reactivated:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.reactivated
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.reactivated'
              responses:
                '200':
                  description: OK
        payto_agreement.reactivation_failed:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.reactivation_failed
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.reactivation_failed'
              responses:
                '200':
                  description: OK
  /payto/agreements/{agreement_uid}/simulate_debtor_action:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    - name: agreement_uid
      in: path
      schema:
        type: string
        pattern: ^[A-Za-z0-9_~.-]{1,64}$
        description: A supplied unique ID
        example: Agreement_00012345
      required: true
    post:
      summary: simulate debtor [sandbox]
      tags:
      - Agreement modification
      description: '**SANDBOX ONLY** Enables simulation of actions debtor party can trigger for an agreement: `amendment`, `cancellation`, `suspension` & `reactivation`'
      parameters: []
      responses:
        '202':
          description: accepted
        '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:
                Incorrect agreement state:
                  summary: Incorrect agreement state
                  value:
                    errors:
                    - code: ZPCAN00
                      title: Incorrect agreement state
                      detail: Agreement can not be cancelled while in the 'cancelled' state
                Invalid value for type:
                  summary: Invalid value for type
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: params.debtor.account_identifier.value is in invalid format
              schema:
                $ref: '#/components/schemas/payto.unprocessable_mandate_simulate_debtor_action_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
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      requestBody:
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/payto.simulate_debtor_action_request'
      callbacks:
        payto_agreement.cancelled:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.cancelled
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.cancelled'
              responses:
                '200':
                  description: OK
        payto_agreement.suspended:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.suspended
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.suspended'
              responses:
                '200':
                  description: OK
        payto_agreement.reactivated:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.reactivated
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.reactivated'
              responses:
                '200':
                  description: OK
        payto_agreement.amended:
          DESTINATION_WEBHOOK_URL:
            post:
              summary: payto_agreement.amended
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/payto.webhook.payto_agreement.amended'
              responses:
                '200':
                  description: OK
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.unprocessable_mandate_simulate_debtor_action_errors:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/payto.unprocessable_mandate_simulate_debtor_action_error'
      required:
      - errors
    payto.unprocessable_mandate_reactivate_errors:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/payto.unprocessable_mandate_reactivate_error'
      required:
      - errors
    payto.event.payto_agreement.reactivation_failed:
      allOf:
      - $ref: '#/components/schemas/payto.event.base'
      - $ref: '#/components/schemas/payto.event.agreement_action_failed'
    payto.webhook.payto_agreement.suspension_failed:
      allOf:
      - $ref: '#/components/schemas/payto.webhook.base'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/payto.event.payto_agreement.suspension_failed'
      - type: object
        example:
          data:
            type: payto_agreement.suspension_failed
            resource_type: payto_agreement
          links:
            resource: https://api.zeptopayments.com/payto/agreements/biz_20221231_G7MQWwkQZIP8vbfH
    payto.simulate_debtor_suspension_request:
      type: object
      required:
      - debtor_action
      - reason
      properties:
        debtor_action:
          type: string
          description: The debtor action to be triggered for simulation
          enum:
          - suspension
          example: suspension
        reason:
          type: string
          description: Reason for the agreement being suspended
          enum:
          - invalid_debtor_account_number
          - closed_account_number
          - closed_debtor_account_number
          - blocked_account
          - invalid_debtor_account_type
          - transaction_forbidden
          - transaction_not_supported
          - not_allowed_currency
          - not_allowed_amount
          - amount_exceeds_agreed_limit
          - customer_deceased
          - no_mandate_service_agent
          - no_mandate_service_customer
          - customer_requested
          - initiating_party_requested
          - mandate_expired
          - suspected_fraudulent
          - no_reason_customer
          - no_reason_agent
          - narrative
          - regulatory
          - no_service_debtor
          - creditor_not_whitelisted_by_debtor
          - creditor_blacklisted_by_debtor
          - contract_amended
          - debtor_cancellation_requested
          - contract_expired
          - mandate_suspended_final_collection
          - mandate_suspended_one_collection
          - mandate_suspended_failed_collections
          - no_answer
          example: customer_requested
        narrative:
          description: Free text field to store a description to accompany the given reason
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 256
          example: My custom description
    payto.simulate_debtor_amendment_request:
      type: object
      required:
      - debtor_action
      - changes
      properties:
        debtor_action:
          type: string
          description: The debtor action to be triggered for simulation
          enum:
          - amendment
          example: amendment
        changes:
          type: object
          required:
          - debtor
          properties:
            debtor:
              type: object
              description: Who and where the payment is taken from
              properties:
                ultimate_party_name:
                  type: string
                  example: Billie Jean Senior
                  minLength: 1
                  maxLength: 140
                  pattern: ^[ -~]+$
                  description: The ultimate debtor name for the account.
                party_name:
                  type: string
                  example: Billie Jean Junior
                  minLength: 1
                  maxLength: 140
                  pattern: ^[ -~]+$
                  description: The name of the debtor party for this agreement.
                account_identifier:
                  type: object
                  description: An identifier representing the parties account. In production, the debtor can only change the account_identifier to another value within the scope of the same BIC. This sandbox simulation does not enforce that scope.
                  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.webhook.payto_agreement.cancellation_failed:
      allOf:
      - $ref: '#/compon

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