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 Demo PSP system).

Terms of using split payments

Split payment limitations

  • Split payment works only with the card token.
  • The marketplace is registered in the Demo PSP system as a separate store.
  • The marketplace shops must be registered in the Demo PSP 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.begateway.com/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 Demo PSP 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.

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

  • If the main transaction fails or the acquirer declines it, Demo PSP doesn’t run all the next split transactions.
  • If the main transaction successfully processes, but the first split transaction fails, Demo PSP 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, Demo PSP sends voids or refunds request for all previous transactions, including the main transaction.
  • If something goes wrong before sending any requests to the gateway, Demo PSP also handles this case as failed with the standard error message.