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óriaEnvie 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
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)
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 |
device | object | ❌ | Dados do navegador do comprador, coletados pelo SDK (prepared.payinCard.device). Repasse como veio, sem montar nem validar |
userAgent | string | ❌ | User agent do navegador do comprador (prepared.payinCard.userAgent). Repasse junto com device |
Com o SDK, envie o
prepared.payinCardinteiro (ou usebuildPayinPayload()). Se o seu servidor escolhe
campos, mantenhatoken,installments,threeDSecure,deviceeuserAgent: sem os dois últimos, conforme
a adquirente, a venda perde a autenticação sem desafio ou é recusada. Veja 3DS.
Estrutura: items
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://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órioO 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íncronoAo contrário de PIX e Boleto, o Cartão de Crédito geralmente retorna o status final (
APPROVEDouREFUSED) diretamente na resposta. Exceção: quando o adquirente exige 3DS pós-order, a resposta vem com"threeDSecurePending": truee o status permanecePENDING— 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" — não existe status PENDING_3DS na resposta; quem sinaliza o desafio é o campo abaixo |
threeDSecurePending | boolean | true — o único campo que você precisa ler |
threeDSecureProvider | string | Interno ao SDK — não interprete, mas repasse |
threeDSecureSdkUrl | string | Interno ao SDK — não interprete, mas repasse |
threeDSecureAction | object | Interno ao SDK — não interprete, mas repasse |
Se você chama o/payina 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. OhandlePendingThreeDS()escolhe como conduzir o desafio a partir do
threeDSecureProvidere precisa dothreeDSecureActionpara 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_REQUIREDouTHREEDS_SDK_UNAVAILABLE).Entregue ao
handlePendingThreeDS()o mesmo objeto que o/payindevolveu, sem podar.
O status continuaPENDING— 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 pelothreeDSecurePending, nunca pelostatus.
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 parahandlePendingThreeDS()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 emissordo 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. Liberescript-src,
connect-srceframe-srcpara 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
| 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 |
Updated 12 days ago
