APG PayAPG Paydocs

Transactions

Create transfers

POST/transfers

Move part of a transaction's funds to another merchant.

Permissions

Required permission
transactions:transfer

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

Request body

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

Discriminated by type
type = "TtfrCmdCreate"
transactionIdTranIdrequired

The transaction to move funds out of.

Example tran_9f2Kd8QpLzXw

fromMerchantIdMchtIdrequired

The merchant that took the payment. Must be the transaction's own merchant.

Example mcht_9f2Kd8QpLzXw

toMerchantIdMchtIdrequired

The merchant to move the funds to.

Example mcht_9f2Kd8QpLzXw

How much to move and the fee to charge for it. Both in the single currency given here.

surchargebooleanrequired

true charges the platform fee for this transfer back to the source merchant.

Example true

metadatamap of string

Free-form data to store against this movement and return on every read of it.

curl -X POST https://api.tst.au.apgpay.dev/transfers \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "TtfrCmdCreate",
  "transactionId": "tran_9f2Kd8QpLzXw",
  "fromMerchantId": "mcht_9f2Kd8QpLzXw",
  "toMerchantId": "mcht_9f2Kd8QpLzXw",
  "amounts": {
    "type": "TtfrCmdAmountsAttributes",
    "currency": "AUD",
    "amount": 1250,
    "levy": 1250
  },
  "surcharge": true,
  "metadata": {
    "yourKey": "string"
  }
}'

Responses

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

Discriminated by type
type = "TtfrCreateRspAttributes"

The resource that was created.

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