Update loan

PATCH/loans/{loanId}

Update a loan's mutable attributes, including its status and its limit, or replace or clear its statement settings. Answers with the loan, and with the statement settings where the patch changed them.

11 actionsLoanUpdateAccountNameLoanUpdateBillingSourceLoanUpdateClearStatementSettingsLoanUpdateDisableLoanUpdateEnableLoanUpdateMetadataLoanUpdateProductLineLoanUpdateRealtimeSettlementLoanUpdateReferenceLoanUpdateStatementSettingsLoanUpdateTradingAccount

Permissions

Required permission

loans:update

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

Path parameters

loanIdstring

required

Request body

This body is a typed union. Pick a variant to see its fields and a matching example.

Discriminated by type

type = "LoanUpdateAccountName"

accountNamestringrequired

Example Ada Lovelace

curl -X PATCH https://api.tst.au.apgpay.dev/loans/{loanId} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "LoanUpdateAccountName",
  "accountName": "Ada Lovelace"
}'

Responses

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

Discriminated by type

type = "LoanUpdateRspAttributes"

The loan as it stands after the change.

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

Present only where this patch replaced or cleared the statement settings: what they are now.

One of, by type

The loan's own settings. A format not listed is not produced. Settings imported from APG read back as stored, so ,-joined or malformed addresses can appear here; sending them back in LoanUpdateStatementSettings is refused until they are corrected.

statementEmailsarray of string

Where the statement mail and its documents go, one address per entry.

Example ada@example.com

readyNoticeEmailsarray of string

Who is told a statement is ready to download, one address per entry. Empty sends no notice.

Example ada@example.com

How mailed copies are encrypted. Absent: nothing is mailed, since a statement mail is never sent unencrypted.

Read-only. A replacement keeps them and clearing the settings deletes them.

createdAtstring (date-time)required

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

updatedAtstring (date-time)required

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

Nobody has configured this loan, or its settings were cleared. Its statements get CSV and PDF and nothing is mailed.

What a loan with no settings gets: CSV and PDF, enabled, on no channel.

statementEmailsarray of string

Always empty.

Example ada@example.com

readyNoticeEmailsarray of string

Always empty.

Example ada@example.com

Example

{
  "type": "LoanUpdateRspAttributes",
  "updated": {
    "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"
  },
  "statementSettings": {
    "type": "LoanStatementSettingsConfigured",
    "documents": [
      {
        "type": "LoanStatementDocumentSettingViewAttributes",
        "format": "Csv",
        "enabled": true,
        "schemaVersion": "string",
        "channels": [
          "Email"
        ]
      }
    ],
    "statementEmails": [
      "ada@example.com"
    ],
    "readyNoticeEmails": [
      "ada@example.com"
    ],
    "transferEncryption": {
      "type": "LoanStatementTransferEncryptionViewAttributes",
      "method": "Zip",
      "secretSet": true
    },
    "systemIntegrations": [
      {
        "type": "LoanStatementSystemIntegrationAttributes",
        "sysCode": "string",
        "formats": [
          "Csv"
        ],
        "enabled": true,
        "referenceCustomerId": "your-own-reference",
        "isTest": true
      }
    ],
    "createdAt": "2026-08-19T04:21:07Z",
    "updatedAt": "2026-08-19T04:21:07Z"
  }
}

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"
}