Transfer Reconciliation

Persona: Accounting software integrator, finance operations team, marketplace platform tracking per-merchant payouts.

Scenario: After each settlement run, a background worker needs to reconcile the transfer against your internal payment records, confirming which payments have settled, identifying dishonour clawbacks, and matching refunds back to the original orders.

Endpoint sequence

1. Receive transfer webhook event: get the transferId
2. GET /transfers/{id}: get transfer header (net amount, date, account)
3. GET /transfers/items/{id}: get all line items
4. Match each line item back to your records using paymentId

Step 1: Receive the transfer webhook event

Subscribe to the transfer event type. The event fires when a transfer is created and contains the transfer ID and a high-level summary.

{
  "Id": "evt_tra001",
  "Type": "transfer",
  "EventDate": "2026-08-02T08:00:00.000Z",
  "Metadata": {
    "TransferAmount": 95000,
    "SettlementCount": 10,
    "DishonourCount": 1
  },
  "Data": {
    "Transfer": {
      "Id": "tra_abc123",
      "Amount": 95000,
      "TransferDate": "2026-08-02T00:00:00.000Z",
      "Status": "exported"
    }
  }
}

Extract the transfer ID from Data.Transfer.Id (tra_abc123) and proceed to fetch the full line items.

Step 2: Fetch the transfer header

GET https://api.getpinch.com.au/test/transfers/tra_abc123
Authorization: ******
pinch-version: 2020.1

This confirms the net amount and the date funds were sent to the merchant's bank account.

Step 3: Fetch the line items

GET https://api.getpinch.com.au/test/transfers/items/tra_abc123
Authorization: ******
pinch-version: 2020.1

Each line item represents an individual debit or credit that makes up the net transfer amount.

{
  "items": [
    {
      "type": "Settlement",
      "paymentId": "pmt_001",
      "amount": 10000,
      "feeAmount": 220,
      "taxAmount": 20,
      "description": "Invoice INV-100"
    },
    {
      "type": "Dishonour",
      "paymentId": "pmt_002",
      "amount": -5500,
      "feeAmount": 0,
      "taxAmount": 0,
      "description": "Invoice INV-099"
    },
    {
      "type": "Refund",
      "paymentId": "pmt_003",
      "amount": -2500,
      "feeAmount": 0,
      "taxAmount": 0,
      "description": "Partial refund - INV-098"
    },
    {
      "type": "ProcessingFee",
      "paymentId": "pmt_001",
      "amount": -220,
      "feeAmount": 220,
      "taxAmount": 20,
      "description": "Processing fee"
    }
  ]
}

Step 4: Process each line item type

Settlement: payment has cleared

Match paymentId to your internal payment record and mark it as settled.

case "Settlement":
  await db.payments.updateStatus(item.paymentId, "settled");
  await db.payments.setTransferId(item.paymentId, transferId);
  break;

Dishonour: funds clawed back

A Dishonour line item means a payment that was settled in a previous transfer has since been reversed by the bank. The transfer amount is reduced accordingly.

case "Dishonour":
  await db.payments.updateStatus(item.paymentId, "dishonoured");
  await retryQueue.add(item.paymentId); // see Handle a Dishonoured Direct Debit recipe
  break;

⚠️

Dishonour line items represent a clawback of previously settled funds. Do not confuse them with the payment record itself; the transfer amount is negative because Pinch is debiting your settlement account for the reversal.

Refund: refund has been processed

Match paymentId to your order or payment record and confirm the refund is reflected.

case "Refund":
  await db.payments.recordRefundSettled(item.paymentId, Math.abs(item.amount));
  break;

ProcessingFee / ApplicationFee: fee deducted

Record for your own financial reporting. feeAmount is in cents and taxAmount is the GST component.

case "ProcessingFee":
case "ApplicationFee":
  await db.fees.record({
    paymentId: item.paymentId,
    transferId: transferId,
    fee: item.feeAmount,
    tax: item.taxAmount
  });
  break;

Key caveats

• Store paymentId at creation time. It is your only reliable foreign key from a transfer line item back to a payment. Without it, automated reconciliation is not possible. Store it in your database when you create each payment.
• Amounts are in cents. amount, feeAmount, and taxAmount are all in cents. Negative amounts represent debits from your settlement account.
• One transfer can span multiple payment dates. Do not assume all line items in a transfer relate to the same original payment date.
• Dishonours may not appear in the same transfer as the original settlement. A dishonour typically arrives in a transfer 1–3 business days after the bank returns the result; this may be a different transfer from the one that contained the original Settlement line item.
• Statements correspond 1:1 with transfers. If you also need PDF statements for archiving or merchant portal display, use the Statements API; each statement maps to a specific transfer.

What to do next

• Transfers in Pinch Payments: full transfers feature reference
• Handle a Dishonoured Direct Debit: how to handle and retry dishonoured payments
• Refunds: how refunds appear in transfers
• Events Guide: the transfer event payload reference