Payout

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/luniumpay-com/json-schema/luniumpay-com-payout-schema.json",
  "title": "Payout",
  "description": "Saque PIX (PIX→PIX) debitado do saldo custodial da chave.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/luniumpay-com-openapi.json#/components/schemas/Payout",
  "type": "object",
  "properties": {
    "payout_id": {
      "type": "string"
    },
    "customer_ref": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 80
    },
    "status": {
      "type": "string",
      "description": "processing, sent, failed ou refunded; use extrato para conciliar saldo. Estados novos devem ser tolerados."
    },
    "amount_cents": {
      "type": "integer",
      "description": "Valor que o destinatário recebe."
    },
    "fee_cents": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Total fees beyond amount_cents: fee_service_total_cents + fee_provider_cents. Includes partner commission already; do not add it again."
    },
    "fee_service_cents": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Lunium-only service fee in recorded cents; accounting component. For customer UI and notifications use fee_service_total_cents."
    },
    "fee_provider_cents": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Tarifa do provedor: fee_cents menos fee_service_cents menos fee_partner_cents."
    },
    "pix_key": {
      "type": "string"
    },
    "pix_key_type": {
      "type": "string",
      "enum": [
        "cpf",
        "cnpj",
        "phone",
        "email",
        "random"
      ]
    },
    "tax_number": {
      "type": [
        "string",
        "null"
      ],
      "description": "Documento do beneficiário mascarado, quando informado; opcional no pedido."
    },
    "external_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
      "maxLength": 64
    },
    "error": {
      "type": [
        "string",
        "null"
      ],
      "description": "Motivo quando failed/refunded."
    },
    "e2e": {
      "type": [
        "string",
        "null"
      ],
      "description": "EndToEndId do PIX enviado."
    },
    "receiver_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Nome obtido após o pagamento quando disponível. null quando não obtido."
    },
    "receiver_tax_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "paid_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "sent_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "verify_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Verificação pública do PIX (GET /v1/verificar/{e2e})."
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "sandbox": {
      "type": "boolean",
      "description": "True for fictitious sandbox operations."
    },
    "simulation": {
      "type": "object",
      "additionalProperties": true
    },
    "fee_partner_cents": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Sub fee do parceiro debitada do saldo neste saque (centavos). Parte de fee_cents."
    },
    "fee_service_total_cents": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "description": "Combined customer service fee: recorded Lunium fee plus partner commission. Preserves original cent rounding and historical pricing; null when the legacy house component is unknown. Included in payout responses and payout.* webhook data, production and sandbox. Add fee_provider_cents once to get fee_cents; do not add fee_partner_cents again."
    }
  }
}