APG PayAPG Paydocs

Transactions

Create refunds

POST/refunds

Refund part or all of a transaction, acquiring or issuing.

Permissions

Required permission
refunds:create

Requires the `create` action on `refunds` for the supplied runtime context

Request body

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

Discriminated by type
type = "RfndCmdCreate"

A refund of a payment taken from a customer, the acquiring side.

How much to refund. Omit to refund everything not yet refunded.

metadatamap of any JSON value

Free-form data the platform stores against the refund and returns untouched.

curl -X POST https://api.tst.au.apgpay.dev/refunds \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "RfndCmdCreate",
  "subject": {
    "type": "RfndSubjectTransaction",
    "transactionId": "tran_9f2Kd8QpLzXw"
  },
  "amount": {
    "type": "IsoCurrencyAmount",
    "minorCurrencyUnits": 1250,
    "currency": "AUD"
  },
  "metadata": {
    "yourKey": {}
  }
}'

Responses

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

Discriminated by type
type = "RfndCreateRspAttributes"

The resource that was created.

Example
{
  "type": "RfndCreateRspAttributes",
  "created": {
    "type": "RfndViewAttributes",
    "refundId": "rfnd_9f2Kd8QpLzXw",
    "subject": {
      "type": "RfndSubjectTransaction",
      "transactionId": "tran_9f2Kd8QpLzXw"
    },
    "merchantId": "mcht_9f2Kd8QpLzXw",
    "customer": {
      "type": "RfndCustomerAttributes",
      "customerId": "cust_9f2Kd8QpLzXw",
      "name": "Ada Lovelace",
      "emailAddress": "ada@example.com",
      "phoneNumber": "+61400000000"
    },
    "status": "Pending",
    "amounts": {
      "type": "RfndAmountsAttributes",
      "currency": "AUD",
      "amount": 1250,
      "transactionAmount": 1250
    },
    "orderId": "ordr_9f2Kd8QpLzXw",
    "referenceOrderId": "your-own-reference",
    "orderMetadata": {
      "yourKey": {}
    },
    "payoutId": "payout_9f2Kd8QpLzXw",
    "settlementDate": "2026-08-19",
    "attempts": 1250,
    "lastError": "string",
    "createdAt": "2026-08-19T04:21:07Z",
    "refundedAt": "2026-08-19T04:21:07Z",
    "updatedAt": "2026-08-19T04:21:07Z"
  }
}

Error responses