Skip to main content

​
About the Escrow & Payment Split API

The Star-Pay Escrow & Payment Split API enables marketplaces, platforms, and multi-party businesses to securely collect, hold, and distribute payments between multiple merchants or beneficiaries. With Escrow, funds are held securely after a payment is initiated and remain in escrow until the marketplace or platform determines that the agreed condition has been fulfilled. The platform can then release the funds to the intended merchant or cancel the escrow payment when the transaction should be reversed. The Payment Split capability allows a single customer payment to be distributed between multiple merchants or beneficiaries based on predefined split rules. Platforms can choose to automatically split the payment when the initial payment is completed, or use the escrow lifecycle to control when the funds are released and distributed. This makes the API suitable for marketplaces and platforms where a single customer transaction involves multiple merchants, service providers, or other participating parties. A typical flow can be:
1

Initiate Payment

The platform initiates a customer payment through Star-Pay.
2

Automatically Split the Payment (Optional)

If payment splitting is configured, Star-Pay can automatically distribute the payment according to the configured split rules once the initial payment is successfully completed.
3

Hold in Escrow (Optional)

When escrow is used, the funds can remain secured until the platform determines that the transaction conditions have been fulfilled.
4

Release or Cancel

The platform can release the escrowed funds to the configured beneficiary or cancel the escrow payment according to the transaction outcome.
5

Distribute Funds

When applicable, the payment is distributed among the configured merchants or beneficiaries according to the defined split configuration.

​
Flexible Payment Distribution

Payment splitting can be used independently or together with Escrow:

Payment Split only

Automatically distribute a successful payment between multiple beneficiaries.

Escrow only

Hold a payment until it is released or canceled.

Escrow + Payment Split

Hold the payment in escrow and distribute it according to the configured split rules when released (or automatically if autoRelease is enabled).
This provides platforms with flexibility to choose whether payment distribution happens automatically after the initial payment (using autoRelease: true) or as part of the explicit escrow release lifecycle (using autoRelease: false). For standard one-party payments that do not require escrow or payment distribution, refer to the API Introduction.

​
Authentication

Escrow & Payment Split endpoints require authentication using the merchant API secret. Include your x-api-secret header with every request.
Keep your API secret secure and never expose it in client-side applications or publicly accessible code.

​
API Base URLs

Use the Sandbox environment for development and integration testing: