APG PayAPG Paydocs

Merchants

Create external accounts

POST/external-accounts

Add a bank account the merchant can be paid out to.

Permissions

Required permission
merchantFinancials:create

Requires the `create` action on `merchantFinancials` for the supplied runtime context

Request body

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

Discriminated by type
type = "XaccCmdCreate"
merchantIdMchtIdrequired

Whose account this is. The platform's operation is merchant-scoped and cannot resolve one otherwise.

Example mcht_9f2Kd8QpLzXw

accountNamestringrequired

Name of the person or business that holds the account.

Example Ada Lovelace

bankNamestring

Name of the financial institution.

Example Ada Lovelace

accountNumberstringrequired

Write-only. Digits only, and only the last four are ever returned.

routingNumberstringrequired

Bank-state-branch for Australian accounts, six digits. Leave blank for New Zealand.

countrystringrequired

Two-letter country code the account is held in. Not derivable from the currency.

Example AU

currencyIsoCurrencyrequired
AFNDZDARSAMDAWGAUDAZNBSDBHDTHB
+156 more

PAB, BBD, BYR, BZD, BMD, VEF, BOB, BRL, BND, BGN, BIF, CAD, CVE, KYD, XOF, XAF, XPF, CLP, COP, KMF, CDF, BAM, NIO, CRC, HRK, CUP, CZK, GMD, DKK, MKD, DJF, STD, DOP, VND, XCD, EGP, SVC, ETB, EUR, FKP, FJD, HUF, GHS, GIP, HTG, PYG, GNF, GYD, HKD, UAH, ISK, INR, IRR, IQD, JMD, JOD, KES, PGK, LAK, KWD, MWK, AOA, MMK, GEL, LBP, ALL, HNL, SLL, LRD, LYD, SZL, LSL, MGA, MYR, MUR, MXN, MXV, MDL, MAD, MZN, BOV, NGN, ERN, NAD, NPR, ANG, ILS, TWD, NZD, BTN, KPW, NOK, PEN, MRU, PKR, MOP, TOP, CUC, UYU, PHP, GBP, BWP, QAR, GTQ, ZAR, OMR, KHR, RON, MVR, IDR, RUB, RWF, SHP, SAR, RSD, SCR, SGD, SBD, KGS, SOS, TJS, SSP, LKR, SDG, SRD, SEK, CHF, SYP, BDT, WST, TZS, KZT, TTD, MNT, TND, TRY, TMT, AED, UGX, COU, CLF, UYI, USD, USN, USS, UZS, VUV, CHE, CHW, KRW, YER, JPY, CNY, ZMW, ZWL, PLN

primarybooleanrequired

Whether payouts in this currency should go to this account. Required: the platform defaults it to true, which silently redirects a merchant's payouts.

Example true

referencestring

Your own reference for this account. Must be unique for the merchant.

Example your-own-reference

requesterIdstring

Who is asking. Required where the merchant's policy verifies accounts, because the verification is recorded against a person.

curl -X POST https://api.tst.au.apgpay.dev/external-accounts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "XaccCmdCreate",
  "merchantId": "mcht_9f2Kd8QpLzXw",
  "accountName": "Ada Lovelace",
  "bankName": "Ada Lovelace",
  "accountNumber": "string",
  "routingNumber": "string",
  "country": "AU",
  "currency": "AUD",
  "primary": true,
  "reference": "your-own-reference",
  "requesterId": "string"
}'

Responses

The response is a tagged shape: type is always "XaccCreateRspAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.

Discriminated by type
type = "XaccCreateRspAttributes"

The resource that was created.

Example
{
  "type": "XaccCreateRspAttributes",
  "created": {
    "type": "XaccViewAttributes",
    "externalAccountId": "xacc_9f2Kd8QpLzXw",
    "merchantId": "mcht_9f2Kd8QpLzXw",
    "reference": "your-own-reference",
    "accountName": "Ada Lovelace",
    "bankName": "Ada Lovelace",
    "routingNumber": "string",
    "last4": "4242",
    "country": "AU",
    "currency": "AUD",
    "status": "Pending",
    "blockReason": "Requested by the customer.",
    "primary": true,
    "verified": true,
    "verification": {
      "type": "XaccVerificationAttributes",
      "outcome": "Match",
      "matchedName": "Ada Lovelace",
      "message": "string",
      "provider": "string",
      "failureMessage": "string",
      "verifiedAt": "2026-08-19T04:21:07Z"
    },
    "createdAt": "2026-08-19T04:21:07Z",
    "updatedAt": "2026-08-19T04:21:07Z"
  }
}

Error responses