Create beneficial owners
/beneficial-ownersAdd a beneficial owner to a merchant. The platform verifies them; the response says how far it got.
Permissions
merchantKyb:createRequires the `create` action on `merchantKyb` for the supplied runtime context
Request body
This body is a tagged shape: type is always "PsonCmdCreate". Send it; more variants can be added, and a caller that switches on it keeps working when they are.
typetype = "PsonCmdCreate"merchantIdMchtIdrequiredIdentifier of a merchant.
Example mcht_9f2Kd8QpLzXw
What is known about a beneficial owner.
typeenumrequiredPsonProfileAttributestitlestringrequiredTheir title in relation to the business, Director, Secretary.
rolesarray of PsonRoleWhat they are to the business. At least one.
DirectorOwnerExecutiveUnknowngivenNamestringrequiredExample Ada Lovelace
middleNamestringExample Ada Lovelace
familyNamestringrequiredExample Ada Lovelace
dateOfBirthstring (date)requiredDate of birth, ISO 8601.
Example 2026-08-19
A postal address.
typeenumrequiredPsonAddressAttributesunitNumberstringUnit, shop or level, as written on the building. Free text, 12, Shop 4, Level 3. Omit where there is none.
streetNumberstringrequiredStreet number, including any range or letter, 34, 34A, 34-36.
streetNamestringrequiredStreet name, without the type, Smith, not Smith Street.
Example Ada Lovelace
streetTypestringStreet, Road, Avenue. Optional because not every address has one.
suburbstringSuburb. This is where Australia and South Africa keep what other countries call the city.
citystringCity. Required in New Zealand. In Australia and South Africa send suburb instead, the platform moves whichever you send to where that country keeps it.
statestringState, province or territory. Required in Australia.
postalCodestringrequiredExample 3000
countrystringrequiredISO 3166-1 alpha-2.
Example AU
emailAddressstringrequiredExample ada@example.com
phoneNumberstringrequiredPhone number in E.164 format, such as +61400000000.
Example +61400000000
Documents offered as evidence of identity. The platform holds at most one of each kind, so this is one, or a passport and a licence. Omit where there are none.
typeA driver licence. Which extra number is required follows from the issuing country.
numberstringrequiredissuingCountrystringrequiredISO 3166-1 alpha-2 country that issued it.
Example AU
issuingRegionstringState or territory that issued it. Required in Australia.
documentNumberstringThe card's document number. Required for an Australian licence.
versionNumberstringThe licence's version number. Required for a New Zealand licence.
A passport. The expiry is checked, an expired one fails verification.
numberstringrequiredissuingCountrystringrequiredISO 3166-1 alpha-2 country that issued it.
Example AU
expiresOnstring (date)requiredWhen it expires. The platform refuses an expired passport.
Example 2026-08-19
The scan of an identity document, by fileId from the files collection. Absent until one is uploaded.
typeenumrequiredPsonVerificationDocAttributesidTypePsonDocumentTyperequiredWhich document was scanned. A driver licence needs both sides; a passport needs only the front.
PassportDriverLicenceUnknownfrontFileIdstringrequiredThe front of the document, by fileId.
Example lfile_9f2Kd8QpLzXw
backFileIdstringThe back of the document, by fileId. Required for a driver licence.
Example lfile_9f2Kd8QpLzXw
curl -X POST https://api.tst.au.apgpay.dev/beneficial-owners \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "PsonCmdCreate",
"merchantId": "mcht_9f2Kd8QpLzXw",
"profile": {
"type": "PsonProfileAttributes",
"title": "string",
"roles": [
"Director"
],
"givenName": "Ada Lovelace",
"middleName": "Ada Lovelace",
"familyName": "Ada Lovelace",
"dateOfBirth": "2026-08-19",
"address": {
"type": "PsonAddressAttributes",
"unitNumber": "string",
"streetNumber": "string",
"streetName": "Ada Lovelace",
"streetType": "string",
"suburb": "string",
"city": "string",
"state": "string",
"postalCode": "3000",
"country": "AU"
},
"emailAddress": "ada@example.com",
"phoneNumber": "+61400000000",
"identityDocuments": [
{
"type": "PsonDocumentDriverLicence",
"number": "string",
"issuingCountry": "AU",
"issuingRegion": "string",
"documentNumber": "string",
"versionNumber": "string"
}
],
"verificationDocument": {
"type": "PsonVerificationDocAttributes",
"idType": "Passport",
"frontFileId": "lfile_9f2Kd8QpLzXw",
"backFileId": "lfile_9f2Kd8QpLzXw"
}
}
}'Responses
The response is a tagged shape: type is always "PsonCreateRspAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.
typetype = "PsonCreateRspAttributes"The resource that was created.
typeenumrequiredPsonViewAttributesbeneficialOwnerIdPsonIdrequiredIdentifier of a person. A beneficial owner is a person, so it is identified by its person's identifier.
Example pson_9f2Kd8QpLzXw
merchantIdMchtIdrequiredWhose owner this is. Not on PersonInfo, the read already knows, because it was asked for one merchant.
Example mcht_9f2Kd8QpLzXw
What is known about a beneficial owner.
typeenumrequiredPsonProfileAttributestitlestringrequiredTheir title in relation to the business, Director, Secretary.
rolesarray of PsonRoleWhat they are to the business. At least one.
DirectorOwnerExecutiveUnknowngivenNamestringrequiredExample Ada Lovelace
middleNamestringExample Ada Lovelace
familyNamestringrequiredExample Ada Lovelace
dateOfBirthstring (date)requiredDate of birth, ISO 8601.
Example 2026-08-19
A postal address.
typeenumrequiredPsonAddressAttributesunitNumberstringUnit, shop or level, as written on the building. Free text, 12, Shop 4, Level 3. Omit where there is none.
streetNumberstringrequiredStreet number, including any range or letter, 34, 34A, 34-36.
streetNamestringrequiredStreet name, without the type, Smith, not Smith Street.
Example Ada Lovelace
streetTypestringStreet, Road, Avenue. Optional because not every address has one.
suburbstringSuburb. This is where Australia and South Africa keep what other countries call the city.
citystringCity. Required in New Zealand. In Australia and South Africa send suburb instead, the platform moves whichever you send to where that country keeps it.
statestringState, province or territory. Required in Australia.
postalCodestringrequiredExample 3000
countrystringrequiredISO 3166-1 alpha-2.
Example AU
emailAddressstringrequiredExample ada@example.com
phoneNumberstringrequiredPhone number in E.164 format, such as +61400000000.
Example +61400000000
Documents offered as evidence of identity. The platform holds at most one of each kind, so this is one, or a passport and a licence. Omit where there are none.
typeA driver licence. Which extra number is required follows from the issuing country.
numberstringrequiredissuingCountrystringrequiredISO 3166-1 alpha-2 country that issued it.
Example AU
issuingRegionstringState or territory that issued it. Required in Australia.
documentNumberstringThe card's document number. Required for an Australian licence.
versionNumberstringThe licence's version number. Required for a New Zealand licence.
A passport. The expiry is checked, an expired one fails verification.
numberstringrequiredissuingCountrystringrequiredISO 3166-1 alpha-2 country that issued it.
Example AU
expiresOnstring (date)requiredWhen it expires. The platform refuses an expired passport.
Example 2026-08-19
The scan of an identity document, by fileId from the files collection. Absent until one is uploaded.
typeenumrequiredPsonVerificationDocAttributesidTypePsonDocumentTyperequiredWhich document was scanned. A driver licence needs both sides; a passport needs only the front.
PassportDriverLicenceUnknownfrontFileIdstringrequiredThe front of the document, by fileId.
Example lfile_9f2Kd8QpLzXw
backFileIdstringThe back of the document, by fileId. Required for a driver licence.
Example lfile_9f2Kd8QpLzXw
The outcome of verifying a beneficial owner.
typeenumrequiredPsonVerificationAttributesstatusPsonVerificationStatusrequiredPendingVerifiedUnknownerrorCodesarray of stringWhy verification has not completed, as codes, InvalidPersonAge, InvalidContactEmail. Branch on these.
detailsarray of stringThe same thing in words, for showing a person. Not always populated even when errorCodes is.
deletablebooleanrequiredWhether this owner can be removed. The platform decides; the last owner of a verified merchant cannot.
Example true
{
"type": "PsonCreateRspAttributes",
"created": {
"type": "PsonViewAttributes",
"beneficialOwnerId": "pson_9f2Kd8QpLzXw",
"merchantId": "mcht_9f2Kd8QpLzXw",
"profile": {
"type": "PsonProfileAttributes",
"title": "string",
"roles": [
"Director"
],
"givenName": "Ada Lovelace",
"middleName": "Ada Lovelace",
"familyName": "Ada Lovelace",
"dateOfBirth": "2026-08-19",
"address": {
"type": "PsonAddressAttributes",
"unitNumber": "string",
"streetNumber": "string",
"streetName": "Ada Lovelace",
"streetType": "string",
"suburb": "string",
"city": "string",
"state": "string",
"postalCode": "3000",
"country": "AU"
},
"emailAddress": "ada@example.com",
"phoneNumber": "+61400000000",
"identityDocuments": [
{
"type": "PsonDocumentDriverLicence",
"number": "string",
"issuingCountry": "AU",
"issuingRegion": "string",
"documentNumber": "string",
"versionNumber": "string"
}
],
"verificationDocument": {
"type": "PsonVerificationDocAttributes",
"idType": "Passport",
"frontFileId": "lfile_9f2Kd8QpLzXw",
"backFileId": "lfile_9f2Kd8QpLzXw"
}
},
"verification": {
"type": "PsonVerificationAttributes",
"status": "Pending",
"errorCodes": [
"string"
],
"details": [
"string"
]
},
"deletable": true
}
}Error responses
statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}