Split de pagamentos
O split de pagamentos permite dividir o valor líquido de um pedido entre um marketplace e um ou mais recebedores (recipients) previamente cadastrados. Este guia apresenta o fluxo de ponta a ponta e as regras do produto. Os endpoints individuais estão detalhados nas páginas de referência linkadas ao final de cada etapa.
Visão geral do fluxo
O processo se divide em três blocos:
- Onboarding & KYC — cadastro do recebedor e verificação facial obrigatória.
- Split de pedido — divisão do valor líquido do pedido entre marketplace e recebedores.
- Saque — consulta de saldo e solicitação de retirada (com ou sem antecipação).
Regras
- Estornos parciais não são permitidos em pedidos com split. Só estorno total.
- Não é permitido criar ou alterar o split de pedidos que já estão com status
aprovado. Crie o split antes da aprovação do pagamento. - O split é calculado sobre o valor líquido do pedido (após taxas da Appmax), não sobre o valor bruto. Exemplo:
| Componente | Valor |
|---|---|
| Pedido (bruto) | R$ 100,00 |
| Valor líquido (após taxas) | R$ 90,00 |
| Split para recebedores | R$ 40,00 |
| Saldo do marketplace | R$ 50,00 |
- Os valores nos payloads de split e saque são sempre informados em centavos (inteiros).
Status do recebedor
O onboarding do recipient passa por três estados possíveis, retornados por GET /recipient/{recipient_hash}/status:
| Status | Significado |
|---|---|
Awaiting face match completion | Recebedor ainda precisa completar o facematch (KYC) via SMS. |
Onboarding on verification | Dados + facematch recebidos, em análise pela Appmax. |
Onboarding completed | Cadastro aprovado. Recebedor habilitado a receber splits. |
Só é possível usar o recipient_hash em um split depois do status Onboarding completed.
Para a referência completa dos status — transições, elegibilidade por estado e status de solicitações de saque (WithdrawRequest) — consulte Status do split de pagamentos.
Etapas e endpoints
Onboarding & KYC
- Criar um recebedor —
POST /recipient - Criar link de facematch (KYC) —
POST /recipient/{recipient_hash}/facematch-link - Consultar status do recebedor —
GET /recipient/{recipient_hash}/status
Split de pedido
- Criar split de pedido —
POST /orders/{orderId}/split-order
Saque
- Consultar saldos do recebedor —
GET /recipient/{recipient_hash}/balances - Simular antecipação de saque —
GET /recipient/{recipient_hash}/withdraw-request/anticipation/simulate - Solicitar antecipação de saque —
POST /recipient/{recipient_hash}/withdraw-request/anticipation - Solicitar saque com saldo disponível —
POST /recipient/{recipient_hash}/withdraw-request/available - Consultar solicitação de saque —
GET /withdraw-request/{withdrawRequestId}
Diferença entre saque e antecipação
Há dois tipos de saldo e dois endpoints distintos para retirá-los:
| Tipo de saldo | Endpoint | Uso |
|---|---|---|
available | POST /recipient/{recipient_hash}/withdraw-request/available | Saldo já liberado. Saque direto, sem taxa de antecipação. |
to_release | POST /recipient/{recipient_hash}/withdraw-request/anticipation | Saldo ainda em compensação. Retirada antecipada com taxa aplicada. |
Antes de solicitar uma antecipação, use o endpoint de simulação para exibir ao recebedor o valor líquido e a taxa aplicada — a simulação não cria solicitação nenhuma.
Autenticação
Todas as rotas de split usam o mesmo esquema de autenticação descrito em Autenticação: Authorization: Bearer <token> com o token do merchant obtido via POST /oauth2/token. Credenciais do app não funcionam nessas rotas.
Veja também
TIP
Dúvidas comuns sobre cadastro, edição, exclusão, KYC e SMS estão reunidas em Perguntas frequentes — Split de pagamentos.