Criar Payin

Cria uma nova requisição de pagamento para receber de um cliente. O método de pagamento determina os campos obrigatórios e os dados retornados na resposta.

POST https://api.legacyecombr.com.br/payin

📘
Autenticação obrigatória
Envie o cabeçalho Authorization: Basic base64(pk_live_xxxx:sk_live_yyyy) em todas as chamadas. Consulte o guia de Autenticação.

Corpo da requisição

Campos obrigatórios

Campo	Tipo	Descrição
`paymentMethod`	`string`	Método de pagamento: `PIX`, `BOLETO` ou `CREDIT_CARD`
`amount`	`integer`	Valor total em centavos (ex.: `10000` = R$100,00)
`referenceId`	`string`	Identificador único no seu sistema para conciliação
`isPhysicalProduct`	`boolean`	`true` se o pedido envolve entrega física; `false` para produtos digitais
`payerIp`	`string`	IP IPv4 do cliente pagador (usado pelo antifraude)
`customer`	`object`	Dados do cliente — veja estrutura abaixo
`items`	`array`	Lista de itens da cobrança — mínimo de 1 item

Campos opcionais

Campo	Tipo	Descrição
`webhookUrl`	`string (URL)`	URL para receber notificações de status via POST
`card`	`object`	Dados do cartão — obrigatório quando `paymentMethod` é `CREDIT_CARD`
`antifraud`	`object`	Dados de sessão do antifraude (sessionId, fingerprintId, deviceSessionId)
`subSellerId`	`string`	ID do sub-vendedor para operações de marketplace
`split`	`array`	Regras de split de pagamento entre múltiplos recebedores

Estrutura: `customer`

Campo	Tipo	Obrigatório	Descrição
`name`	`string`	✅	Nome completo do cliente
`document`	`string`	✅	CPF válido (somente dígitos)
`email`	`string`	✅	E-mail do cliente
`phone`	`string`	✅	Telefone com DDD (ex.: `5511999999999`)
`address.street`	`string`	✅	Logradouro
`address.number`	`string`	✅	Número
`address.zipCode`	`string`	✅	CEP
`address.city`	`string`	✅	Cidade
`address.state`	`string`	✅	UF (ex.: `SP`)
`address.complement`	`string`	❌	Complemento
`address.neighborhood`	`string`	❌	Bairro

Estrutura: `card` (apenas para `CREDIT_CARD`)

Campo	Tipo	Obrigatório	Descrição
`holderName`	`string`	✅*	Nome impresso no cartão
`number`	`string`	✅*	Número do cartão (sem espaços)
`expirationMonth`	`string`	✅*	Mês de validade (ex.: `08`)
`expirationYear`	`string`	✅*	Ano de validade (ex.: `2027`)
`cvv`	`string`	✅*	Código de segurança
`installments`	`integer`	✅	Número de parcelas (mínimo `1`)
`token`	`string`	❌	Token do cartão, substitui os campos marcados com `*`
`threeDSecure`	`object`	❌	Dados do 3DS para autenticação adicional

Estrutura: `items`

Campo	Tipo	Obrigatório	Descrição
`title`	`string`	✅	Nome do produto ou serviço
`quantity`	`integer`	✅	Quantidade (mínimo `1`)
`unitPrice`	`integer`	✅	Preço unitário em centavos
`description`	`string`	❌	Descrição opcional do item

Exemplo: PIX

Requisição:

{
  "paymentMethod": "PIX",
  "amount": 10000,
  "referenceId": "pedido-001",
  "webhookUrl": "https://sua-api.com/webhooks/legacy",
  "isPhysicalProduct": false,
  "payerIp": "200.100.50.3",
  "customer": {
    "name": "Maria Silva",
    "document": "83416281085",
    "email": "[email protected]",
    "phone": "5511999999999",
    "address": {
      "street": "Rua Exemplo",
      "number": "123",
      "zipCode": "01000-000",
      "city": "São Paulo",
      "state": "SP"
    }
  },
  "items": [
    {
      "title": "Produto Digital",
      "quantity": 1,
      "unitPrice": 10000
    }
  ]
}

Resposta 201 Created:

{
  "id": "payin_1A2B3C",
  "externalId": "tx_998877",
  "referenceId": "pedido-001",
  "status": "PENDING",
  "amount": 10000,
  "paymentMethod": "PIX",
  "createdAt": "2026-03-02T12:00:00.000Z",
  "pix": {
    "qrcode": "00020101021126360014br.gov.bcb.pix0114+5511999999999..."
  }
}

Exemplo: Boleto

Requisição: igual ao PIX, apenas mude "paymentMethod": "BOLETO".

Resposta 201 Created:

{
  "id": "payin_1A2B3D",
  "externalId": "tx_998878",
  "referenceId": "pedido-002",
  "status": "PENDING",
  "amount": 10000,
  "paymentMethod": "BOLETO",
  "createdAt": "2026-03-02T12:05:00.000Z",
  "boleto": {
    "barcode": "34191.09008 00000.000004 00000.000006 1 800000000010000",
    "url": "https://boleto.holdinglegacy.io/12346"
  }
}

Exemplo: Cartão de Crédito

🚧
KYC adicional obrigatório
O processamento de Cartão de Crédito requer aprovação de um KYC adicional. Entre em contato com o suporte para habilitação.

Requisição:

{
  "paymentMethod": "CREDIT_CARD",
  "amount": 29900,
  "referenceId": "pedido-003",
  "webhookUrl": "https://sua-api.com/webhooks/legacy",
  "isPhysicalProduct": false,
  "payerIp": "200.100.50.3",
  "customer": {
    "name": "João Oliveira",
    "document": "12345678900",
    "email": "[email protected]",
    "phone": "5511988887777",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "zipCode": "01310-100",
      "city": "São Paulo",
      "state": "SP"
    }
  },
  "card": {
    "holderName": "JOAO OLIVEIRA",
    "number": "4111111111111111",
    "expirationMonth": "08",
    "expirationYear": "2027",
    "cvv": "123",
    "installments": 1
  },
  "items": [
    {
      "title": "Plano Mensal",
      "quantity": 1,
      "unitPrice": 29900
    }
  ]
}

Resposta 201 Created:

{
  "id": "payin_1A2B3E",
  "externalId": "tx_998879",
  "referenceId": "pedido-003",
  "status": "APPROVED",
  "amount": 29900,
  "paymentMethod": "CREDIT_CARD",
  "createdAt": "2026-03-02T12:10:00.000Z"
}

📘
Cartão de Crédito é síncrono
Ao contrário de PIX e Boleto, o Cartão de Crédito retorna o status final (APPROVED ou REFUSED) diretamente na resposta, sem necessidade de aguardar webhook.

Erros comuns

Erro	Status	Causa
`INVALID_DATA`	400	CPF, telefone ou CEP inválido
`REJECTED_BY_RISK`	400	Transação negada pelo antifraude
`PAYER_LIMIT_REJECTED`	400	Limite insuficiente no cartão
`INVALID_CVV`	400	CVV incorreto
`PROVIDER_ERROR`	502	Falha temporária na adquirente

Autenticação obrigatória

Corpo da requisição

Campos obrigatórios

Campos opcionais

Estrutura: customer

Estrutura: card (apenas para CREDIT_CARD)

Estrutura: items

Exemplo: PIX

Exemplo: Boleto

Exemplo: Cartão de Crédito

KYC adicional obrigatório

Cartão de Crédito é síncrono

Erros comuns

Estrutura: `customer`

Estrutura: `card` (apenas para `CREDIT_CARD`)

Estrutura: `items`