Exirom Payment API Documentation

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 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. 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`. When omitted, `PAYID` if `payId` is sent, otherwise `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": "PAYID",
  "accountHolderName": "Alex Example",
  "payId": "alex@example.com"
}

#Direct Response

An accepted payout returns transactionStatus: PENDING with actionType: NONE and the provider's providerTransactionId. The funds are not confirmed until the payout becomes SUCCEED; use the callback or payout info for 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 is transactionStatus: CUSTOMER_VERIFICATION with actionType: KYC_REQUIRED and an iframeUrl holding the hosted verification form. Collect the identity data with that form or with your own, and submit it to the KYC endpoint; the payout then continues and returns one of the responses above. See Identity Verification.

{
  "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	The 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 Exirom's page, and fields you already sent are not asked again.

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

#See Also

APM Payout API — Full request and response schema
APM Payout Flow — End-to-end payout handling
PayID Payment Payload — PayID payment fields
PayID Identity Verification — The identity data PayID requires