APG PayAPG Paydocs

Transactions

Update transfer

PATCH/transfers/{transferId}

Claw back part of what was transferred to one merchant. Identify the record by its transaction.

Permissions

Required permission
transactions:transfer

Requires the `transfer` action on `transactions` for the supplied runtime context

Path parameters

transferIdstring
required

Request body

This body is a tagged shape: type is always "TtfrUpdateReverse". Send it; more variants can be added, and a caller that switches on it keeps working when they are.

Discriminated by type
type = "TtfrUpdateReverse"
toMerchantIdMchtIdrequired

The merchant to claw the funds back from. It must have received a transfer on this transaction.

Example mcht_9f2Kd8QpLzXw

How much to reverse. Must be positive, and at most what that merchant received.

reverseLevybooleanrequired

true returns the levy charged to that merchant in proportion. false leaves it in place.

Example true

metadatamap of string

Free-form data to store against the reversal movement.

curl -X PATCH https://api.tst.au.apgpay.dev/transfers/{transferId} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "TtfrUpdateReverse",
  "toMerchantId": "mcht_9f2Kd8QpLzXw",
  "amount": {
    "type": "IsoCurrencyAmount",
    "minorCurrencyUnits": 1250,
    "currency": "AUD"
  },
  "reverseLevy": true,
  "metadata": {
    "yourKey": "string"
  }
}'

Responses

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

Discriminated by type
type = "TtfrUpdateRspAttributes"

The resource as it stands after the change.

Example
{
  "type": "TtfrUpdateRspAttributes",
  "updated": {
    "type": "TtfrViewAttributes",
    "transferId": "tran_9f2Kd8QpLzXw",
    "merchantId": "mcht_9f2Kd8QpLzXw",
    "marketplaceId": "mktp_9f2Kd8QpLzXw",
    "enterpriseId": "ent_9f2Kd8QpLzXw",
    "state": "Available",
    "amounts": {
      "type": "TtfrAmountsAttributes",
      "currency": "AUD",
      "transactionAmount": 1250,
      "transferred": 1250,
      "transferable": 1250,
      "levied": 1250,
      "surcharged": 1250
    },
    "movements": [
      {
        "type": "TtfrMovementAttributes",
        "toMerchantId": "mcht_9f2Kd8QpLzXw",
        "idempotencyKey": "string",
        "transferred": 1250,
        "surcharged": 1250,
        "levy": 1250,
        "metadata": {
          "yourKey": "string"
        },
        "createdAt": "2026-08-19T04:21:07Z"
      }
    ],
    "createdAt": "2026-08-19T04:21:07Z",
    "updatedAt": "2026-08-19T04:21:07Z"
  }
}

Error responses