Ordens de Split de Pagamentos

Este guia descreve como consultar ordens e payouts de Split de Pagamentos e como solicitar o processamento forçado ou o cancelamento de um payout.

Conceitos

Ordem de split: registra a divisão associada a um cash-in recebido. Uma ordem pode conter um ou mais payouts.
Payout: valor destinado a um beneficiário, com uma instrução de transferência e um estado próprio.
Origem das instruções: em cash-ins PIX, as instruções do QR Code são usadas quando presentes. Se não houver instruções no QR Code, o sistema consulta a configuração de split da conta recebedora. Sem instrução e sem configuração, não é gerada uma ordem de split para aquele fluxo.
Base do split: valor bruto do cash-in menos a tarifa, quando a cobrança da tarifa antes do split estiver habilitada.

Payouts com data de pagamento futura ficam agendados. Payouts elegíveis para a data corrente podem seguir para processamento sem uma chamada manual. A API permite consultar o andamento e, quando aplicável, solicitar novamente o processamento ou cancelar a operação.

Payouts só podem ser agendados através das instruções de split na criação do qr code.

Endpoints

Prefixo comum: /baas/api/v1/split-payments

Consultar ordens

Use GET /orders para buscar uma ordem específica ou listar as ordens da conta.

Parâmetro	Obrigatório	Descrição
`id`	Não	Identificador da ordem.
`transactionId`	Não	Identificador da transação original de cash-in associada à ordem.
`page`	Não	Página da listagem. Padrão: `1`.
`limit`	Não	Itens por página. Padrão: `10`; valores acima de `100` são limitados a `100`.

id e transactionId são mutuamente exclusivos. Quando nenhum dos dois é informado, a resposta será uma listagem paginada.

curl --location 'https://api.delbank.com.br/baas/api/v1/split-payments/orders?id=12345' \
--header 'x-delbank-api-key: {{apiKey}}'

curl --location 'https://api.delbank.com.br/baas/api/v1/split-payments/orders?transactionId=ID-DO-CASHIN' \
--header 'x-delbank-api-key: {{apiKey}}'

curl --location 'https://api.delbank.com.br/baas/api/v1/split-payments/orders?page=1&limit=20' \
--header 'x-delbank-api-key: {{apiKey}}'

{
    "id": 12345,
    "transactionOriginalId": "ID-DO-CASHIN",
    "grossAmount": 10.00,
    "tariffAmount": 0.25,
    "splitBaseAmount": 9.75,
    "source": {
        "name": "QR_CODE",
        "description": "QrCode",
        "value": 0
    },
    "createdAt": "2025-09-22T12:00:00.000Z",
    "payouts": [
        {
            "id": 12545,
            "splitOrderId": 12345,
            "beneficiary": {
                "bankIspb": "ISPBCODE",
                "bankAccountNumber": "12345",
                "bankAccountBranch": "0001",
                "holderDocument": "01234567890",
                "holderName": "Nome do beneficiário",
                "bankAccountType": "Tipo da conta bancária do beneficiário"
            },
            "transferType": {
                "name": "PIX_MANUAL",
                "description": "Pix Manual",
                "value": 2
            },
            "instructionType": {
                "name": "PERCENTAGE",
                "description": "Porcentagem",
                "value": 0
            },
            "instructionAmount": 85.00,
            "amount": 8.29,
            "paymentDate": "2025-09-22T12:00:00.000Z",
            "status": {
                "name": "SUCCESS",
                "description": "Sucesso",
                "value": 1
            },
            "transactionId": "ID-DO-SPLIT-CASHOUT",
            "endToEndId": "E2E-DO-SPLIT-CASHOUT",
            "paidAt": "2025-09-22T12:00:00.000Z",
            "createdAt": "2025-09-22T12:00:00.000Z",
            "updatedAt": "2025-09-22T12:00:00.000Z"
        }
    ]
}

[
    {
        "id": 12345,
        "transactionOriginalId": "ID-DO-CASHIN",
        "grossAmount": 10.00,
        "tariffAmount": 0.25,
        "splitBaseAmount": 9.75,
        "source": {
            "name": "QR_CODE",
            "description": "QrCode",
            "value": 0
        },
        "createdAt": "2025-09-22T12:00:00.000Z"
    },
    {
        "id": 12346,
        "transactionOriginalId": "ID-DO-CASHIN",
        "grossAmount": 100.00,
        "tariffAmount": 0.00,
        "splitBaseAmount": 100.00,
        "source": {
            "name": "QR_CODE",
            "description": "QrCode",
            "value": 0
        },
        "createdAt": "2025-09-26T12:00:00.000Z"
    }
]

{
    "currentPage": 1,
    "pageSize": 20,
    "pageCount": 1,
    "rowCount": 2
}

A consulta individual retorna HTTP 200 e uma ordem com seus payouts. Se a ordem não existir ou não pertencer à conta da credencial, a API retorna 404. Informar id e transactionId juntos retorna 400. A listagem também retorna HTTP 200; por padrão, o corpo é um array. Para receber metadados de paginação no corpo, use include=metadata. Nesse formato, os itens ficam em data e os metadados em metadata.

Consultar payouts

Use GET /payouts para consultar payouts da conta vinculada à credencial, com filtros opcionais.

Parâmetro	Obrigatório	Descrição
`beneficiaryDocument`	Não	CPF ou CNPJ do beneficiário.
`beneficiaryName`	Não	Nome do beneficiário; a busca aceita correspondência parcial.
`startDate`	Não	Data inicial para filtrar pela criação do payout.
`endDate`	Não	Data final para filtrar pela criação do payout.
`status`	Não	Estado do payout. Valores: `PENDING`, `PROCESSING`, `SUCCESS`, `ERROR`, `SCHEDULED` ou `CANCELED`.
`page`	Não	Página da listagem. Padrão: `1`.
`limit`	Não	Itens por página. Padrão: `10`.

curl --location 'https://api.delbank.com.br/baas/api/v1/split-payments/payouts?beneficiaryDocument=12345678901&status=ERROR&page=1&limit=10' \
--header 'x-delbank-api-key: {{apiKey}}'

[
    {
        "id": 98765,
        "splitOrderId": 12345,
        "beneficiary": {
            "bankIspb": "ISPBCODE",
            "bankAccountNumber": "12345",
            "bankAccountBranch": "0001",
            "holderDocument": "12345678901",
            "holderName": "Nome do beneficiário",
            "bankAccountType": "Tipo da conta bancária do beneficiário"
        },
        "transferType": {
            "name": "PIX_MANUAL",
            "description": "Pix Manual",
            "value": 2
        },
        "instructionType": {
            "name": "PERCENTAGE",
            "description": "Porcentagem",
            "value": 0
        },
        "instructionAmount": 85.00,
        "amount": 8.29,
        "paymentDate": "2025-09-22T12:00:00.000Z",
        "status": {
            "name": "ERROR",
            "description": "Error",
            "value": 2
        },
        "transactionId": "ID-DO-SPLIT-CASHOUT",
        "endToEndId": "E2E-DO-SPLIT-CASHOUT",
        "errorMessage": "Banco rejeitou a transferência",
        "paidAt": "2025-09-22T12:00:00.000Z",
        "createdAt": "2025-09-22T12:00:00.000Z",
        "updatedAt": "2025-09-22T12:00:00.000Z",
        "splitOrder": {
            "id": 12345,
            "transactionOriginalId": "ID-DO-CASHIN",
            "grossAmount": 10.00,
            "tariffAmount": 0.25,
            "splitBaseAmount": 9.75,
            "source": {
                "name": "QR_CODE",
                "description": "QrCode",
                "value": 0
            },
            "createdAt": "2025-09-22T12:00:00.000Z",
        }
    }
]

{
    "currentPage": 1,
    "pageSize": 10,
    "pageCount": 1,
    "rowCount": 1
}

Cada payout pode incluir campos como id, splitOrderId, beneficiary, transferType, instructionType, instructionAmount, amount, paymentDate, status, transactionId, endToEndId, errorMessage, cancellationDetails, paidAt, createdAt e updatedAt. A resposta também pode incluir um resumo da ordem em splitOrder. Os estados representam:

PENDING: aguardando processamento;
PROCESSING: em processamento;
SUCCESS: concluído;
ERROR: falha;
SCHEDULED: agendado;
CANCELED: cancelado.

Use o campo status.name ou status.description quando precisar identificar o estado da operação. O valor numérico do enum não é o identificador mais legível para a lógica de integração.

Solicitar processamento

Use POST /payouts/process para reenviar um ou mais payouts para processamento quando eles estiverem elegíveis.

POST /baas/api/v1/split-payments/payouts/process
Content-Type: application/json

{
  "splitPayoutIds": [98765, 98766]
}

Payouts elegíveis para solicitação de processamento podem estar nos estados PENDING, SCHEDULED e ERROR. A resposta 202 Accepted confirma que a solicitação foi recebida, mas não que a transferência foi concluída. Consulte GET /payouts para acompanhar a evolução do estado.

Envie apenas IDs pertencentes à conta autenticada. IDs inexistentes, de outra conta ou em estados não elegíveis podem ser ignorados sem rejeição individual na resposta.

Cancelar payout

Use PATCH /payouts/cancel para solicitar o cancelamento de um payout em SCHEDULED ou ERROR.

PATCH /baas/api/v1/split-payments/payouts/cancel
Content-Type: application/json

{
  "splitPayoutId": 98765,
  "reason": "Solicitação do cliente",
  "canceledBy": "Nome ou identificação do solicitante"
}

splitPayoutId identifica o payout; reason registra o motivo e canceledBy identifica quem solicitou o cancelamento. Se canceledBy não for informado, a API registra Não informado. Em caso de sucesso, a resposta é 202 Accepted; o estado passa para CANCELED e os dados ficam disponíveis em cancellationDetails na consulta de payouts.

Fluxo de alto nível

Boas práticas de integração

Guarde transactionOriginalId e id da ordem para conciliar os payouts com o cash-in.
Use GET /orders?transactionId=... para localizar a ordem pela transação original e GET /payouts para acompanhar cada beneficiário.
Trate o processamento como assíncrono: após uma resposta 202, consulte novamente o payout até obter o estado final.
Solicite cancelamento apenas para payouts em SCHEDULED ou ERROR; pagamentos já em processamento ou concluídos não são cancelados por esta rota.
Solicite o processamento forçado apenas quando o payout ficou travado em PENDING, quando houver erro elegível para reprocessamento ou quando for necessário antecipar um payout agendado.

Referência da API

Consultar Ordens de Split

GET /baas/api/v1/split-payments/orders

Consultar Split Payouts

GET /baas/api/v1/split-payments/payouts

Cancelar Split Payout

PATCH /baas/api/v1/split-payments/payouts/cancel

Introdução

Autenticação

Receber via Pix (Pix Cash-in)

Pagar via Pix (Pix Cash-out)

Pagar via TED (TED Cash-out)

Pagar boletos e contas (Cash-out)

Cobranças via Boleto

Split de Pagamentos

Saldo e extrato

Webhooks

Ordens de Split de Pagamentos

Conceitos

Endpoints

Consultar ordens

Consultar payouts

Solicitar processamento

Cancelar payout

Fluxo de alto nível

Boas práticas de integração

Referência da API

Consultar Ordens de Split

Consultar Split Payouts

Cancelar Split Payout

​Conceitos

​Endpoints

​Consultar ordens

​Consultar payouts

​Solicitar processamento

​Cancelar payout

​Fluxo de alto nível

​Boas práticas de integração

​Referência da API

Consultar Ordens de Split

Consultar Split Payouts

Cancelar Split Payout

Conceitos

Endpoints

Consultar ordens

Consultar payouts

Solicitar processamento

Cancelar payout

Fluxo de alto nível

Boas práticas de integração

Referência da API