PayID Payout Payload

Payment Method Identifier: PAY_ID
Payment Type: BANK_TRANSFER

PayID is an Australian bank-transfer method. It is available for AUD payouts through POST /api/v1/payouts/apm and pays to a PayID or to an Australian bank account.

A payout may require identity verification before it continues. The data PayID asks for is listed on PayID Identity Verification; the flow itself is described on Identity Verification.

Request Payload

Request Fields

Select a recipient with recipientType, or omit it: the payout then goes to the PayID when payId is sent and to the bank account otherwise. Fields of the other recipient type are ignored.

Note: Keep bsb and accountNumber as strings to preserve leading zeros.

Top-Level Fields

Field	Type	Required	Description
`callbackUrl`	String	No	Server-to-server webhook URL for the final transaction result.
`successRedirectUrl`	String	No	URL the customer returns to after completing the hosted step of the internal redirect flow.
`failureRedirectUrl`	String	No	URL the customer returns to after a failed or abandoned hosted step.

Billing Details (`ApmBillingDetails`)

Field	Type	Required	Description
`externalUserId`	String	Conditional	The customer identifier at the provider. Required unless `billingDetails.email` is sent; a request with neither is declined before it reaches the provider. Send the same value for every payment and payout of a customer. The provider keeps the verification status under this identifier, and a changed identifier is treated as a new customer.
`email`	String	Conditional	Used as the customer identifier when `externalUserId` is blank, with the same consequences for a change. Required unless `billingDetails.externalUserId` is sent.

Payload Fields (`apmPayload`)

Field	Type	Required	Description
`paymentMethod`	Enum	Yes	Must be `PAY_ID`.
`paymentType`	Enum	Yes	Must be `BANK_TRANSFER`.
`recipientType`	Enum	NO	`PAYID` or `BANK_ACCOUNT`.
`accountHolderName`	String	Yes	Recipient's full name, for both recipient types.
`payId`	String	For `PAYID`	Recipient's PayID, for example an email or phone number.
`bankName`	String	For `BANK_ACCOUNT`	Recipient's bank.
`bsb`	String	For `BANK_ACCOUNT`	Six-digit BSB.
`accountNumber`	String	For `BANK_ACCOUNT`	Recipient's account number.

{
  "paymentMethod": "PAY_ID",
  "paymentType": "BANK_TRANSFER",
  "recipientType": "BANK_ACCOUNT",
  "accountHolderName": "Alex Example",
  "bankName": "Example Bank",
  "bsb": "001234",
  "accountNumber": "00001234"
}

{
  "paymentMethod": "PAY_ID",
  "paymentType": "BANK_TRANSFER",
  "recipientType": "PAYID",
  "accountHolderName": "Alex Example",
  "payId": "[email protected]"
}

Direct Response

An accepted payout returns:

transactionStatus: PENDING
actionType: NONE
The provider's providerTransactionId

The funds are not confirmed until the payout becomes SUCCEED. Use the callback or payout info to obtain the final result.

{
  "requestId": "00000000-0000-4000-8000-000000000002",
  "transactionId": "123456790",
  "transactionStatus": "PENDING",
  "paymentType": "APM",
  "apmResponseData": {
    "paymentMethod": "PAY_ID",
    "paymentType": "BANK_TRANSFER",
    "actionType": "NONE",
    "providerTransactionId": "payout-1"
  }
}

Response Fields

Field	Type	Description
`paymentMethod`	Enum	Always `PAY_ID`.
`paymentType`	Enum	Always `BANK_TRANSFER`.
`actionType`	Enum	`NONE` — the payout is processed server-to-server, with no customer action.
`providerTransactionId`	String	Provider transaction identifier, when available.

Verification Response

When the customer must be verified before the payout continues, the response contains:

transactionStatus: CUSTOMER_VERIFICATION
actionType: KYC_REQUIRED
iframeUrl containing the hosted verification form

Collect the identity data using the hosted form or your own form and submit it to the KYC endpoint. The payout then continues and returns one of the responses described above.

See Identity Verification for the complete flow.

{
  "requestId": "00000000-0000-4000-8000-000000000002",
  "transactionId": "123456790",
  "transactionStatus": "CUSTOMER_VERIFICATION",
  "paymentType": "APM",
  "apmResponseData": {
    "paymentMethod": "PAY_ID",
    "paymentType": "BANK_TRANSFER",
    "actionType": "KYC_REQUIRED",
    "iframeUrl": "https://...",
    "customerInstructionsByLanguage": {
      "en": "Identity verification is required to continue this payout. Complete the form and submit your identity document."
    }
  }
}

Verification Response Fields

Field	Type	Description
`paymentMethod`	Enum	Always `PAY_ID`.
`paymentType`	Enum	Always `BANK_TRANSFER`.
`actionType`	Enum	`KYC_REQUIRED` while the payout waits for the customer's identity data.
`iframeUrl`	String	Hosted verification form to embed in an iframe.
`providerTransactionId`	String	Provider transaction identifier, when available.
`customerInstructionsByLanguage`	Object	Markdown instructions keyed by language.

Internal Redirect Response

If you cannot send the recipient fields, omit them and use the internal APM redirect flow.

The initial response has:

actionType: REDIRECTION

Redirect the customer to redirectUrl to continue the same transaction.

The customer enters the recipient type and its fields on Facilero's page. Fields that you already sent are not requested again.

{
  "paymentMethod": "PAY_ID",
  "paymentType": "BANK_TRANSFER",
  "actionType": "REDIRECTION",
  "redirectUrl": "https://checkout.example.com/?token=..."
}