Transaction Transfers

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

Transferring a transaction

To transfer a single transaction, execute a request to the Transaction [Transfer] API. For example, to transfer $100, POST the following:

{
  "fromMerchant": "mcht_Yh6iVsd4lFf1Odg8",
  "toMerchant": "mcht_Yh6qVVhqmzj0vqR3",
  "transferAmount": {
    "amount": 10000,
    "currency": "AUD"
  },
  "surcharge": false,
  "levy": null
}

Both the from and to merchants must be on the same platform. The amount can be less than or equal to the current value of the transaction, so 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 surcharge parameter which allows the Limepay 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 toMerchant would be transferred $100 and subsequently debited $1. The transaction origin fromMerchant 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 Limepay platform fee). Similar to the surcharge process, the toMerchant will be transferred the total funds designated and subsequently debited the levy amount, which is then credited to the fromMerchant.

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

Reversing a transaction transfer

To reverse a transfer, execute a request to the Transaction Transfer [Reverse] API. To reverse the previous example, for instance, POST the following:

{
  "fromMerchant": "mcht_Yh6qVVhqmzj0vqR3",
  "toMerchant": "mcht_Yh6iVsd4lFf1Odg8",
  "reverseAmount": {
    "amount": 5000,
    "currency": "AUD"
  },
  "reverseLevy": true
}

As the flow of funds has been reversed, note that the fromMerchant and toMerchant have also reversed from the previous example. The original transfer can be partially reversed, as shown in the above example where the amount 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 fromMerchant will be credited with the levy, proportional to the amount reversed.

Getting a transfer state

The Transaction Transfers [Get] API allows the review of completed transfers and reversals for a specified transaction. Note that unlike the above transfer APIs, this API requires the use of the merchant secret token for the sub-merchant who owns the transaction.

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

{
  "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.