Update merchant invoice
/merchant-invoices/{merchantInvoiceId}Record an out-of-band payment, resend the invoice by email, or push it through a billing run. Selected by the body's type.
MinvUpdateMarkPaidMinvUpdateProcessMinvUpdateResendEmailPermissions
Required action depends on the request variant. Select a variant in the request body below to see the permission it requires.
Path parameters
merchantInvoiceIdstringRequest body
This body is a typed union. Pick a variant to see its fields, the permission it requires, and a matching example.
typetype = "MinvUpdateMarkPaid"Record an out-of-band payment
amountCreditedMinorUnitsHow much to credit, in minor units of the invoice's currency. Omit to credit the whole outstanding amount. A part payment leaves the invoice unpaid.
Example 1250
curl -X PATCH https://api.tst.au.apgpay.dev/merchant-invoices/{merchantInvoiceId} \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "MinvUpdateMarkPaid",
"amountCredited": 1250
}'Responses
The response is a tagged shape: type is always "MinvUpdateRspAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.
typetype = "MinvUpdateRspAttributes"The resource as it stands after the change.
typeenumrequiredMinvViewAttributesmerchantInvoiceIdMinvIdrequiredIdentifier of a merchant invoice.
Example minv_9f2Kd8QpLzXw
referencestringrequiredThe reference a payer quotes. Derived from the identifier, and the two convert both ways.
Example your-own-reference
payerMerchantIdMchtIdrequiredThe merchant being billed.
Example mcht_9f2Kd8QpLzXw
payerNamestringrequiredBusiness name of the merchant billed, so a listing reads without a second call.
Example Ada Lovelace
payeeMerchantIdMchtIdrequiredThe merchant receiving the funds. Usually the platform's own; a marketplace that self-manages gross settlement is its own payee.
Example mcht_9f2Kd8QpLzXw
payerMarketplaceIdMktpIdThe marketplace the payer trades under, where it does.
Example mktp_9f2Kd8QpLzXw
payerEnterpriseIdEntIdrequiredIdentifier of an enterprise.
Example ent_9f2Kd8QpLzXw
statusMinvStatusrequiredDraftOutstandingNearDueDueOverduePaidCancelledDefaultedUnknownWhat is owed on the invoice and what has been paid. All in the single currency given here.
typeenumrequiredMinvAmountsAttributescurrencyIsoCurrencyrequiredAFNDZDARSAMDAWGAUDAZNBSDBHDTHB+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
invoicedMinorUnitsrequiredThe invoice total.
Example 1250
paidMinorUnitsrequiredCredited towards it so far.
Example 1250
outstandingMinorUnitsrequiredStill owing. invoiced less paid.
Example 1250
periodStartstring (date)requiredFirst day of the period billed.
Example 2026-08-19
periodEndstring (date)requiredLast day of the period billed.
Example 2026-08-19
dueDatestring (date)requiredWhen payment falls due.
Example 2026-08-19
issuedOnstring (date)When the invoice was issued to the payer. Absent while the invoice is a draft.
Example 2026-08-19
narrativestringrequiredWhat the invoice covers, in words.
orderIdstringThe order raised to represent payment of this invoice. Read it to see how payment is going.
Example ordr_9f2Kd8QpLzXw
Which stretch of the payer's ledger this invoice cleared, so the total is reproducible from the books.
typeenumrequiredMinvLedgerClearanceAttributessystemLedgerIdstringrequiredfirstSequenceinteger (int64)requiredSequence of the first ledger entry included.
Example 1250
lastSequenceinteger (int64)requiredSequence of the last ledger entry included.
Example 1250
Every attempt at paying this invoice, in order. Empty where none has been made.
typeThe platform stopped retrying an automatic payment.
atstring (date-time)requiredExample 2026-08-19T04:21:07Z
summarystringrequiredAn automatic payment was refused.
atstring (date-time)requiredExample 2026-08-19T04:21:07Z
summarystringrequiredThe invoice was settled from the payer's credit balance rather than a payment.
atstring (date-time)requiredExample 2026-08-19T04:21:07Z
summarystringrequiredAn automatic payment was started, a direct debit, typically, and has not resolved.
atstring (date-time)requiredExample 2026-08-19T04:21:07Z
summarystringrequiredSomeone recorded that the invoice was settled outside the platform.
atstring (date-time)requiredExample 2026-08-19T04:21:07Z
summarystringrequiredAn automatic payment succeeded.
atstring (date-time)requiredExample 2026-08-19T04:21:07Z
amountPaidMinorUnitsrequiredHow much was taken.
Example 1250
newStatusMinvStatusrequiredThe status the invoice moved to. A part payment does not reach Paid.
DraftOutstandingNearDueDueOverduePaidCancelledDefaultedUnknownsummarystringrequiredThe lines that make up the invoice. Present on a by-id read; a listing is not itemised.
typeenumrequiredMinvItemAttributesitemTypeMinvItemTyperequiredPayInFullFeePayPlanFeePaymentFeeReversalDisputeFeeDisputeFeeReversalManualTopUpManualTopUpReversalTransactionTransferFeeReversalOverdueInvoiceFeeOther+1 moreShow fewer
Unknown
categorystringWhich payment product the line covers, where the item type has one.
categoryLabelstringThat category in words, for printing.
unitPricestringWhat one of these costs, as printed. A rate rather than an amount, 1.75% + $0.30, so it is a string.
countinteger (int64)requiredHow many of them.
Example 42
transactionValueMinorUnitsThe value of the transactions this line covers, where the line is charged on transaction value.
Example 1250
feesMinorUnitsrequiredFees charged on the line, excluding tax.
Example 1250
taxMinorUnitsrequiredTax charged on those fees.
Example 1250
Who the invoice is addressed to. Present on a by-id read.
typeenumrequiredMinvBillingAttributesbusinessNamestringrequiredExample Ada Lovelace
taxIdstringrequiredemailAddressstringrequiredExample ada@example.com
phoneNumberstringrequiredPhone number in E.164 format.
Example +61400000000
A postal address.
typeenumrequiredPsonAddressAttributesunitNumberstringUnit, shop or level, as written on the building. Free text, 12, Shop 4, Level 3. Omit where there is none.
streetNumberstringrequiredStreet number, including any range or letter, 34, 34A, 34-36.
streetNamestringrequiredStreet name, without the type, Smith, not Smith Street.
Example Ada Lovelace
streetTypestringStreet, Road, Avenue. Optional because not every address has one.
suburbstringSuburb. This is where Australia and South Africa keep what other countries call the city.
citystringCity. Required in New Zealand. In Australia and South Africa send suburb instead, the platform moves whichever you send to where that country keeps it.
statestringState, province or territory. Required in Australia.
postalCodestringrequiredExample 3000
countrystringrequiredISO 3166-1 alpha-2.
Example AU
How a person can pay this invoice by hand. Present on a by-id read, where the platform issued a link.
typeenumrequiredMinvManualPaymentAttributestokenstringrequiredAuthorises the holder to pay this invoice. Valid for 28 days.
Example tok_9f2Kd8QpLzXwR4mN
paymentUrlstringrequiredWhere to send a person to pay it. Carries the token.
Example https://example.com/callback
orderIdstringrequiredThe order that represents payment of this invoice.
Example ordr_9f2Kd8QpLzXw
createdAtstring (date-time)requiredExample 2026-08-19T04:21:07Z
updatedAtstring (date-time)requiredExample 2026-08-19T04:21:07Z
{
"type": "MinvUpdateRspAttributes",
"updated": {
"type": "MinvViewAttributes",
"merchantInvoiceId": "minv_9f2Kd8QpLzXw",
"reference": "your-own-reference",
"payerMerchantId": "mcht_9f2Kd8QpLzXw",
"payerName": "Ada Lovelace",
"payeeMerchantId": "mcht_9f2Kd8QpLzXw",
"payerMarketplaceId": "mktp_9f2Kd8QpLzXw",
"payerEnterpriseId": "ent_9f2Kd8QpLzXw",
"status": "Draft",
"amounts": {
"type": "MinvAmountsAttributes",
"currency": "AUD",
"invoiced": 1250,
"paid": 1250,
"outstanding": 1250
},
"periodStart": "2026-08-19",
"periodEnd": "2026-08-19",
"dueDate": "2026-08-19",
"issuedOn": "2026-08-19",
"narrative": "string",
"orderId": "ordr_9f2Kd8QpLzXw",
"ledgerClearance": {
"type": "MinvLedgerClearanceAttributes",
"systemLedgerId": "string",
"firstSequence": 1250,
"lastSequence": 1250
},
"payments": [
{
"type": "MinvPaymentAbandoned",
"at": "2026-08-19T04:21:07Z",
"summary": "string"
}
],
"items": [
{
"type": "MinvItemAttributes",
"itemType": "PayInFullFee",
"category": "string",
"categoryLabel": "string",
"unitPrice": "string",
"count": 42,
"transactionValue": 1250,
"fees": 1250,
"tax": 1250
}
],
"billing": {
"type": "MinvBillingAttributes",
"businessName": "Ada Lovelace",
"taxId": "string",
"emailAddress": "ada@example.com",
"phoneNumber": "+61400000000",
"address": {
"type": "PsonAddressAttributes",
"unitNumber": "string",
"streetNumber": "string",
"streetName": "Ada Lovelace",
"streetType": "string",
"suburb": "string",
"city": "string",
"state": "string",
"postalCode": "3000",
"country": "AU"
}
},
"manualPayment": {
"type": "MinvManualPaymentAttributes",
"token": "tok_9f2Kd8QpLzXwR4mN",
"paymentUrl": "https://example.com/callback",
"orderId": "ordr_9f2Kd8QpLzXw"
},
"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"
}