APG PayAPG Paydocs

Settlement

Get merchant invoice

GET/merchant-invoices/{merchantInvoiceId}
Request
GEThttps://api.tst.au.apgpay.dev/merchant-invoices/{merchantInvoiceId}
curl -X GET https://api.tst.au.apgpay.dev/merchant-invoices/{merchantInvoiceId} \
  -H "Authorization: Bearer $API_KEY"

Return one invoice, with its lines and billing details.

Permissions

Required permission
merchantFinancials:query

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

Path parameters

merchantInvoiceIdstring
required

Responses

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

Discriminated by type
type = "MinvViewAttributes"
merchantInvoiceIdMinvIdrequired

Identifier of a merchant invoice.

Example minv_9f2Kd8QpLzXw

referencestringrequired

The reference a payer quotes. Derived from the identifier, and the two convert both ways.

Example your-own-reference

payerMerchantIdMchtIdrequired

The merchant being billed.

Example mcht_9f2Kd8QpLzXw

payerNamestringrequired

Business name of the merchant billed, so a listing reads without a second call.

Example Ada Lovelace

payeeMerchantIdMchtIdrequired

The merchant receiving the funds. Usually the platform's own; a marketplace that self-manages gross settlement is its own payee.

Example mcht_9f2Kd8QpLzXw

payerMarketplaceIdMktpId

The marketplace the payer trades under, where it does.

Example mktp_9f2Kd8QpLzXw

payerEnterpriseIdEntIdrequired

Identifier of an enterprise.

Example ent_9f2Kd8QpLzXw

statusMinvStatusrequired
DraftOutstandingNearDueDueOverduePaidCancelledDefaultedUnknown

What is owed on the invoice and what has been paid. All in the single currency given here.

periodStartstring (date)required

First day of the period billed.

Example 2026-08-19

periodEndstring (date)required

Last day of the period billed.

Example 2026-08-19

dueDatestring (date)required

When 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

narrativestringrequired

What the invoice covers, in words.

orderIdstring

The 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.

Every attempt at paying this invoice, in order. Empty where none has been made.

The lines that make up the invoice. Present on a by-id read; a listing is not itemised.

Who the invoice is addressed to. Present on a by-id read.

How a person can pay this invoice by hand. Present on a by-id read, where the platform issued a link.

createdAtstring (date-time)required

Example 2026-08-19T04:21:07Z

updatedAtstring (date-time)required

Example 2026-08-19T04:21:07Z

Example
{
  "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