---
updatedAt: 2026-04-20T20:32:06.000Z
agentTools:
  projectIndex: https://docs.zeptopayments.com/llms.txt
---

# resolve

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.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Zepto PayTo API",
    "version": "20260901",
    "description": "Documentation for the Zepto PayTo API.",
    "termsOfService": "https://www.zepto.com.au/customer-terms",
    "contact": {
      "email": "support@zepto.com.au"
    }
  },
  "tags": [
    {
      "name": "Alias Resolution",
      "description": "Resolve the display name associated with a PayID alias"
    }
  ],
  "externalDocs": {
    "description": "Zepto API v1.0",
    "url": "https://docs.zeptopayments.com"
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/payto/alias_resolution": {
      "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"
                    }
                  }
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "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"
          },
          "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"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error"
          },
          "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"
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "$ref": "#/components/schemas/payto.alias_resolution_request"
              }
            }
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/ZeptoAPIVersion"
        }
      ]
    }
  },
  "servers": [
    {
      "description": "Zepto Sandbox",
      "url": "https://api.sandbox.zeptopayments.com"
    },
    {
      "description": "Zepto Production",
      "url": "https://api.zeptopayments.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "parameters": {
      "ZeptoAPIVersion": {
        "name": "Zepto-API-Version",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^\\d{8}$",
          "default": "20250101",
          "example": "20260901"
        },
        "description": "API version in YYYYMMDD format. Defaults to 20250101 (legacy) when omitted."
      }
    },
    "schemas": {
      "payto.account_identifiers_alias_abn": {
        "type": "string",
        "title": "ABN alias",
        "description": "A PayID ABN alias",
        "example": "123456789",
        "pattern": "^((\\d{9})|(\\d{11}))$"
      },
      "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_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_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}$"
      },
      "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_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.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_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_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_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.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.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.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.unprocessable_alias_resolution_errors": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/payto.unprocessable_alias_resolution_error"
            }
          }
        },
        "required": [
          "errors"
        ]
      }
    }
  }
}
```