PayID Payment Payload

Request and response payloads for Australian PayID payments.

• Payment method identifier: PAY_ID
• Payment type: BANK_TRANSFER
• Currency: AUD
• Endpoint: POST /api/v1/payments/apm

PayID is an Australian bank-transfer payment method. The merchant creates the payment and always redirects the customer to the hosted URL returned in the response. For REDIRECTION, use redirectUrl. For KYC_REQUIRED, use iframeUrl.

Facilero manages the customer journey, including collecting any missing information, completing identity verification when required, and displaying bank details and payment instructions. All KYC is handled by Facilero within the hosted flow.

Payment Flow

1. Create a PayID payment through POST /api/v1/payments/apm.
2. Check actionType and redirect the customer to the corresponding hosted URL: redirectUrl for REDIRECTION, or iframeUrl for KYC_REQUIRED.
3. The customer completes any required information and identity verification on Facilero's hosted page.
4. Facilero displays the receiving bank details, payment reference, amount, and payment instructions.
5. The customer transfers the money from their banking app, entering the payment reference exactly as shown.
6. Use the callback or payment info to obtain the final transaction result.

Every payment requires the customer redirect, including payments for customers who have already completed verification.

Request Payload

Top-Level Fields

Billing Details (billingDetails)

Keep the customer identifier consistent. The provider stores verification status under this identifier; changing it creates a new customer identity at the provider.

Payload Fields (apmPayload)

The first PayID payment requires the customer's account holder name and date of birth. The customer must be at least 18 years old. Facilero collects missing information on its hosted page; information already supplied is not requested again.

Billing first and last names are not sent to the provider. The provider receives the name supplied in accountHolderName or collected during the hosted flow.

apmPayload Example

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

Redirect Response

When the payment is ready for the hosted flow, the response contains actionType: REDIRECTION and a redirectUrl.

For REDIRECTION, redirect the customer to redirectUrl to continue the same transaction. If the response contains KYC_REQUIRED, follow the verification response instructions below. The merchant must redirect the customer to the hosted flow in either case.

Redirect Response Data Example

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

Redirect Response Fields

Identity Verification

Facilero handles all identity verification within the hosted payment flow. When verification is required, Facilero guides the customer through the required steps and continues the payment once verification allows it.

Verification Response

When the payment requires identity verification, the response contains:

• transactionStatus: CUSTOMER_VERIFICATION
• actionType: KYC_REQUIRED
• iframeUrl: the hosted verification URL

KYC_REQUIRED remains the action type for this response. Redirect the customer to the URL in iframeUrl. Facilero collects the required identity data and documents and handles verification within the hosted flow.

Verification Response Example

{
  "requestId": "00000000-0000-4000-8000-000000000001",
  "transactionId": "123456789",
  "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 payment. Complete the form and submit your identity document."
    }
  }
}

Verification Response Fields

After the hosted flow, obtain the final payment result through the callback or payment info.

Payment Result

Displaying bank details, completing identity verification, or returning the customer to the merchant does not confirm a successful payment.

The payment becomes SUCCEED when the provider confirms the transfer. Use the callback or payment info as the source of the final transaction result.

If the provider confirms an amount different from the requested amount:

• processedAmount contains the confirmed amount.
• orderAmount remains unchanged.

Important — customer credit: Once the payment is confirmed as SUCCEED, credit the customer based on processedAmount, the amount confirmed as received. Do not use the requested orderAmount to determine the amount to credit. If these amounts differ, processedAmount is the amount that must be granted to the customer.

Declines

If the provider has no receiving account available, the payment is declined with 81 (GATEWAY_LIMIT_EXCEEDED). A later payment may succeed.

A first payment with an invalid date of birth or a customer under 18 is declined with 62; the response includes the reason.

A payment declined before transfer details exist returns:

• actionType: NONE
• transactionStatus: FAILED
• A decline code
• No references

See Also

• APM Payment API — Full request and response schema
• Payment Flow — End-to-end payment handling
• PayID Payout Payload — PayID payout fields