--- updatedAt: 2025-09-23T21:14:21.000Z agentTools: projectIndex: https://developer.hellozai.com/llms.txt --- # Register PayID Register a _PayID_ for a given _Virtual Account_. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Virtual Accounts and PayIDs", "description": "Simplify payin reconciliations by creating a dedicated _Virtual Account_ for each user on your platform.\n\nEnhance the payments experience on your platform by registering a user friendly identifier, i.e. a _PayID_, for each user's _Virtual Account_. Your users should then be able to address payins using _PayIDs_ which are easier to remember and use than a BSB and account number.\n\nThis swagger document lists APIs for _Virtual Account_ and _PayID_ creation and management.\n", "contact": { "url": "https://developer.hellozai.com/reference/overview", "email": "support@hellozai.com" }, "version": "0.12-external" }, "servers": [ { "description": "Zai Prelive API", "url": "https://sandbox.au-0000.api.assemblypay.com" }, { "description": "Zai Production API", "url": "https://au-0000.api.assemblypay.com" } ], "paths": { "/virtual_accounts/{id}/pay_ids": { "post": { "tags": [ "PayIDs" ], "summary": "Register PayID", "description": "Register a _PayID_ for a given _Virtual Account_.", "operationId": "registerPayID", "parameters": [ { "name": "id", "in": "path", "description": "_Virtual Account_ ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "format": "uuid" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay_id_request" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay_id" }, "example": { "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc", "pay_id": "jsmith@mydomain.com", "type": "EMAIL", "status": "pending_activation", "created_at": "2020-04-27T20:28:22.378Z", "updated_at": "2020-04-27T20:28:22.378Z", "details": { "pay_id_name": "J Smith", "owner_legal_name": "Mr John Smith" }, "links": { "self": "/pay_ids/46deb476-c1a6-41eb-8eb7-26a695bbe5bc", "virtual_accounts": "/virtual_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inline_response_400_1" }, "examples": { "invalid_email_address": { "value": { "errors": { "pay_id": [ "pay_id should be a valid email address" ] } } }, "invalid_payid_domain": { "value": { "errors": { "pay_id": [ "invalid domain/sub-domain" ] } }, "description": "Provided domain is not registered with the marketplace." } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inline_response_401" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inline_response_403_va" }, "examples": { "Virtual Accounts unavailable": { "value": { "errors": { "virtual_accounts": [ "Feature not available" ] } } }, "PayID unavailable": { "value": { "errors": { "payid_per_user": [ "Feature not available" ] } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/virtual_account_not_found" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inline_response_409_1" }, "examples": { "Invalid Virtual Account Status": { "value": { "errors": "Virtual account must be active to register payid" } }, "Invalid PayID Status": { "value": { "errors": "Provided PayID is either pending activation or active already and associated with a virtual account" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inline_response_500" } } } } } } } }, "components": { "schemas": { "pay_id_request": { "required": [ "pay_id", "type", "details" ], "type": "object", "properties": { "pay_id": { "type": "string", "description": "The PayID that is being registered.", "format": "email", "example": "jsmith@mydomain.com", "maxLength": 256 }, "type": { "type": "string", "description": "The type of PayID being registered.", "enum": [ "EMAIL" ] }, "details": { "type": "object", "properties": { "pay_id_name": { "type": "string", "description": "Name that can be used to identify the entity registering the PayID.", "example": "J Smith", "minLength": 1, "maxLength": 140 }, "owner_legal_name": { "type": "string", "description": "The full legal account name.", "example": "Mr John Smith", "minLength": 1, "maxLength": 140 } } } } }, "pay_id": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc" }, "pay_id": { "type": "string", "format": "email", "example": "jsmith@mydomain.com" }, "type": { "type": "string", "enum": [ "EMAIL" ], "example": "EMAIL" }, "status": { "type": "string", "enum": [ "active", "activation_failed", "pending_activation", "deregistered" ], "example": "active" }, "created_at": { "type": "string", "format": "date-time", "example": "2020-04-27T20:28:22.378Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2020-04-27T20:28:22.378Z" }, "details": { "type": "object", "properties": { "pay_id_name": { "type": "string", "example": "J Smith" }, "owner_legal_name": { "type": "string", "example": "Mr John Smith" } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "/pay_ids/46deb476-c1a6-41eb-8eb7-26a695bbe5bc" }, "virtual_accounts": { "type": "string", "example": "/virtual_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc" } } } } }, "inline_response_400_1": { "properties": { "errors": { "type": "object" } } }, "inline_response_401": { "properties": { "errors": { "type": "string", "example": "Invalid or missing authorisation token" } } }, "inline_response_403_va": { "properties": { "errors": { "type": "object", "properties": { "virtual_accounts": { "type": "array", "items": { "type": "string", "example": "Feature not available" } } } } } }, "inline_response_409_1": { "properties": { "errors": { "type": "object", "properties": { "pay_id": { "type": "string", "example": "Provided PayID is either pending activation or active already and associated with a virtual account" } } } } }, "inline_response_500": { "properties": { "errors": { "type": "string", "example": "An error occurred processing your request. Please try again." } } }, "virtual_account_not_found": { "properties": { "errors": { "type": "string", "example": "Virtual Account does not exist." } } } } }, "x-explorer-enabled": false, "x-samples-languages": [ "curl", "c#", "ruby", "php", "javascript", "csharp", "go" ], "x-readme": { "proxy-enabled": true } } ```