Payment Split Learn how you can split a transaction to multiple merchants

What is Payment Split?

Payment split allows you to allocate (or split) the funds of a transactions into multiple merchant accounts. Let's say you run a marketplace and earn a commission on each booking. With payment split you would be able to process a transaction using your own merchant and then transfer the funds, minus your commission, to the service provider's merchant account. The commission would stay in your account.

Please consider

A transaction is always made on behalf of a merchant. This merchant is debited for all Payyo fees and commissions. Only this merchant can refund the transaction or reverse the transfers to other merchants.

When integrating payment split you need to decide whether you want to process the transaction on your merchant account and transfer funds to other merchants, or process the transaction on another merchant's account and transfer funds to your account.

Integration

To integrate payment split integrators need to send the payment split definition (or "payments") along with a regular transaction.capture call.

Payment

1. Authorize €55 for merchant #1.

Merchant #1 receives 10% commission on a service provided by merchant #2. The service costs €50 so merchant #1 sells it for €55.

{
  "jsonrpc": "2.0",
  "method": "transaction.initiate",
  "params": {
    "merchant_id": 1,
    "merchant_reference": "order_1234",
    "currency": "EUR",
    "amount": 5500,
    "return_urls": {
      "success": "https://example.org/success",
      "fail": "https://example.org/fail",
      "abort": "https://example.org/abort"
    },
    "funding_instrument": {
      "type": "credit_card",
      "number": "4242 4242 4242 4242",
      "expires": "2020-04",
      "cvc": "123",
      "holder": "Card Tester"
    }
  },
  "id": 1
}
2. Capture €55 and send €50 to merchant #2
{
  "jsonrpc": "2.0",
  "method": "transaction.capture",
  "params": {
    "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
    "payments": [
      {
        "merchant_id": 1,
        "currency": "EUR",
        "amount": 500,
        "reference": "commission",
        "description": "Commission for service"
      },
      {
        "merchant_id": 2,
        "currency": "EUR",
        "amount": 5000,
        "reference": "service",
        "description": "Service"
      }
    ]
  },
  "id": 1
}

As the first payment (with reference commission) goes to the same account as the transaction (merchant #1, EUR) it will not lead to a transfer. As the remainder always stays with the transaction's merchant the payment could also be omitted.

{
  "jsonrpc": "2.0",
  "method": "transaction.capture",
  "params": {
    "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
    "payments": [
      {
        "merchant_id": 2,
        "currency": "EUR",
        "amount": 5000,
        "reference": "service",
        "description": "Service"
      }
    ]
  },
  "id": 1
}

Refunds

When refunding a transaction that used payment split it's likely that some funds need to be transferred back from a merchant to the transaction's merchant, so that the necessary funds for the refund are available. For each transaction the balance of each involved merchant is tracked and a merchant can never refund more than what they received.

Success
{
  "jsonrpc": "2.0",
  "method": "transaction.refund",
  "params": {
    "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
    "currency": "EUR",
    "amount": 5500,
    "payments": [
      {
        "merchant_id": 2,
        "currency": "EUR",
        "amount": 5000,
        "reference": "service",
        "description": "Service"
      }
    ]
  },
  "id": 1
}
Error because merchant #1 doesn't have the necessary funds for the full refund
{
  "jsonrpc": "2.0",
  "method": "transaction.refund",
  "params": {
    "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
    "currency": "EUR",
    "amount": 5500
  },
  "id": 1
}
{
  "jsonrpc": "2.0",
  "error": {
    "code": 1001,
    "message": "Insufficient funds. Merchant 1 must not refund more than they received from this transaction."
  },
  "id": 1
}