APG PayAPG Paydocs

Merchants

Replace beneficial owner

PUT/beneficial-owners/{beneficialOwnerId}

Replace everything known about an owner. Whole, not partial, and it names the merchant, because the platform needs one.

Permissions

Required permission
merchantKyb:update

Requires the `update` action on `merchantKyb` for the supplied runtime context

Path parameters

beneficialOwnerIdstring
required

Request body

This body is a tagged shape: type is always "PsonReplaceProfile". Send it; more variants can be added, and a caller that switches on it keeps working when they are.

Discriminated by type
type = "PsonReplaceProfile"
merchantIdMchtIdrequired

Whose owner this is. Required, the platform cannot resolve an owner without its merchant.

Example mcht_9f2Kd8QpLzXw

What is known about a beneficial owner.

curl -X PUT https://api.tst.au.apgpay.dev/beneficial-owners/{beneficialOwnerId} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "PsonReplaceProfile",
  "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 "PsonViewAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.

Discriminated by type
type = "PsonViewAttributes"
beneficialOwnerIdPsonIdrequired

Identifier of a person. A beneficial owner is a person, so it is identified by its person's identifier.

Example pson_9f2Kd8QpLzXw

merchantIdMchtIdrequired

Whose 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.

The outcome of verifying a beneficial owner.

deletablebooleanrequired

Whether this owner can be removed. The platform decides; the last owner of a verified merchant cannot.

Example true

Example
{
  "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