# Transaction Transfers

Important
This page describes functionality only relevant for merchants using **[Marketplace](/developer-portal/marketplace)** integration.
The configuration described on this page will not function without a Marketplace API Key.

Merchants in a marketplace environment are capable of transferring funds between themselves.
This function is useful for marketplaces wishing to process all their transactions through one of
their sub-merchants and disburse the funds to others.

## Transferring a transaction

To transfer a single transaction, execute a request to the [Update Transaction](/openapi/april-public/transactions/updatetransaction) API via the `TransferFunds` action.
For example, to transfer $100, `PATCH` the following:


```http request
PATCH https://api.au.meetapril.io/transactions/tran_YvrnkXYqUW-2JsB1
Authorization: Bearer MARKETPLACE_API_KEY
Accept: application/json
Content-Type: application/json

{
  "TransferFunds": {
    "destinationMerchantId": "mcht_Yh6iVsd4lFf1Odg8",
    "transferAmount": 10000,
    "surchargeFee": false,
    "levy": null
  }
}
```

The `destinationMerchantId` merchant must be on the same marketplace as the transaction origin merchant.
The `transferAmount` can be less than or equal to the current value of the transaction.
In situations where a transaction was partially refunded prior to the transfer, it would only be possible to transfer the remaining amount.

## Surcharging

The transfers API features a `surchargeFee` parameter which allows the April platform fee to be surcharged for the transaction.
Using the example above, if the transaction had a platform fee of $1 and the transfer request specified a surcharge,
the destination `destinationMerchantId` would be transferred $100 and subsequently debited $1.
The transaction origin merchant would be credited the surcharge of $1.
In the case of a partial transfer (i.e. not the entire transaction amount), then the platform fee is proportional to the
amount transferred.

This inter-merchant surcharging is a different level of surcharging from [Payment Surcharging](/developer-portal/payment-surcharging), which
applies when a merchant passes on platform fees to the end customer.

## Applying a levy

A levy can be applied to each transfer in addition to a surcharge. This allows for the application of a separate fee
that is mutually exclusive from the amount surcharged (i.e. the April platform fee).
Similar to the surcharge process, the `destinationMerchantId` will be transferred the total funds designated and subsequently
debited the levy amount, which is then credited to the transaction origin merchant.

The `levy` and `surcharge` parameters can be used individually or in conjunction. If used together,
the fee deducted from the `destinationMerchantId` will be the sum of both fees and debited as a single entry,
and likewise credited to the transaction origin merchant.

## Reversing a transaction transfer

To reverse a transfer, execute a request to the [Update Transaction](/openapi/april-public/transactions/updatetransaction) API via the `ReverseFundsTransfer` action.
To reverse the previous example, for instance, `PATCH` the following:


```http request
PATCH https://api.au.meetapril.io/transactions/tran_YvrnkXYqUW-2JsB1
Authorization: Bearer MARKETPLACE_API_KEY
Accept: application/json
Content-Type: application/json

{
  "TransferFunds": {
    "sourceMerchantId": "mcht_Yh6iVsd4lFf1Odg8",
    "reverseAmount": 5000,
    "reverseLevy": true
  }
}
```

As the flow of funds has been reversed, note that the `destinationMerchantId` from the original call is now the `sourceMerchantId` for this call.
The original transfer can be partially reversed, as shown in the above example where the `reverseAmount` is specified to be only `5000` to return $50.

### Reversing the levy

The `reverseLevy` parameter allows the reversal of what was previously deducted in the prior transfer.
If this parameter is set to `true`, the `sourceMerchantId` merchant will be credited with the levy, proportional to the amount reversed.

## Reviewing the transaction transfer state

The [Get Transaction](/openapi/april-public/transactions/gettransaction) API allows the review of completed transfers and reversals for a specified transaction.

Below is an example of the output from the previous transactions and reversals:

**TODO - update example response**


```json
{
  "transactionTransferId": "trantransfer_YipoOahqOmqtml3u",
  "transactionId": "tran_YipoKKhqOmqtml3f",
  "transactionMerchant": "mcht_Yh6iVsd4lFf1Odg8",
  "transactionAmount": 10000,
  "currency": "AUD",
  "totalTransferred": 5000,
  "totalSurcharged": 325,
  "totalLevied": 61,
  "transfers": [
    {
      "transferredToMerchantId": "mcht_Yh6iVsd4lFf1Odg8",
      "idempotencyKey": "413aadc2-53df-4a1b-b032-6da139e7eee6",
      "createdAt": "2022-03-10T21:06:01.929Z",
      "transferred": 10000,
      "surcharged": 325,
      "levy": 123
    },
    {
      "transferredToMerchantId": "mcht_Yh6iVsd4lFf1Odg8",
      "idempotencyKey": "353bb6d4-9888-4b6f-b5ec-eb66c5c74873",
      "createdAt": "2022-03-10T21:06:24.084Z",
      "transferred": -5000,
      "surcharged": 0,
      "levy": -62
    }
  ]
}
```

br
br
**[Return to documentation home](/).**