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`, `CREDIT_CARD` ou `OPEN_FINANCE`
`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`
`bankId`	`string`	Banco escolhido pelo cliente — usado quando `paymentMethod` é `OPEN_FINANCE`. Veja o guia de Open Finance
`antifraud`	`object`	Dados de sessão do antifraude — objeto com campo `sessionId`
`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: Open Finance

Requisição: use "paymentMethod": "OPEN_FINANCE" e, opcionalmente, bankId com o banco escolhido pelo cliente.

{
  "paymentMethod": "OPEN_FINANCE",
  "amount": 10000,
  "referenceId": "pedido-004",
  "isPhysicalProduct": false,
  "payerIp": "200.150.0.1",
  "bankId": "nubank",
  "webhookUrl": "https://sua-api.com/webhooks/legacy",
  "customer": {
    "name": "Maria Silva",
    "document": "12345678909",
    "email": "[email protected]",
    "phone": "5511999999999"
  },
  "items": [
    { "title": "Plano Premium", "quantity": 1, "unitPrice": 10000 }
  ]
}

Resposta 201 Created: retorna openFinanceRedirectUrl, para onde você deve redirecionar o cliente autorizar o pagamento no banco.

{
  "id": "payin_1A2B3E",
  "externalId": "of_1A2B3C",
  "referenceId": "pedido-004",
  "status": "PENDING",
  "amount": 10000,
  "paymentMethod": "OPEN_FINANCE",
  "createdAt": "2026-03-02T12:05:00.000Z",
  "openFinanceRedirectUrl": "https://autorizacao.banco.com.br/consent/abc123"
}

A confirmação chega de forma assíncrona via webhook. Detalhes do fluxo no guia de Open Finance.

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 geralmente é síncrono
Ao contrário de PIX e Boleto, o Cartão de Crédito geralmente retorna o status final (APPROVED ou REFUSED) diretamente na resposta. Exceção: quando o adquirente exige 3DS pós-order, a resposta retorna "threeDSecurePending": true com status PENDING_3DS — consulte a seção abaixo.

3DS pós-order

Quando o adquirente exige autenticação 3DS após a criação do payin, a resposta do cartão terá:

Campo	Tipo	Descrição
`status`	`string`	`"PENDING_3DS"` — aguardando conclusão do desafio
`threeDSecurePending`	`boolean`	`true` — indica que há um desafio aberto
`threeDSecureSession`	`string`	Session token para inicializar o SDK do adquirente
`threeDSecureTransactionId`	`string`	ID da transação 3DS no adquirente
`threeDSecureSdkUrl`	`string`	URL do script do SDK do adquirente a ser carregado

Com o SDK LegacyPay — use client.handlePendingThreeDS() para completar o desafio de forma provider-agnóstica:

var payinResponse = await fetch("/api/payin", { method: "POST", body: JSON.stringify(payload) })
  .then(r => r.json());

if (payinResponse.threeDSecurePending) {
  await client.handlePendingThreeDS(payinResponse, {
    card:         { holderName, number, expirationMonth, expirationYear, cvv, installments },
    customer:     { name, email, document, phone, address },
    amount:       payinResponse.amount,
    installments: 1,
  });
  // Desafio concluído — transação será confirmada via webhook ou polling.
}

Sem o SDK — não há suporte para desafios pós-order sem o SDK LegacyPay, pois o processo exige integração direta com o SDK do adquirente (ex: PagSeguro.authenticate3DS). Use sempre legacy-pay.js.

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: Open Finance

Exemplo: Cartão de Crédito

KYC adicional obrigatório

Cartão de Crédito geralmente é síncrono

3DS pós-order

Erros comuns

Estrutura: `customer`

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

Estrutura: `items`