openapi: 3.2.0
info:
  title: Zepto PayTo Alias Resolution 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: Alias Resolution
  description: Resolve the display name associated with a PayID alias
paths:
  /payto/alias_resolution:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    post:
      summary: resolve
      tags:
      - Alias Resolution
      parameters: []
      description: This endpoint is used to resolve an alias to a display name. It is possible for this endpoint to return a 503 service unavailable error if the addressing service is not available.
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/payto.alias_resolution'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              examples:
                Alias not found:
                  summary: Alias not found
                  value:
                    errors:
                    - title: Alias not found
                      detail: The given alias was not able to be resolved
                      code: ZPADD01
                Missing type param:
                  summary: Missing type param
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: params.type is missing
                Missing value param:
                  summary: Missing value param
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: params.value is missing
                Missing requester.id param:
                  summary: Missing requester.id param
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: params.requester.id is missing
                Invalid type param:
                  summary: Invalid type param
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: 'params.type must be one of: alias_phone, alias_email, alias_abn, alias_organisation_identifier'
                Value matches no regex's:
                  summary: Value matches no regex's
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: params.value is in invalid format
                Invalid value for alias_phone alias type:
                  summary: Invalid value for alias_phone alias type
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: The given value is not a valid alias_phone
                Invalid value for alias_email alias type:
                  summary: Invalid value for alias_email alias type
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: The given value is not a valid alias_email
                Invalid value for alias_abn alias type:
                  summary: Invalid value for alias_abn alias type
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: The given value is not a valid alias_abn
                Invalid value for organisation identifier alias type:
                  summary: Invalid value for organisation identifier alias type
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: The given value is not a valid alias_organisation_identifier
                Account daily lookup limit exceeded:
                  summary: Account daily lookup limit exceeded
                  value:
                    errors:
                    - code: ZPADD02
                      title: Account lookup limit reached
                      detail: The account level lookup limit has been reached for the current period
                Invalid requester remote IPv4:
                  summary: Invalid requester remote IPv4
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: params.requester.remote_ip is in invalid format
                Remote IP level limit exceeded:
                  summary: Remote IP level limit exceeded
                  value:
                    errors:
                    - code: ZPADD03
                      title: Remote IP lookup limit reached
                      detail: The remote IP level lookup limit has been reached for the current period
                Invalid requester id:
                  summary: Invalid requester id
                  value:
                    errors:
                    - code: ZPUNP00
                      title: One or more fields violate the relevant schema
                      detail: params.requester.id is in invalid format
                Requester ID level limit reached:
                  summary: Requester ID level limit reached
                  value:
                    errors:
                    - code: ZPADD04
                      title: Requester ID lookup limit reached
                      detail: The requester ID level lookup limit has been reached for the current period
                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
              schema:
                $ref: '#/components/schemas/payto.unprocessable_alias_resolution_errors'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Generic validation error:
                  summary: Generic validation error
                  value:
                    errors:
                    - title: Validation Failed
                      detail: The value for `alias_owner` is not allowed
              schema:
                $ref: '#/components/schemas/payto.generic_errors'
        '503':
          description: service unavailable
          content:
            application/json:
              examples:
                test_example:
                  value:
                    errors:
                    - title: Service Unavailable
                      detail: The Addressing Service is temporarily unavailable
                      code: ZPADD98
              schema:
                $ref: '#/components/schemas/payto.alias_resolution_service_unavailable_errors'
        '404':
          description: not found
        '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.alias_resolution_request'
components:
  schemas:
    payto.alias_resolution_email_request:
      allOf:
      - type: object
        required:
        - type
        - value
        properties:
          type:
            type: string
            enum:
            - alias_phone
            - alias_email
            - alias_abn
            - alias_organisation_identifier
            example: alias_email
          value:
            allOf:
            - $ref: '#/components/schemas/payto.account_identifiers_alias_email'
      - $ref: '#/components/schemas/payto.alias_resolution_base_request'
    payto.alias_resolution_base_request:
      type: object
      required:
      - requester
      properties:
        requester:
          type: object
          description: Details of the end-user requesting this resolution.
          required:
          - id
          - remote_ip
          properties:
            id:
              type: string
              pattern: ^[A-Za-z0-9_~.-]{1,64}$
              description: Integrator's unique identifier for the end-user requesting this resolution. Maximum 64 characters containing only unreserved characters as defined in RFC3986.
              example: user_G7MQWwkQZIP8vbfH
              minLength: 1
              maxLength: 64
            remote_ip:
              type: string
              description: IP address of the end-user requesting this resolution. (IPv4 or IPv6)
              anyOf:
              - format: ipv4
              - format: ipv6
              example: 192.0.2.146
        sandbox:
          type: object
          required:
          - simulate
          description: 'SANDBOX ONLY: Parameter that allows you to simulate certain alias lookup scenarios to aid integrators while testing their control flows.'
          properties:
            simulate:
              type: string
              enum:
              - alias_found
              - alias_not_found
              - service_unavailable
            display_name:
              type: string
              description: Display name to be returned when simulating an `alias_found` response. Will be ignored for other simulations. Defaults to `Sandbox User`.
              example: Jane Smith
    payto.alias_resolution_organisation_request:
      allOf:
      - type: object
        required:
        - type
        - value
        properties:
          type:
            type: string
            enum:
            - alias_phone
            - alias_email
            - alias_abn
            - alias_organisation_identifier
            example: alias_organisation_identifier
          value:
            allOf:
            - $ref: '#/components/schemas/payto.account_identifiers_alias_organisation_identifier'
      - $ref: '#/components/schemas/payto.alias_resolution_base_request'
    payto.alias_resolution_phone_request:
      allOf:
      - type: object
        required:
        - type
        - value
        properties:
          type:
            type: string
            enum:
            - alias_phone
            - alias_email
            - alias_abn
            - alias_organisation_identifier
            example: alias_phone
          value:
            allOf:
            - $ref: '#/components/schemas/payto.account_identifiers_alias_phone'
      - $ref: '#/components/schemas/payto.alias_resolution_base_request'
    payto.alias_resolution_service_unavailable_errors:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/payto.alias_resolution_service_unavailable_error'
      required:
      - errors
    payto.alias_resolution:
      type: object
      required:
      - display_name
      properties:
        display_name:
          type: string
          example: Jane Smith
          description: The display name associated with the alias.
    payto.alias_resolution_request:
      type: object
      anyOf:
      - $ref: '#/components/schemas/payto.alias_resolution_phone_request'
      - $ref: '#/components/schemas/payto.alias_resolution_email_request'
      - $ref: '#/components/schemas/payto.alias_resolution_abn_request'
      - $ref: '#/components/schemas/payto.alias_resolution_organisation_request'
      discriminator:
        propertyName: type
        mapping:
          alias_phone: '#/components/schemas/payto.alias_resolution_phone_request'
          alias_email: '#/components/schemas/payto.alias_resolution_email_request'
          alias_abn: '#/components/schemas/payto.alias_resolution_abn_request'
          alias_organisation_identifier: '#/components/schemas/payto.alias_resolution_organisation_request'
    payto.alias_resolution_service_unavailable_error:
      type: object
      additionalProperties: false
      required:
      - title
      - detail
      - code
      properties:
        title:
          type: string
          example: Title of error
        code:
          type: string
          description: A code assigned to the type of error received
          example: E100
          enum:
          - ZPADD98
        detail:
          type: string
          description: A short description of the error
          example: Description of error
        links:
          type: object
          properties:
            about:
              type: string
              description: An optional link to more information on the error
              example: https://docs.zeptopayments.com/docs/zepto-environments
          required:
          - about
        meta:
          type: object
          description: Optional meta information about the error
          properties:
            resource_ref:
              type: string
              description: Resource reference of the resource impacted by the error
              example: P2PAY.1000
            resource_uid:
              type: string
              description: Supplied ID of the resource impacted by the error
              example: payment_34fj8djh2
    payto.account_identifiers_alias_abn:
      type: string
      title: ABN alias
      description: A PayID ABN alias
      example: '123456789'
      pattern: ^((\d{9})|(\d{11}))$
    payto.alias_resolution_abn_request:
      allOf:
      - type: object
        required:
        - type
        - value
        properties:
          type:
            type: string
            enum:
            - alias_phone
            - alias_email
            - alias_abn
            - alias_organisation_identifier
            example: alias_abn
          value:
            allOf:
            - $ref: '#/components/schemas/payto.account_identifiers_alias_abn'
      - $ref: '#/components/schemas/payto.alias_resolution_base_request'
    payto.unprocessable_alias_resolution_errors:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/payto.unprocessable_alias_resolution_error'
      required:
      - errors
    payto.unprocessable_alias_resolution_error:
      type: object
      additionalProperties: false
      required:
      - title
      - detail
      - code
      properties:
        title:
          type: string
          example: Title of error
        code:
          type: string
          description: A code assigned to the type of error received
          example: E100
          enum:
          - ZPUNP00
          - ZPUNP09
          - ZPADD01
          - ZPADD02
          - ZPADD03
          - ZPADD04
        detail:
          type: string
          description: A short description of the error
          example: Description of error
        links:
          type: object
          properties:
            about:
              type: string
              description: An optional link to more information on the error
              example: https://docs.zeptopayments.com/docs/zepto-environments
          required:
          - about
        meta:
          type: object
          description: Optional meta information about the error
          properties:
            resource_ref:
              type: string
              description: Resource reference of the resource impacted by the error
              example: P2PAY.1000
            resource_uid:
              type: string
              description: Supplied ID of the resource impacted by the error
              example: payment_34fj8djh2
    payto.generic_error:
      type: object
      additionalProperties: false
      properties:
        title:
          type: string
          example: Title of error
        detail:
          type: string
          description: A short description of the error
          example: Description of error
        links:
          type: object
          properties:
            about:
              type: string
              description: An optional link to more information on the error
              example: https://docs.zeptopayments.com/docs/zepto-environments
          required:
          - about
        meta:
          type: object
          description: Optional meta information about the error
          properties:
            resource_ref:
              type: string
              description: Resource reference of the resource impacted by the error
              example: P2PAY.1000
            resource_uid:
              type: string
              description: Supplied ID of the resource impacted by the error
              example: payment_34fj8djh2
      required:
      - title
      - detail
    payto.generic_errors:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/payto.generic_error'
      required:
      - errors
    payto.account_identifiers_alias_organisation_identifier:
      type: string
      title: Organisation alias
      description: A PayID organisation identifier alias
      example: Zepto Pty Ltd, Byron Bay NSW
      pattern: ^[!-@\[-~][ -@\[-~]{0,254}[!-@\[-~]$
    payto.account_identifiers_alias_email:
      type: string
      title: Email alias
      description: A PayID email alias
      example: default@example.com
      pattern: ^(?:[a-z0-9!#$%&'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+\/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$
    payto.account_identifiers_alias_phone:
      type: string
      title: Phone alias
      description: A PayID phone alias. e.g. +61-411222333
      example: +61-411222333
      pattern: ^\+[0-9]{1,3}-[1-9]{1,1}[0-9]{1,29}$
  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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
externalDocs:
  description: Zepto API v1.0
  url: https://docs.zeptopayments.com