List loans

GET/loans

Request

GEThttps://api.tst.au.apgpay.dev/loans

curl -X GET https://api.tst.au.apgpay.dev/loans \
  -H "Authorization: Bearer $API_KEY"

Return a page of loans. Supply page for offset pagination or startingAfter for cursor pagination, and q to search. The filters combine with each other and with q by AND. GET /filter-catalogues/loans lists those this caller can use. A cursor continues only the walk that issued it: sent with different filters, q or sort, it is refused with 400.

Permissions

Required permission

loans:query

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

Query parameters

qstring

Search. Matches a loan id, the id of its product or facility, the reference loan id, the account name or the EDI number. An id, an email address, a phone number and any value listed as matched exactly match exactly; any other term matches without regard to case from the start of a value (or of any word in it, beside a longer word of the term), or anywhere in it from three characters, every word of it somewhere; a term that matches nothing so is read again with typos tolerated. Closest matches come first unless sort is given.

pageinteger (int32)

Offset pagination: 1-based page number. Mutually exclusive with the cursor parameters.

startingAfterstring

Cursor pagination, moving forward: the id of the last item on the current page. Mutually exclusive with page.

endingBeforestring

Cursor pagination, moving backward: the id of the first item on the current page. Mutually exclusive with page.

limitinteger (int32)

Maximum items per page.

sortarray of LoanSort

Fields to sort by, comma-delimited, in priority order. Prefix a field with - for descending.

columnsarray of LoanColumn

Columns to include, in order, when asking for text/csv. Omit for all of them. Sending it with application/json is a 400.

statusone of LoanStatus, array of LoanStatus

Only loans whose status is one of these. Repeat the parameter to give several.

statusNotone of LoanStatus, array of LoanStatus

Leave out loans whose status is one of these. Repeat the parameter to give several.

merchantIdone of array of string, string

Only loans whose borrowing merchant is one of these. Repeat the parameter to give several.

merchantIdNotone of array of string, string

Leave out loans whose borrowing merchant is one of these. Repeat the parameter to give several.

marketplaceIdone of array of string, string

Only loans whose marketplace is one of these. Repeat the parameter to give several.

marketplaceIdNotone of array of string, string

Leave out loans whose marketplace is one of these. Repeat the parameter to give several.

marketplaceIdAbsentboolean

true for only loans with no marketplace, false for only those with one.

customerIdone of array of string, string

Only loans whose borrowing customer is one of these. Repeat the parameter to give several.

customerIdNotone of array of string, string

Leave out loans whose borrowing customer is one of these. Repeat the parameter to give several.

customerIdAbsentboolean

true for only loans with no borrowing customer, false for only those with one.

productTypeone of LprodType, array of LprodType

Only loans whose kind is one of these. Repeat the parameter to give several.

productTypeNotone of LprodType, array of LprodType

Leave out loans whose kind is one of these. Repeat the parameter to give several.

currencyone of IsoCurrency, array of IsoCurrency

Only loans whose currency is one of these. Repeat the parameter to give several.

currencyNotone of IsoCurrency, array of IsoCurrency

Leave out loans whose currency is one of these. Repeat the parameter to give several.

referenceLoanIdstring

Filter by your own identifier for the loan.

createdAfterstring (date-time)

Only loans whose creation time is at or after this ISO-8601 timestamp.

createdBeforestring (date-time)

Only loans whose creation time is at or before this ISO-8601 timestamp.

Responses

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

Discriminated by type

type = "LoanPageAttributes"

typeenumrequired

LoanViewAttributes

loanIdLoanIdrequired

Identifier of a loan.

Example loan_9f2Kd8QpLzXw

merchantIdMchtIdrequired

The merchant borrowing.

Example mcht_9f2Kd8QpLzXw

marketplaceIdMktpId

The marketplace the borrowing merchant trades under, where it does.

Example mktp_9f2Kd8QpLzXw

customerIdCustId

The customer borrowing, on a trading-account loan. A real-time-settlement loan has no customer.

Example cust_9f2Kd8QpLzXw

loanFacilityIdLfacIdrequired

Identifier of a loan facility.

Example lfac_9f2Kd8QpLzXw

loanProductIdLprodIdrequired

Identifier of a loan product.

Example lprod_9f2Kd8QpLzXw

loanAgreementIdLmaId

The master agreement this loan draws under, where the product uses one.

Example lma_9f2Kd8QpLzXw

accountNamestringrequired

What the loan account is called on statements.

Example Ada Lovelace

statusLoanStatusrequired

EnabledDisabledUnknown

The balances on a loan. All are in the single currency given here.

The terms this loan runs on, which kind of loan it is, and what the borrower is charged.

One of, by type

Funds a merchant's settlement in real time, charging a rate on the payments it settles.

variableFeenumberrequired

Charged on payments that use the real-time settlement service, as a decimal.

Example 12.5

settingLoanSettlementSettingrequired

Whether payments use real-time settlement automatically, and what happens when it is unavailable.

ManualAutomaticPreferredAutomaticRequiredUnknown

A revolving trading account a customer draws against and repays on statement.

customerIdCustIdrequired

The organisational customer that owns the trading account.

Example cust_9f2Kd8QpLzXw

How often this borrower is sent a statement, and on which day.

graceDaysinteger (int32)required

Days between a statement being issued and falling due.

Example 1250

What this borrower is charged, which may override the product's defaults.

typeenumrequired

LoanCustomerFeesAttributes

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

annualFixedFeeMinorUnitsrequired

Charged to the account annually.

Example 1250

annualFeeRenewalDatestring (date)

When the annual fee next goes on a statement. Absent until the first one has been charged.

Example 2026-08-19

implementationFixedFeeMinorUnits

Charged once, when the loan is established.

Example 1250

implementationFeeAppliedAtstring (date-time)

When the establishment fee was applied. Absent while it is still outstanding.

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

extendedPaymentTermsVariableFeenumber

Charged on each statement for extended payment terms, on the charges since the last one, as a decimal, 0.01 is 1%.

Example 12.5

Charged on each statement for every earlier statement left overdue.

customerTransactionVariableFeenumber

Charged on each statement for its payment terms, on the charges since the last one, as a decimal, 0.01 is 1%.

Example 12.5

supportedCardBrandsarray of CardBrand

Brands of card that may be issued against this loan.

VisaMasterCardAmericanExpressDinersClubDiscoverUnionPayMaestroEloMirHiper

+5 more

Hipercard, Jcb, Electron, Uatp, Unknown

industryGroupLoanIndustryGroup

The industry group this loan is restricted to, where it is restricted at all.

TravelProcurementUnknown

Rules the metadata of this account's card transactions must meet. Replace it with LoanUpdateTradingAccount.

typeenumrequired

LoanMetadataTemplateAttributes

The fields to check, one entry per field. An empty list checks nothing.

typeenumrequired

LoanMetadataFieldAttributes

pathstringrequired

Where the field sits in the metadata JSON object. Names are separated by dots, as in additionalMetaData.dbiInfo.dbiAu. A dotted name may hold only letters, digits and _; any other name goes in brackets and quotes, as in orders['PO number'] or a['b.c'], where a backslash escapes a quote. Arrays cannot be indexed. A path that is empty, starts with a dot, has an empty name (a..b), indexes an array (a[0]) or has a space outside brackets is refused with 400. A field listed twice with the same validator is kept once; with a different validator it is refused with 400.

Example additionalMetaData.dbiInfo.dbiAu

The checks a field's value must pass. A string value is checked as it is; a number is checked as its JSON text, so 45085 is checked as "45085". An absent field, null or a blank string is missing: it is never checked for length or format, and is a problem only while a constraint requires it. A boolean, array or object is invalid, with the issue "Value must be text, not <type>" (a boolean, a JSON array or a JSON object), and value then carries that type, never the content.

typeenumrequired

LoanMetadataValidatorAttributes

namestringrequired

The field's display name, used in validation messages. For an additionalMetaData.dbiInfo.<dbiXx> path it is also the column label on statements and reports. Must not be blank.

Example Order Number

Whether a missing or invalid value holds a charge off the customer statement. LoanMetadataNotRequired: never. LoanMetadataDaysRequiredWithin: the charge is held until the value is valid or until days days after the transaction was created, whichever comes first; after that the requirement lapses and the charge is published as it is. Whatever this says, a charge is published at the first statement close 14 days after authorisation, and a refund is never held. Creating a Mastercard digital card is refused while a field with days of 1 or more is missing or invalid.

Whether a missing or invalid value holds back a captured transaction's publicAt, the time from which the publicAtAfter and publicAtBefore transaction filters find it. LoanMetadataNotRequired: never. LoanMetadataDaysRequiredWithin: publicAt is set once the value is valid or once days days have passed since the transaction was created. Once set, publicAt is not withdrawn.

minLengthinteger (int32)required

The fewest characters a present value may have, inclusive, from 0 to 30. A missing or blank value is never measured, so 0 behaves as 1 and is stored as 1: a field is made optional by its constraints, not by its length.

Example 1

maxLengthinteger (int32)required

The most characters a present value may have, inclusive, from minLength to 30. Equal to minLength asks for exactly that length.

Example 17

formatLoanMetadataFieldFormatrequired

The characters a present value may contain. Alphanumeric: letters, digits, whitespace and @ . ; : ? + - * / $ & # < > _ , ( ) % ', for example PENNY LIM or PO-1234/7. Alphabetic: letters and whitespace, for example PENNY LIM. Numeric: digits and whitespace, for example 045085; a sign or decimal point is refused. IsoDate: eight digits read as yyyyMMdd, for example 20250501; a month above 12 or a day above 31 is refused. Letters and digits include those of any script.

AlphanumericAlphabeticNumericIsoDateUnknown

timeZonestringrequired

IANA time zone the loan's statement periods are measured in.

billingPaymentSourceIdPsrcId

The payment source automated billing is charged to.

Example psrc_9f2Kd8QpLzXw

productLineLoanProductLine

APG's product line, which picks the account a bank-transfer statement asks to be paid into. Absent until set, on the application or with LoanUpdateProductLine.

CentralPayVirtualPayTaaB2bSupplyChainUnknown

metadatamap of any JSON value

Free-form data the platform stores and returns untouched.

referenceLoanIdstring

The caller's own reference for this loan.

Example your-own-reference

createdAtstring (date-time)required

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

updatedAtstring (date-time)required

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

hasMorebooleanrequired

Whether further items exist after this page.

Example true

nextStartingAfterstring

Id to pass as startingAfter to fetch the next page. Present in cursor mode only.

totalCountinteger (int64)

Total items matching the query.

Example 42

pageinteger (int32)

The 1-based page returned. Present in offset mode only.

Example 1250

totalPagesinteger (int32)

Total pages available. Present in offset mode only.

Example 1250

Example

{
  "type": "LoanPageAttributes",
  "data": [
    {
      "type": "LoanViewAttributes",
      "loanId": "loan_9f2Kd8QpLzXw",
      "merchantId": "mcht_9f2Kd8QpLzXw",
      "marketplaceId": "mktp_9f2Kd8QpLzXw",
      "customerId": "cust_9f2Kd8QpLzXw",
      "loanFacilityId": "lfac_9f2Kd8QpLzXw",
      "loanProductId": "lprod_9f2Kd8QpLzXw",
      "loanAgreementId": "lma_9f2Kd8QpLzXw",
      "accountName": "Ada Lovelace",
      "status": "Enabled",
      "balances": {
        "type": "LoanBalancesAttributes",
        "currency": "AUD",
        "limit": 500000,
        "used": 1250,
        "available": 1250,
        "reserved": 1250,
        "pending": 1250
      },
      "specification": {
        "type": "LoanSpecRealtimeSettlement",
        "variableFee": 12.5,
        "setting": "Manual"
      },
      "timeZone": "string",
      "billingPaymentSourceId": "psrc_9f2Kd8QpLzXw",
      "productLine": "CentralPay",
      "metadata": {
        "yourKey": {}
      },
      "referenceLoanId": "your-own-reference",
      "createdAt": "2026-08-19T04:21:07Z",
      "updatedAt": "2026-08-19T04:21:07Z"
    }
  ],
  "hasMore": true,
  "nextStartingAfter": "string",
  "totalCount": 42,
  "page": 1250,
  "totalPages": 1250
}

Error responses

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}

statusCodeinteger (int32)required

HTTP status code for this error

errorCodestringrequired

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

messagestringrequired

Human readable description of the error

tracerstring

An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

detailstring

Optional additional details for the error.

errorTypeDescriptionstring

A description of the category of errors for the given statusCode.

metadataobject

Optional key value list of metadata

Example response

{
  "statusCode": 100,
  "errorCode": "string",
  "message": "string",
  "tracer": "string",
  "detail": "string",
  "errorTypeDescription": "string"
}