Skip to content

Split payment

Split payment is a method of making payments in the marketplace, in which one transaction is sent to two or more legal entities (shops in the bePaid system).

Terms of using split payments

Split payment limitations

  • Split payment works only with the card token.
  • The marketplace is registered in the bePaid system as a separate store.
  • The marketplace shops must be registered in the bePaid system and have a Shop ID.
  • The split currency is determined by the currency of the transaction, that will be debited from the client, so it cannot be set its own currency for each split (the currency converter does not work with split payment).

Split payment paid amounts

  • The amount that will be charged from the client card is determined in the amount parameter of the split payment request.
  • The amount that will be paid to each shop is determined in the split section of the split payment request.
  • The amount that will be paid to the marketplace (marketplace commission) calculated as the amount parameter of the split payment request minus the amounts from split section, that will be paid to each shop.

Split payment request

To split the amount of a payment, send a POST request to https://api.bepaid.by/splits/payment with the same parameters as for authorization or payment requests, as well as the additional split section:

Parameter Type Description
amount * required
integer The amount that will be charged from the customer card in minimal currency units, for example $32.45 must be sent as 3245
additional_data object A section of additional information about the payment.
split object A section contains detailed information about the shops that participate in the split payment.
{shop ID} * required
integer An amount that will be paid to the shop in minimal currency units, for example $32.45 must be sent as 3245. The amounts of payments to the shops cannot exceed or be equal to the amount specified in the amount parameter.

The parameter key contains the Shop ID of the shop that participates in the split payment.

Split payment request authorization is provided by request headers with credentials of the main shop (marketplace). Request authorization for the marketplace shops is provided automatically by their shop ID, which is sent in the split payment request in the split section.

Example of the request
{
  "request": {
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction",
    "tracking_id": "tracking_id_000",
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "country": "US",
      "city": "Denver",
      "state": "CO",
      "zip": "96002",
      "address": "1st Street"
    },
    "credit_card": {
      "token": "credit-card-token"
    },
    "customer": {
      "ip": "127.0.0.1",
      "email": "john@example.com",
      "device_id": "12312312321fff67",
      "birth_date": "1980-01-31"
    },
    "additional_data": {
      "contract": "test",
      "split": {
        "241": 40,
        "242": 50
      }
    }
  }
}
Response

To the split payment request the bePaid system returns a response specifying:

Parameter Type Description
uid * required
string Transaction UID
amount * required
integer Amount in minimal currency units, for example $32.45 is 3245
status * required
string The standard transaction statuses and status cancelling - cancellation is requested (аll transactions will be cancelled or already cancelled)
message * required
string Processing result message.
shop_id * required
integer Shop ID
parent * required
boolean If true, this is the parent (main) transaction (marketplace commission). The main transaction is processed first. If false, this is a transaction to the marketplace shops
parent_uid * required
string UID of the parent transaction.
Example of the successful response
{
  "splits": [
    {
      "uid": "21-99834feb0b",
      "amount": 70,
      "status": "successful",
      "message": "Successfully processed",
      "shop_id": 91,
      "parent": true,
      "parent_uid": null
    },
    {
      "uid": "22-56784ffecd",
      "amount": 10,
      "status": "successful",
      "message": "Successfully processed",
      "shop_id": 1111,
      "parent": false,
      "parent_uid": "21-99834feb0b"
    },
    {
      "uid": "23-abcd4f1234",
      "amount": 20,
      "status": "successful",
      "message": "Successfully processed",
      "shop_id": 2222,
      "parent": false,
      "parent_uid": "21-99834feb0b"
    }
  ]
}
Example of the response if one of the transactions was declined
{
  "splits": [
    {
      "uid": "21-99834feb0b",
      "amount": 10,
      "status": "cancelling",
      "message": "Cancel has been requested.",
      "shop_id": 240,
      "parent": true,
      "parent_uid": "nil"
    },
    {
      "uid": "123",
      "amount": 40,
      "status": "cancelling",
      "message": "Cancel has been requested.",
      "shop_id": 241,
      "parent": false,
      "parent_uid": "21-99834feb0b"
    },
    {
      "uid": "234",
      "amount": 50,
      "status": "failed",
      "message": "Decline",
      "shop_id": 242,
      "parent": false,
      "parent_uid": "21-99834feb0b"
    }
  ]
}
Example of the response if the amounts of payments to the shops exceed or equal to the amount specified in the amount parameter

HTTP status code 422.

{
  "message": "Split sum is equal or more than main amount."
}

Cancel split payments

If a decline/error response is returned for at least one of the split transactions, the system cancels all previous transactions.

bePaid process the main transaction (amount, that will be paid to the marketplace):

  • If the main transaction fails or the acquirer declines it, bePaid doesn’t run all the next split transactions.
  • If the main transaction successfully processes, but the first split transaction fails, bePaid sends voids or refunds request for the main transaction.
  • If the main transaction successfully processes and few split transactions were processed, but the last split transaction failed, bePaid sends voids or refunds request for all previous transactions, including the main transaction.
  • If something goes wrong before sending any requests to the gateway, bePaid also handles this case as failed with the standard error message.