Criar Payin

Cria uma nova cobrança via PIX, Boleto ou Cartão de Crédito.

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.pagamaster.com/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

CampoTipoDescrição
paymentMethodstringMétodo de pagamento: PIX, BOLETO, CREDIT_CARD ou OPEN_FINANCE
amountintegerValor total em centavos (ex.: 10000 = R$100,00)
referenceIdstringIdentificador único no seu sistema para conciliação
isPhysicalProductbooleantrue se o pedido envolve entrega física; false para produtos digitais
payerIpstringIP IPv4 do cliente pagador (usado pelo antifraude)
customerobjectDados do cliente — veja estrutura abaixo
itemsarrayLista de itens da cobrança — mínimo de 1 item

Campos opcionais

CampoTipoDescrição
webhookUrlstring (URL)URL para receber notificações de status via POST
cardobjectDados do cartão — obrigatório quando paymentMethod é CREDIT_CARD
bankIdstringBanco escolhido pelo cliente — usado quando paymentMethod é OPEN_FINANCE. Veja o guia de Open Finance
antifraudobjectDados de sessão do antifraude — objeto com campo sessionId
subSellerIdstringID do sub-vendedor para operações de marketplace
splitarrayRegras de split de pagamento entre múltiplos recebedores

Estrutura: customer

CampoTipoObrigatórioDescrição
namestring✅Nome completo do cliente
documentstring✅CPF válido (somente dígitos)
emailstring✅E-mail do cliente
phonestring✅Telefone com DDD (ex.: 5511999999999)
address.streetstring✅Logradouro
address.numberstring✅Número
address.zipCodestring✅CEP
address.citystring✅Cidade
address.statestring✅UF (ex.: SP)
address.complementstring❌Complemento
address.neighborhoodstring❌Bairro

Estrutura: card (apenas para CREDIT_CARD)

CampoTipoObrigatórioDescrição
holderNamestring✅*Nome impresso no cartão
numberstring✅*Número do cartão (sem espaços)
expirationMonthstring✅*Mês de validade (ex.: 08)
expirationYearstring✅*Ano de validade (ex.: 2027)
cvvstring✅*Código de segurança
installmentsinteger✅Número de parcelas (mínimo 1)
tokenstring❌Token do cartão, substitui os campos marcados com *
threeDSecureobject❌Dados do 3DS para autenticação adicional
deviceobject❌Dados do navegador do comprador, coletados pelo SDK (prepared.payinCard.device). Repasse como veio, sem montar nem validar
userAgentstring❌User agent do navegador do comprador (prepared.payinCard.userAgent). Repasse junto com device

Com o SDK, envie o prepared.payinCard inteiro (ou use buildPayinPayload()). Se o seu servidor escolhe
campos, mantenha token, installments, threeDSecure, device e userAgent: sem os dois últimos, conforme
a adquirente, a venda perde a autenticação sem desafio ou é recusada. Veja 3DS.

Estrutura: items

CampoTipoObrigatórioDescrição
titlestring✅Nome do produto ou serviço
quantityinteger✅Quantidade (mínimo 1)
unitPriceinteger✅Preço unitário em centavos
descriptionstring❌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://api.pagamaster.com/boletos/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 vem com "threeDSecurePending": true e o status permanece PENDING — 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á:

CampoTipoDescrição
statusstring"PENDING" — não existe status PENDING_3DS na resposta; quem sinaliza o desafio é o campo abaixo
threeDSecurePendingbooleantrue — o único campo que você precisa ler
threeDSecureProviderstringInterno ao SDK — não interprete, mas repasse
threeDSecureSdkUrlstringInterno ao SDK — não interprete, mas repasse
threeDSecureActionobjectInterno ao SDK — não interprete, mas repasse
⚠️

Se você chama o /payin a partir do seu servidor, repasse a resposta inteira ao browser.

"Interno ao SDK" quer dizer que você não deve interpretar esses campos — não que possa
descartá-los. O handlePendingThreeDS() escolhe como conduzir o desafio a partir do
threeDSecureProvider e precisa do threeDSecureAction para executá-lo. Se o seu backend
devolver ao browser só { id, status, threeDSecurePending }, o SDK não tem como saber qual
desafio conduzir e falha com um erro que não aponta para a causa
(SCRIPT_URL_REQUIRED ou THREEDS_SDK_UNAVAILABLE).

Entregue ao handlePendingThreeDS() o mesmo objeto que o /payin devolveu, sem podar.

🚨

O status continua PENDING — o mesmo de um PIX aguardando pagamento.

Se o seu checkout decidir a tela pelo status, ele trata a venda como recebida e segue para
"pedido confirmado" com o desafio ainda aberto. O comprador vê a tela de sucesso, o desafio
aparece por cima dela (ou não aparece) e a venda morre quando a sessão expira, em 15 minutos.
Decida pelo threeDSecurePending, nunca pelo status.

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

// Use a MESMA instância de `client` que chamou prepareCardPayment(): handlePendingThreeDS()
// desliga o watcher de retomada automática daquela instância. Um client novo deixa o watcher
// antigo vivo, e os dois disputam o mesmo desafio.
var payinResponse = await fetch("/api/payin", { method: "POST", body: JSON.stringify(payload) })
  .then(r => r.json());

if (payinResponse.threeDSecurePending) {
  try {
    await client.handlePendingThreeDS(payinResponse);
  } catch (err) {
    if (err.code === "THREEDS_EXPIRED") {
      // O comprador demorou mais que a sessão do desafio. É retentável, mas exige criar uma
      // venda NOVA — nunca reaproveite o mesmo desafio.
    } else {
      // THREEDS_FAILED: autenticação não concluída.
    }
    return; // não mostre "pedido confirmado"
  }
}
// Desafio concluído — a confirmação definitiva chega pelo webhook.
📘

Não passe dados de cartão para handlePendingThreeDS()

O desafio pós-order é concluído só com o que o servidor devolveu. Reter o cartão no browser
para isso amplia o seu escopo PCI sem necessidade.

⚙️

CSP: o desafio carrega, sob demanda, o script do fornecedor de 3DS e o do emissor

do cartão. Esses domínios mudam por emissor e não são conhecidos de antemão — uma
Content-Security-Policy com allowlist fixa bloqueia o desafio. Libere script-src,
connect-src e frame-src para esse fluxo.

Sem o SDK — não há suporte para desafios pós-order sem o SDK LegacyPay: concluir o desafio exige falar diretamente com o SDK do adquirente, que muda por adquirente e por emissor. Use sempre legacy-pay.js.

O fluxo completo, com os erros mais comuns de integração, está em Autenticação 3D Secure (3DS).


Erros comuns

ErroStatusCausa
INVALID_DATA400CPF, telefone ou CEP inválido
REJECTED_BY_RISK400Transação negada pelo antifraude
PAYER_LIMIT_REJECTED400Limite insuficiente no cartão
INVALID_CVV400CVV incorreto
PROVIDER_ERROR502Falha temporária na adquirente

Did this page help you?