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 PayCross system).

Terms of using split payments

Split payment limitations

Split payment works only with the card token.
The marketplace is registered in the PayCross system as a separate store.
The marketplace shops must be registered in the PayCross 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://data.pay-cross.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": "[email protected]",
      "device_id": "12312312321fff67",
      "birth_date": "1980-01-31"
    },
    "additional_data": {
      "contract": "test",
      "split": {
        "241": 40,
        "242": 50
      }
    }
  }
}

Response

To the split payment request the PayCross 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.

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

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