Split Payment

Split Payment and Split Payment Status

Split payment API

Endpoint details

Method: POST
URL: BASE_URL/splitPayment/
Query params:

api-key: kfggfgf.given_api_key_by_paylov

Swagger Docs

Description:
Splits a transaction amount among multiple recipients. Each recipient receives a sub-transaction with the specified amount. The transaction is marked as split upon successful completion.

💡 Note: Get the recipientId from (Paylov) the service provider

Request body

Field	Type	Required	Description
transactionId	string	Yes	Unique identifier for the transaction.
recipients	array	Yes	List of recipients receiving the transaction.
recipients[].recipientId	string	Yes	Unique identifier for the recipient.
recipients[].amount	number	Yes	Amount allocated to the recipient.
recipients[].items	array	No	List of items associated with the recipient.
recipients[].items[].title	string	Yes	Name or title of the item.
recipients[].items[].price	number	Yes	Price of the item before discounts.
recipients[].items[].discount	number	Yes	Discount applied to the item.
recipients[].items[].count	number	Yes	Quantity of the item.
recipients[].items[].code	string	Yes	Unique code identifying the item.
recipients[].items[].vat_percent	number	Yes	VAT percentage applicable to the item.
recipients[].items[].package_code	string	Yes	Code representing the package type.
recipients[].items[].pinfl	string	No	Taxpayer identification number (PINFL).
resendOFD	boolean	No	Flag indicating whether to resend data to the fiscal system.

Request example

{
  "transactionId": "9b3bd7be-9327-4608-b886-4353e49df05f",
  "recipients": [
    {
      "recipientId": "string",
      "amount": 100,  #in tiyn
      "items": [
        {
          "title": "string",
          "price": 0,
          "discount": 0,
          "count": 0,
          "code": "string",
          "vat_percent": 0,
          "package_code": "string",
          "pinfl": "string"
        }
      ]
    },
    {
      "recipientId": "abda5234-16aq-4896-90a2-b095ff557654",
      "amount": 100
    }

  ],
 "resendOFD": false
}

Response

On Success, you'll receive:

{
  "result": {
    "transactionId": "<transaction_id>"
  }
}

💡 Note: If items included in the request body, transaction will be send to OFD to generate fiscal data. The transaction is sent to OFD asynchronously, so it won’t wait for a response. OFD might be delayed due to high traffic. After the payment is split, you can check the status using a dedicated method. If the response does not include OFD data, you need to resend the split payment request with resendOFD: true

Error codes

• permission_denied
• transaction_not_found
• split_already_done
• invalid_amount
• recipient_not_found

Example for recipient_not_found:

{
  "error": {
    "code": "recipient_not_found",
    "message": "One or more recipients not found.",
    "data": {
      "notFoundRecipientIds": [
        "<recipient_id>"
      ]
    }
  }
}

Implementation Notes

• Permission Check: Ensures the merchant has split payment permissions.
• Validation:
  • Verifies the transaction exists, is not already split.
  • Ensures the sum of recipients’ amounts matches the transaction amount.
  • Checks for the existence of recipient merchants.

Split payment status API

Endpoint details

Method: GET
URL: BASE_URL/splitPayment/status/

Swagger Docs

Description: Retrieves the status of all sub-transactions for a split transaction.

Request parameters

Parameter	Type	Description	Required
api-key	string	API key	Yes
transactionId	string	The ID of the parent transaction.	Yes

Response example
On Success,

{
  "result": [
    {
      "recipientId": "ccda5111-66a0-4896-90a2-b095ff558129",
      "amount": 100,  #in tiyn
      "status": "paid",
      "createdAt": "2025-01-06 17:17:17"
    },
    {
      "recipientId": "ffddb832-4bd2-410c-a1d9-26dv9fefb111",
      "amount": 100,
      "status": "paid",
      "createdAt": "2025-01-06 17:17:17"
    }
  ]
}

Error codes

• permission_denied
• transaction_not_found
• split_not_found

Implementation notes

• Permission check: Verify that the merchant has split payment permissions.

• Transaction validation: Ensure the parent transaction exists and belongs to the merchant.

• Status mapping:

  • paid
  • cancelled
  • check