Create payouts
/payoutsRaise a payout by hand, for the credential's own merchant.
Permissions
merchantFinancials:updateRequires the `update` action on `merchantFinancials` for the supplied runtime context
Request body
This body is a tagged shape: type is always "PayoutCmdCreateManual". Send it; more variants can be added, and a caller that switches on it keeps working when they are.
typetype = "PayoutCmdCreateManual"How much to pay out. Must be in a currency the merchant keeps books in.
typeenumrequiredIsoCurrencyAmountminorCurrencyUnitsinteger (int64)requiredThe amount in minor currency units (e.g. cents for AUD).
Example 1250
currencyIsoCurrencyrequiredThe currency of the given amount as a 3 letter ISO code.
AFNDZDARSAMDAWGAUDAZNBSDBHDTHB+156 moreShow fewer
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
statementDescriptorstringrequiredWhat the recipient sees on their bank statement.
Example ADA COFFEE
paymentChannelsarray of PayoutChannelWhich channels are acceptable, in preference order. NPP is near-instant and costs more.
DirectEntryNppUnknownexternalAccountIdXaccIdWhich account to pay into. Defaults to the merchant's primary; a 400 if neither is set.
Example xacc_9f2Kd8QpLzXw
feePayingMerchantIdMchtIdWhich merchant bears the payout fees. Defaults to the merchant being paid; naming another requires financials-update on it too.
Example mcht_9f2Kd8QpLzXw
curl -X POST https://api.tst.au.apgpay.dev/payouts \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "PayoutCmdCreateManual",
"amount": {
"type": "IsoCurrencyAmount",
"minorCurrencyUnits": 1250,
"currency": "AUD"
},
"statementDescriptor": "ADA COFFEE",
"paymentChannels": [
"DirectEntry"
],
"externalAccountId": "xacc_9f2Kd8QpLzXw",
"feePayingMerchantId": "mcht_9f2Kd8QpLzXw"
}'Responses
The response is a tagged shape: type is always "PayoutCreateRspAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.
typetype = "PayoutCreateRspAttributes"The resource that was created.
typeenumrequiredPayoutViewAttributespayoutIdPayoutIdrequiredIdentifier of a payout.
Example payout_9f2Kd8QpLzXw
referencestringThe reference the merchant sees, and the one that appears against the deposit. Set once the payout is raised.
Example your-own-reference
merchantIdMchtIdrequiredIdentifier of a merchant.
Example mcht_9f2Kd8QpLzXw
marketplaceIdMktpIdThe marketplace that merchant trades under, where it does.
Example mktp_9f2Kd8QpLzXw
enterpriseIdEntIdrequiredIdentifier of an enterprise.
Example ent_9f2Kd8QpLzXw
statusPayoutStatusrequiredWhere the payout is up to. This is the external status: a payout being retried reads as InTransit, not Pending.
CreatedPendingInTransitPaidCanceledFailedReversedSuspendedUnknownWhat the payout moved, and the merchant's balance either side of it. All in the single currency given here.
typeenumrequiredPayoutAmountsAttributescurrencyIsoCurrencyrequiredAFNDZDARSAMDAWGAUDAZNBSDBHDTHB+156 moreShow fewer
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
amountMinorUnitsrequiredWhat was paid out. May be negative where the payout is a reversal.
Example 1250
openingBalanceMinorUnitsrequiredThe merchant's balance before this payout.
Example 1250
closingBalanceMinorUnitsrequiredThe merchant's balance after it.
Example 1250
entryCountinteger (int64)requiredHow many journal entries were rolled into this payout, excluding the payout entry itself.
Example 42
When and how the payout settles.
typeenumrequiredPayoutSettlementAttributessettlementTypeMchtSettlementTyperequiredWhether platform fees are netted off each payout or invoiced separately.
NetGrossUnknownfacilitationPayoutFacilitationrequiredWho facilitates the payment, the platform's own funds flow, or a connected gateway account.
AbacusStripeConnectUnknownsettlementDatestring (date)The date the platform marked this payout ready to disburse. Not the same as a clearance date.
Example 2026-08-19
arrivedAtstring (date-time)When the destination bank acknowledged the funds. Absent until the payout clears.
Example 2026-08-19T04:21:07Z
Whether the platform raised this payout on a schedule or someone asked for it.
typeSomeone asked for this payout.
issuedBystringWho asked, as the platform recorded it.
The platform raised this payout on the merchant's schedule.
sequenceinteger (int64)The merchant's payout number, counting up. Absent on the very first payouts of a migrated merchant.
Example 1250
How the payment carrying this payout is going, or went.
typeenumrequiredPayoutDisbursementAttributesdisbursementIdPayoutDisbIdThe payment instruction the destination bank knows this payout by. Absent until one is issued.
Example disb_9f2Kd8QpLzXw
gatewayPayoutGatewayWhich provider is carrying it.
StripeConnectAuStripeConnectNzBnzSftpZeptoWestpacManualUnknownpriorityinteger (int32)Higher goes first when the platform batches. Set for scheduled payouts only.
Example 10
channelPayoutChannelThe channel actually used, once chosen.
DirectEntryNppUnknownrequestedChannelsarray of PayoutChannelThe channels the payout was raised asking for, in preference order.
DirectEntryNppUnknownrequiredbooleanrequiredWhether the platform issues the payment. false means the money moves outside the platform, so no instruction is ever issued.
Example true
Every attempt, in order. Empty until the first is made.
typeThe destination bank acknowledged the funds.
disbursementIdPayoutDisbIdrequiredIdentifier of a disbursement, the payment instruction carrying a payout.
Example disb_9f2Kd8QpLzXw
atstring (date-time)requiredExample 2026-08-19T04:21:07Z
The payment failed. The reason says whether the account can be used again.
disbursementIdPayoutDisbIdrequiredIdentifier of a disbursement, the payment instruction carrying a payout.
Example disb_9f2Kd8QpLzXw
gatewayPayoutGatewayWhich provider it failed on.
StripeConnectAuStripeConnectNzBnzSftpZeptoWestpacManualUnknownpriorityinteger (int32)requiredThe priority it was attempted at.
Example 10
externalAccountIdXaccIdThe account it was attempted to.
Example xacc_9f2Kd8QpLzXw
typeThe destination account has been closed.
detailstringrequiredpermanentbooleanrequiredExample true
The destination account does not exist.
detailstringrequiredpermanentbooleanrequiredExample true
The source account did not have the funds. Worth retrying.
detailstringrequiredpermanentbooleanrequiredExample true
The BSB is not a valid one.
detailstringrequiredpermanentbooleanrequiredExample true
The provider gave a reason the platform does not recognise. code and title are its own words.
codestringtitlestringdetailstringrequiredpermanentbooleanrequiredExample true
atstring (date-time)requiredExample 2026-08-19T04:21:07Z
A payment instruction was issued.
disbursementIdPayoutDisbIdrequiredIdentifier of a disbursement, the payment instruction carrying a payout.
Example disb_9f2Kd8QpLzXw
atstring (date-time)requiredExample 2026-08-19T04:21:07Z
A cleared payment was pulled back.
atstring (date-time)requiredExample 2026-08-19T04:21:07Z
externalAccountIdXaccIdThe bank account the payout was sent to. Absent where the payout is not disbursed by the platform.
Example xacc_9f2Kd8QpLzXw
Which stretch of the merchant's ledger this payout cleared. This is what makes a payout reproducible from the books.
typeenumrequiredPayoutLedgerClearanceAttributessystemLedgerIdstringrequiredThe ledger that was cleared to produce this payout.
firstSequenceinteger (int64)requiredSequence of the first ledger entry included.
Example 1250
lastSequenceinteger (int64)requiredSequence of the last ledger entry included.
Example 1250
statementDescriptorstringWhat the merchant asked to appear on the recipient's bank statement.
Example ADA COFFEE
narrativestringInternal notes on what the payout contains. Operational, not merchant-facing.
What the payout is made of, by entry type. Present on a by-id read; a page of payouts is not rolled up.
typeenumrequiredPayoutCompositionAttributescurrencyIsoCurrencyrequiredAFNDZDARSAMDAWGAUDAZNBSDBHDTHB+156 moreShow fewer
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
Entries that cleared out of the merchant's journal into this payout.
typeenumrequiredPayoutEntrySummaryAttributesentryTypestringrequiredWhat kind of movement, the platform's own vocabulary, which grows.
countinteger (int64)requiredHow many entries of this kind.
Example 42
amountMinorUnitsrequiredTheir net contribution, credits less debits, in the composition's currency. Negative for fees and deductions.
Example 1250
Entries added straight to the ledger, reversals and manual transfers, which never pass through a journal.
typeenumrequiredPayoutEntrySummaryAttributesentryTypestringrequiredWhat kind of movement, the platform's own vocabulary, which grows.
countinteger (int64)requiredHow many entries of this kind.
Example 42
amountMinorUnitsrequiredTheir net contribution, credits less debits, in the composition's currency. Negative for fees and deductions.
Example 1250
createdAtstring (date-time)requiredExample 2026-08-19T04:21:07Z
updatedAtstring (date-time)requiredExample 2026-08-19T04:21:07Z
{
"type": "PayoutCreateRspAttributes",
"created": {
"type": "PayoutViewAttributes",
"payoutId": "payout_9f2Kd8QpLzXw",
"reference": "your-own-reference",
"merchantId": "mcht_9f2Kd8QpLzXw",
"marketplaceId": "mktp_9f2Kd8QpLzXw",
"enterpriseId": "ent_9f2Kd8QpLzXw",
"status": "Created",
"amounts": {
"type": "PayoutAmountsAttributes",
"currency": "AUD",
"amount": 1250,
"openingBalance": 1250,
"closingBalance": 1250
},
"entryCount": 42,
"settlement": {
"type": "PayoutSettlementAttributes",
"settlementType": "Net",
"facilitation": "Abacus",
"settlementDate": "2026-08-19",
"arrivedAt": "2026-08-19T04:21:07Z"
},
"origin": {
"type": "PayoutOriginManual",
"issuedBy": "string"
},
"disbursement": {
"type": "PayoutDisbursementAttributes",
"disbursementId": "disb_9f2Kd8QpLzXw",
"gateway": "StripeConnectAu",
"priority": 10,
"channel": "DirectEntry",
"requestedChannels": [
"DirectEntry"
],
"required": true,
"attempts": [
{
"type": "PayoutAttemptCleared",
"disbursementId": "disb_9f2Kd8QpLzXw",
"at": "2026-08-19T04:21:07Z"
}
]
},
"externalAccountId": "xacc_9f2Kd8QpLzXw",
"ledgerClearance": {
"type": "PayoutLedgerClearanceAttributes",
"systemLedgerId": "string",
"firstSequence": 1250,
"lastSequence": 1250
},
"statementDescriptor": "ADA COFFEE",
"narrative": "string",
"composition": {
"type": "PayoutCompositionAttributes",
"currency": "AUD",
"journalEntries": [
{
"type": "PayoutEntrySummaryAttributes",
"entryType": "string",
"count": 42,
"amount": 1250
}
],
"ledgerEntries": [
{
"type": "PayoutEntrySummaryAttributes",
"entryType": "string",
"count": 42,
"amount": 1250
}
]
},
"createdAt": "2026-08-19T04:21:07Z",
"updatedAt": "2026-08-19T04:21:07Z"
}
}Error responses
statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}