PayTo Alias Resolution Overview

The PayTo Alias Resolution endpoint is a compulsory service that must be utilised before establishing a PayTo agreement when PayID is used as an account_identifier type such as alias_phone, alias_email, alias_abn, and alias_organisation_identifier.

The service offers two primary benefits:

Enhanced confidence: Provide real-time PayID validation feedback during the checkout process, increasing confidence in the transaction's accuracy.
Fraud prevention: Mitigate illegitimate activity by leveraging Zepto's integrated fraud prevention measures.

Implementation Guidelines

A PayTo agreement creation request should only be initiated once the PayID has successfully been validated (i.e. 200 response from POST /payto/alias_resolution)
- A PayTo agreement creation request should not be initiated should the alias resolution request return any other response (i.e. 4XX or 5XX)
The "display_name" associated with a registered PayID is provided in the 200 response and can be used as validation against your customer record prior to creating a PayTo agreement
- The "display_name" should not be displayed to the end customer

CX Guidelines

The merchant application should provide real-time visual feedback to the customer to confirm the validity of the PayID
- The "display_name" associated with the PayID included in the 200 response should not be displayed to the end customer
Only once the PayID has been validated can the customer finalise the checkout process

API Documentation

Initiating a Lookup

To make use of this function please enable the pay_to_aliases scope within your Zepto API settings.

Parameters

When initiating an alias lookup, you’ll need to specify the following request parameters:

Parameters	Description
`type`* (required)	Select from 4 alias types: `alias_phone` `alias_email` `alias_abn` `alias_organisation_identifier`
`value`* (required)	The value of the PayID (e.g. `+61-123456789`)
`requester`: `id`* (required)	A unique identifier of the end customer.
`requester`: `remote_ip`* (required)	The IP address of the end customer.

Requester Information

The requester object (i.e. id and remote_ip) is used to collect the details of the end-user requesting this resolution. This is done as an integral component of Zepto's strategy for preventing fraudulent activities and safeguarding against enumeration attacks, ultimately ensuring the security of the end customer's data. Zepto will be able to provide further details around fraud prevention and usage limits during technical discussions.

Endpoint

POST /payto/alias_resolution

Request Payload

{
  "type": "alias_phone",
  "value": "+61-411222333",
  "requester": {
    "id": "user_G7MQWwkQZIP8vbfH",
    "remote_ip": "192.0.2.146"
  }
}

Response

Upon submission, a response will show one of the following:

Successful: 201 response
Failed:
- 400: Bad request
- 422: Unprocessable entity

201: Successful Response Sample

{
  "data": {
    "display_name": "Jane Smith"
  }
}

Notable Fields

Field	Description
`display_name`	Display name associated with the alias.

400: Bad Request

{
  "errors": [
    {
      "title": "Validation Failed",
      "detail": "The value for `alias_owner` is not allowed"
    }
  ]
}

422: Unprocessable Entity Sample

When an alias resolution request is submitted and fails (eg. alias does not exist or the fraud prevention limits have been reached), Zepto will return a (422) response detailing any errors responsible for the invalid request.

{
  "errors": [
    {
      "title": "Alias not found",
      "detail": "The given alias was not able to be resolved",
      "code": "ZPADD01"
    }
  ]
}

Notable Fields

Field	Description
`title`	Error title
`detail`	Error description
`code`	Error code