APG PayAPG Paydocs

Settlement

Create merchant invoices

POST/merchant-invoices

Raise an invoice over a period for the credential's own merchant. The category decides which of its ledgers is billed.

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 "MinvCmdCreate". Send it; more variants can be added, and a caller that switches on it keeps working when they are.

Discriminated by type
type = "MinvCmdCreate"
categorystringrequired

Which of the payer's ledgers to invoice. A merchant has several, and this decides what the invoice is for.

currencyIsoCurrencyrequired

Which currency's books to invoice. Required, a merchant may keep more than one.

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

periodStartstring (date)required

First day of the period to bill.

Example 2026-08-19

periodEndstring (date)required

Last day of the period to bill.

Example 2026-08-19

dueDatestring (date)

When payment falls due. Omit to let the platform apply the merchant's terms.

Example 2026-08-19

narrativestring

What the invoice covers, in words. Shown to the payer.

curl -X POST https://api.tst.au.apgpay.dev/merchant-invoices \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "MinvCmdCreate",
  "category": "string",
  "currency": "AUD",
  "periodStart": "2026-08-19",
  "periodEnd": "2026-08-19",
  "dueDate": "2026-08-19",
  "narrative": "string"
}'

Responses

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

Discriminated by type
type = "MinvCreateRspAttributes"

The resource that was created.

Example
{
  "type": "MinvCreateRspAttributes",
  "created": {
    "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