Payment split

Payment split lets you divide the net amount of an order between a marketplace and one or more pre-registered recipients. This guide walks through the end-to-end flow and product rules. Each individual endpoint is documented on the reference pages linked at the bottom of each section.

Flow overview

The process has three blocks:

1. Onboarding & KYC — register the recipient and complete the mandatory facematch.
2. Order split — divide the order's net value between the marketplace and the recipients.
3. Withdrawal — check balances and request a payout (with or without anticipation).

Rules

• Partial refunds are not allowed on split orders. Only full refunds.
• Split cannot be created or modified on orders with approved status. Create the split before payment approval.
• The split is calculated on the net amount of the order (after Appmax fees), not on the gross amount. Example:

Component	Amount
Order (gross)	R$ 100.00
Net amount (after fees)	R$ 90.00
Split to recipients	R$ 40.00
Marketplace balance	R$ 50.00

• All amounts in split and withdrawal payloads are always in cents (integers).

Recipient status

Recipient onboarding goes through three possible states, returned by GET /recipient/{recipient_hash}/status:

Status	Meaning
Awaiting face match completion	The recipient still needs to complete the facematch (KYC) via SMS.
Onboarding on verification	Data + facematch received, under review by Appmax.
Onboarding completed	Approved. The recipient can receive splits.

A recipient_hash can only be used in a split after it reaches Onboarding completed.

For the full status reference — transitions, eligibility per state, and withdraw request (WithdrawRequest) statuses — see Payment split status.

Endpoints per stage

Onboarding & KYC

1. Create a recipient — POST /recipient
2. Create facematch link (KYC) — POST /recipient/{recipient_hash}/facematch-link
3. Get recipient status — GET /recipient/{recipient_hash}/status

Order split

4. Create order split — POST /orders/{orderId}/split-order

Withdrawal

5. Get recipient balances — GET /recipient/{recipient_hash}/balances
6. Simulate withdrawal anticipation — GET /recipient/{recipient_hash}/withdraw-request/anticipation/simulate
7. Request withdrawal anticipation — POST /recipient/{recipient_hash}/withdraw-request/anticipation
8. Request withdrawal with available balance — POST /recipient/{recipient_hash}/withdraw-request/available
9. Get withdrawal request — GET /withdraw-request/{withdrawRequestId}

Withdrawal vs anticipation

There are two balance types and two distinct endpoints to withdraw them:

Balance type	Endpoint	Use
available	POST /recipient/{recipient_hash}/withdraw-request/available	Already released balance. Direct withdrawal, no anticipation fee.
to_release	POST /recipient/{recipient_hash}/withdraw-request/anticipation	Not-yet-released balance. Anticipated payout with fee applied.

Before requesting an anticipation, use the simulation endpoint to show the recipient the net amount and applied fee — the simulation does not create any request.

Authentication

All split routes use the same authentication scheme described in Authentication: Authorization: Bearer <token> with the merchant token obtained via POST /oauth2/token. App credentials do not work on these routes.

See also

TIP

Common questions about registration, editing, deletion, KYC and SMS are grouped in FAQ — Payment split.