Merchants

Um merchant é uma unidade de recebimento com saldo isolado. Um usuário (conta de API) pode ter vários — cada loja, marca ou cliente com sua própria contabilidade.

Modelo mental

Usuário (sua conta de API)
 ├── Merchant "Loja A"   → saldo próprio, extrato próprio
 ├── Merchant "Loja B"   → saldo próprio, extrato próprio
 └── Merchant "Loja C"   → saldo próprio, extrato próprio

Toda cobrança Pix pode criar ou referenciar um merchant: use o objeto merchant (cria/atualiza pelo externalId) ou o merchantId de um já existente. O dinheiro entra no saldo daquele merchant, sem se misturar com os demais.

Saldo: disponível vs. bloqueado

Cada merchant tem dois saldos (em centavos):

Campo	Significado
`balanceAvailable`	Pronto para sacar ou transferir
`balanceBlocked`	Retido (ex.: em análise, garantia, disputa/infração)

O bloqueio protege contra estornos e infrações (MED) do Pix. Valores podem migrar de blocked para available conforme as regras de liquidação.

Ciclo de vida

criado (isActive: true) ──> ativo ──> desativado (isActive: false)

Um merchant desativado deixa de receber novas cobranças, mas mantém histórico e saldo para reconciliação.

Operações

Criar um merchant

Não existe um endpoint dedicado de criação. Você cria (ou atualiza) o merchant dentro da própria cobrança Pix, pelo campo merchant. Ele é identificado pelo seu externalId, que funciona como chave de upsert: se já existir, é reaproveitado; se não, é criado na hora.

curl -X POST https://api.betpaympix.com/v1/pix \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 1990,
    "callbackUrl": "https://sualoja.com/webhooks/payerpix",
    "merchant": {
      "externalId": "loja-001",
      "name": "Loja Exemplo",
      "commissionBasisPoints": 500
    }
  }'

Campo	Obrigatório	Descrição
`merchant.externalId`	sim	Seu identificador do merchant (chave de upsert)
`merchant.name`	sim	Nome do merchant
`merchant.commissionBasisPoints`	não	Comissão em basis points (`500` = 5%)
`merchant.recipients`	não	Regras de split — ver Splits

Já criou o merchant numa cobrança anterior? Use merchantId (o UUID dele) no lugar do objeto merchant. Envie um ou outro — nunca os dois.

Listar merchants

curl https://api.betpaympix.com/v1/merchants \
  -H "Authorization: Bearer $API_TOKEN"

Retorna apenas os merchants da sua conta.

Consultar a carteira (saldo)

curl https://api.betpaympix.com/v1/merchants/{id}/wallet \
  -H "Authorization: Bearer $API_TOKEN"
# { "balanceAvailable": 18910, "balanceBlocked": 0, "total": 18910 }

Extrato do merchant

curl "https://api.betpaympix.com/v1/merchants/{id}/transactions?status=COMPLETED" \
  -H "Authorization: Bearer $API_TOKEN"

Filtros opcionais: status, dateFrom, dateTo. Cada item traz id, amount (centavos), status, type, datas e endToEndId.

Transferir saldo para o dono (sweep)

Move saldo disponível do merchant para a conta do usuário dono.

curl -X POST https://api.betpaympix.com/v1/merchants/{id}/transfer \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amount": 10000 }'

Use para consolidar o caixa de vários merchants na conta principal antes de um saque único.

Sacar direto do merchant (Pix)

Saca o saldo do merchant para uma chave Pix, sem passar pela conta do dono.

curl -X POST https://api.betpaympix.com/v1/merchants/{id}/withdraw \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 10000,
    "pixKey": "12345678909",
    "pixType": "CPF",
    "description": "Repasse loja",
    "callbackUrl": "https://sualoja.com/webhooks/payerpix"
  }'

Ver tipos de chave e estados em Saldos e Saques.

Segurança

A posse é validada no servidor: você só acessa merchants da sua própria conta. Tentativas em merchants de terceiros retornam MERCHANT_NOT_FOUND (ver Erros).

Sandbox e Mocks

Cobranças Pix