FAQ — Payment split

Recurring questions from integrators about recipient onboarding, KYC, splits, and withdrawals. For the full flow and endpoint references, see Payment split.

Overview and flow

What is the correct flow to register a recipient?

Follow these steps in order:

1. POST /recipient — returns recipient_hash.
2. POST /recipient/{recipient_hash}/facematch-link with the recipient's phone — triggers the SMS with the facematch link.
3. The recipient completes the facematch using the link received on their phone.
4. GET /recipient/{recipient_hash}/status — poll until it returns Onboarding completed.
5. From that point on, use the recipient_hash in POST /orders/{orderId}/split-order.

Do I need to register the marketplace as a recipient?

No. Recipients are only the partners that receive split amounts. The marketplace is the operating account that calls the APIs — it does not register itself as a recipient.

Does the recipient need to log into the Appmax dashboard?

No. The recipient flow is 100% API-based. The recipient does not access the dashboard and does not request withdrawals directly. The marketplace account executes withdrawals and anticipations on behalf of each recipient via the withdrawal endpoints.

Amounts, fees and split calculation

How is the Appmax fee charged when I use split?

The fee is charged to the marketplace on top of the gross order amount and is deducted automatically by Appmax — you do not send the fee in the payload of POST /orders/{orderId}/split-order. The applied rate is agreed commercially between the merchant and Appmax.

What is partner_total?

partner_total is the order amount minus the Appmax fees — that is, the net balance available to distribute among the recipients of the split. The sum of the amount values sent in the split is capped at this value.

What happens if the sum of amount exceeds partner_total?

The endpoint does not return an error. Appmax performs a proportional split capped at partner_total: the first recipients receive the requested value and the last one receives only the residual available.

Example: a R$ 100.00 order with a 5% fee → partner_total = R$ 95.00. If you send two recipients with R$ 50.00 each (summing R$ 100.00, above the cap):

• Recipient 1: R$ 50.00 (requested value)
• Recipient 2: R$ 45.00 (residual after partner_total is exhausted)

Since there is no error or warning, it is easy for the last recipient to receive less than expected without anyone noticing. Size your splits assuming there is always a fee applied.

Can I choose which recipient absorbs the order fee?

No. The fee is applied to the marketplace as a whole, and partner_total is a single cap shared by all recipients — there is no way to flag in the payload which one absorbs the cost. To work around this, calculate the split values leaving headroom for the fee.

Is there an endpoint to query the merchant fee before creating the order?

No. There is no public route to query the fee or partner_total upfront. The rate is agreed commercially between the merchant and Appmax — if you need the exact value for your integration, align with the commercial team that owns the account.

Recipient registration

Can I edit a recipient via API?

No. Once created, the recipient's data cannot be changed via API — there is no PATCH or PUT route. The fields submitted at creation time are used for validation against regulatory bodies. If you need to fix any field, open a ticket with Appmax support — the change is handled internally on a case-by-case basis.

Can I delete a recipient via API?

No. Deletion is handled internally by Appmax upon request from the marketplace through support. There is no public delete route.

I get "O valor indicado para o campo company.company document number já se encontra utilizado" when re-submitting. What should I do?

Each CNPJ maps to exactly one recipient on the platform. If the CNPJ has already been used — even if the previous record has wrong data — you cannot re-create it through the API. For tests, use a different CNPJ. In production, contact support to correct or remove the previous record.

Facematch and KYC

Why don't I get the facematch SMS in sandbox?

The sandbox environment does not send SMS. Test the facematch dispatch in production.

Is the phone sent in POST /recipient the same one that receives the facematch SMS?

No. The SMS is dispatched by the POST /recipient/{recipient_hash}/facematch-link call, using the phone field in that request body. This number does not have to match the account.phone provided at creation — use the number that should actually receive the SMS.

Status and eligibility

When is the recipient actually ready to receive splits?

Only when GET /recipient/{recipient_hash}/status returns Onboarding completed. In the Awaiting face match completion and Onboarding on verification states the recipient cannot yet be used in splits.

What does the Onboarding on verification status mean?

The status is derived from the outcome of the KYC checks — it is not a field flipped by hand. A recipient lands here when the facematch has already been received but one of the onboarding checks held automatic approval back.

The checks applied include, among others:

• CPF and CNPJ validation against the Brazilian federal revenue service (Receita Federal)
• PEP, OFAC and CSNU (international sanctions) lists
• QSA validation for the CNPJ — the provided CPF must appear in the company's ownership structure
• Facematch score below the minimum threshold
• Liveness (proof-of-life) check failed
• Face on the facematch does not match the document

Important: this status does not distinguish "still under review" from "permanently rejected". There is no automatic retry and no timeout for exiting this state — once a check fails, the recipient stays frozen in Onboarding on verification until manual action is taken.

Recommended action: if the recipient remains in this status for more than 24 to 48 business hours, open a support ticket with Appmax to check whether it needs reprocessing or was rejected. Do not sit in an infinite polling loop waiting for an automatic transition, do not try to re-create the recipient (the CNPJ will hit the "already in use" error), and do not leave your end-user's flow hanging without an escape hatch — surface the pending state to the merchant while you wait for a response.

See also

Full reference of the three recipient statuses, available transitions, and eligibility by state in Payment split status.