Payment split status

Consolidated reference for every status an integrator may observe in Appmax's payment split flow — recipient status (returned by GET /recipient/{hash}/status) and withdraw request status (returned by withdraw-request endpoints). Use this page as an enum dictionary: what each value means, when it appears, what to expect next, and the recommended action.

For the full flow and code samples, see Payment split. For recurring operational questions, see FAQ.

Recipient status

Recipient status is returned by GET /recipient/{recipient_hash}/status as a string in the data field. There are three possible values, always in English.

Status	Meaning	Eligible for split?	Expected next action
Awaiting face match completion	Recipient created, waiting for the user to complete the facematch via SMS.	No	Send or resend the facematch link and wait for the user to complete it on their phone.
Onboarding on verification	Facematch received. KYC review in progress or held by a failed check.	No	Wait for automatic approval. If it remains here for more than 24-48 business hours, open a support ticket.
Onboarding completed	Onboarding approved. Recipient is enabled to receive splits and withdraw.	Yes	Use the recipient_hash in POST /orders/{orderId}/split-order.

State transitions

Transitions that do not exist

• There is no path back from Onboarding completed to any earlier state. Once approved, a recipient stays approved.
• There is no path from Onboarding on verification back to Awaiting face match completion. Calling POST /facematch-link again while in verification does not restart the review — the request is accepted but the status does not change.
• There is no public rejection or blocked state (rejected, denied, blocked). Rejected recipients remain frozen in Onboarding on verification.

Onboarding on verification in detail

This is the status that causes the most confusion because it collapses two different scenarios under the same label:

1. Review in progress — the facematch was received and the KYC pipeline is still processing. Typical window: minutes to a few hours.
2. Review held by a failed check — the pipeline finished processing, but one of the KYC criteria was not met. The recipient stays in this state indefinitely until manual action is taken by Appmax.

The GET /recipient/{hash}/status endpoint does not distinguish between these two cases. There is no reason field, no rejected status, and no webhook to notify the change.

Typical reasons for being held

Among the criteria checked during onboarding:

• CPF or CNPJ not validated against the Brazilian federal revenue service (Receita Federal)
• CNPJ without the responsible party's CPF in the QSA (company ownership structure)
• PEP (Politically Exposed Person)
• OFAC (US Treasury sanctions list)
• CSNU (UN Security Council sanctions list)
• Facematch score below the minimum threshold
• Liveness (proof-of-life) check failed
• Facematch photo does not match the ID document

Not every reason is surfaced to the integrator. What is returned is just the Onboarding on verification label.

No automatic retry, no timeout

The system does not automatically reprocess a recipient stuck in Onboarding on verification. There is no timeout to leave this state, no periodic retry, and no rejection notification. Calling POST /facematch-link again does not reactivate the document review — it only dispatches another facematch SMS, which on its own does not unlock the other checks.

Recommended action

• Up to 24-48 business hours in Onboarding on verification: wait. This is a normal processing window.
• Beyond that: open a support ticket with Appmax including the recipient_hash. The internal team checks whether reprocessing, manual review or a definitive rejection applies.
• Do not re-create the recipient: the CNPJ will return the company document number already in use error.
• Do not freeze the end user's flow: surface the pending state to the merchant and offer an escape hatch while you wait.

Withdraw request status

Every withdraw request — whether via available balance or via anticipation — carries a status field that represents where it sits in the financial processing cycle.

The immediate response from POST /withdraw-request/* endpoints always returns 2 (PENDING), as an integer (ID). Subsequent transitions happen in the background on Appmax's side. To track the updated status, use GET /withdraw-request/{withdrawRequestId} — which returns status already translated as a string (e.g. pending, approved, refused). There is no webhook that notifies transitions; tracking is always done by polling this endpoint.

This section documents the 17 possible statuses that may appear when querying a request, in reports, or during support tickets.

Terminal statuses

States that do not transition further. Once here, the request is done.

ID	Constant	Meaning	Integrator action
1	REFUSED	Request refused (validation error, insufficient balance after lock, review rejection, payment provider definitive failure).	Investigate the reason through support. If balance is available again, create a new request.
5	PAID	Amount settled — funds left the Appmax account to the recipient's bank account.	None. Flow completed successfully.

In-progress statuses

Intermediate states. The request is still being processed — wait for natural transition.

ID	Constant	Meaning	Integrator action
2	PENDING	Created. Waiting for processing or internal approval. This is the value returned in the immediate POST response.	None. Wait.
3	APPROVED	Approved internally. Waiting to be sent to the payment provider.	None. Wait.
4	PROCESSING	Being processed by the provider (cash-out or bank transfer).	None. Wait.
7	WAITING_RETURN	Waiting for payment provider response.	None. Wait.
8	INITIAL_ANALYSIS	Under initial review before approval.	None. Wait.
12	PIX_INCLUSION_IN_RETRY	PIX key inclusion in automatic retry with the provider.	None. Wait.
16	PIX_PROCESSING	PIX payment being processed by the provider.	None. Wait.
17	PIX_VALIDATION_API_UNAVAILABLE	The provider's PIX validation API is temporarily unavailable.	None. Wait, or open a ticket if it persists.

Statuses that require Appmax intervention

States in which something has stalled and depend on manual action from Appmax to unblock. If the request stays here for more than a few hours, open a ticket.

ID	Constant	Meaning	Integrator action
6	ON_HOLD	Manual block (risk review, additional verification).	Open a ticket if it does not unblock within a reasonable window.
9	PENDING_ACCREDITATION	Recipient not yet accredited at the cash-out provider.	Wait. Open a ticket if it persists.
10	APPROVED_BUT_NOT_INCLUDED	Approved internally but not included in a payment batch.	Open a ticket.
11	PIX_ACCOUNT_VALIDATION_FAIL	Provider failed to validate the recipient's PIX key.	Open a ticket to validate bank data.
13	PIX_EXPIRED_INCLUSION	PIX inclusion expired before completing.	Open a ticket.
14	PIX_INCLUDED_BUT_REPROVED	PIX was included but rejected by the provider.	Open a ticket.
15	PIX_MANUAL_PAYMENT	Requires manual PIX payment by Appmax's finance team.	Open a ticket.

withdrawal_blocked — invisible lateral state

There is a withdrawal block that does not show up in the recipient status or in the withdraw request itself. It is a lateral flag that Appmax can activate on the recipient's account for reasons such as risk, investigation or regulatory requirement. The practical effect:

• The recipient reports Onboarding completed normally.
• Balances exist and can be queried.
• But every attempt to create a withdraw request returns HTTP 403 with Withdraw not allowed.

If you get 403 on POST /withdraw-request/available or POST /withdraw-request/anticipation for a recipient that should be eligible, this is most likely the cause — open a support ticket including the recipient_hash.

Another case that also returns 403 (or 409 Withdraw request in progress) is when another request is already in progress for the same recipient in the same processing window. Wait for the previous one to finish before creating a new one.

Consolidated eligibility per recipient status

Cross-reference table showing, for each recipient status, what is and is not allowed:

Recipient status	Receive split on a new order	Has balances (GET /balances)	Withdraw available balance	Anticipate to-release balance
Awaiting face match completion	No	No (returns 404)	No	No
Onboarding on verification	No	No (returns 404)	No	No
Onboarding completed	Yes	Yes	Yes, unless withdrawal_blocked or withdraw in progress	Yes, unless withdrawal_blocked or withdraw in progress

About GET /balances: before Onboarding completed, the GET /recipient/{hash}/balances endpoint returns 404 Balance not found. This does not mean the recipient does not exist — it means balances have not been provisioned yet. Use GET /status as the primary source of recipient existence and eligibility.

What the status does not tell you

Split has no status of its own

The order-split entity does not have a separate lifecycle. A split's effective status follows the parent order status:

• Order pending → split created, waiting for approval.
• Order approved → split consolidated, amounts enter the recipients' balance flow.
• Order cancelled or refunded → split discarded together with the order.

There is no GET /split-order/{id}/status endpoint and no split_status field. There is no split-specific webhook either. To know whether a split was effectively applied, check the order status.

No webhook for recipient status changes

Today there is no event that notifies transitions of a recipient between Awaiting face match completion, Onboarding on verification and Onboarding completed. The integrator must poll the GET /status endpoint. There is also no webhook for WithdrawRequest transitions.

Recommendations:

• Poll at reasonable intervals (for example every 1-5 minutes during active onboarding, reducing cadence after the first hour).
• Avoid aggressive polling (more than 1 request per second) — the API has rate limits.
• For recipients stuck in Onboarding on verification for more than 24 business hours, stop polling and escalate to support.

Partial refunds are blocked on split orders

Orders with split only accept full refunds. Attempting a partial refund on an order that has a split returns a validation error. This is a product rule, not a status — detailed in Create order split.

Questions only support can answer

Some data is not exposed in the API and is not publicly documented — it requires a support ticket to be answered case by case:

• Which KYC provider is used for facematch and document checks. Not exposed in the API.
• Why a specific recipient landed in Onboarding on verification. The detailed reason (which check failed) is not returned.
• SLA for a specific recipient's review to complete. Only the typical window (24-48 business hours) is public.
• Expected transition time for a specific WithdrawRequest between states. Varies by provider and banking window.
• Reason for withdrawal_blocked on an account. Requires a ticket with the recipient_hash.

In all these cases, always include the recipient_hash (or withdraw_request_id when applicable) — it lets support locate the record immediately.

See also

• Payment split — overview
• FAQ — Payment split
• Get recipient status
• Get withdrawal request
• Create order split
• Order status