Transaction Transfers

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 API via the TransferFunds action. For example, to transfer $100, PATCH the following:

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.

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 API via the ReverseFundsTransfer action. To reverse the previous example, for instance, PATCH the following:

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 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

{
  "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
    }
  ]
}

Return to documentation home.