Skip to main content
POST
/
payin
Criar Payin
curl --request POST \
  --url https://api.holdinglegacy.io/payin \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "paymentMethod": "<string>",
  "amount": 123,
  "referenceId": "<string>",
  "webhookUrl": "<string>",
  "isPhysicalProduct": true,
  "payerIp": "<string>",
  "customer": {
    "name": "<string>",
    "document": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
      "street": "<string>",
      "number": "<string>",
      "complement": "<string>",
      "zipCode": "<string>",
      "city": "<string>",
      "state": "<string>"
    }
  },
  "items": [
    {
      "title": "<string>",
      "quantity": 123,
      "unitPrice": 123,
      "description": "<string>"
    }
  ],
  "card": {
    "token": "<string>",
    "holderName": "<string>",
    "number": "<string>",
    "expirationMonth": "<string>",
    "expirationYear": "<string>",
    "cvv": "<string>",
    "installments": 123,
    "threeDSecure": {
      "cavv": "<string>",
      "eci": "<string>",
      "xid": "<string>",
      "version": "<string>",
      "referenceId": "<string>",
      "authenticationId": "<string>"
    }
  },
  "antifraud": {
    "sessionId": "<string>"
  }
}
'

​
Autorização

Você deve obrigatoriamente fornecer sua credencial no cabeçalho.
​
Authorization
string
required
Use o Basic Auth base64 de suas chaves de produção. Ex: Basic cGtf...

​
Body

​
paymentMethod
string
required
Os valores aceitos são: "CREDIT_CARD", "PIX" ou "BOLETO"
​
amount
integer
required
Valor total da transação em centavos. Exemplo: para R$100,00 envie 10000
​
referenceId
string
required
ID único ou número do pedido dentro do banco de dados da sua aplicação associada à cobrança.
​
webhookUrl
string
Opcional. Uma URL do seu backend (https://...) que deverá ser notificada quando o status deste pagamento mudar (Ex: o Pix for pago).
​
isPhysicalProduct
boolean
required
Indica se o item cobrado exige entrega física (true) ou se é digital ou serviço (false).
​
payerIp
string
required
Endereço de IPv4 de quem está efetuando o pagamento originário (Necessário para a prevenção de Fraudes e Anti-Chargeback).

​
Customer (Cliente)

Objeto encapsulando quem está comprando de você.
​
customer
object
required

​
Items (Carrinho)

Array de objetos especificando o que está sendo comprado e taxado.
​
items
array
required

​
Card (Cartão de Crédito)

Se o paymentMethod escolhido foi "CREDIT_CARD", o objeto card é obrigatório. Para PIX e Boleto, omita este objeto por inteiro.
Recomendado: envie apenas card.token (gerado pelo SDK LegacyPay — veja Tokenização). Com o token, os campos de PAN bruto (number, cvv, etc.) são preenchidos com segurança pela plataforma e podem ser omitidos. Quando a tokenização é exigida, PAN bruto é rejeitado com 400 INVALID_DATA.
​
card
object

​
Antifraud (Antifraude)

Opcional. Identificador da sessão de device fingerprint coletada pelo SDK. Veja Antifraude.
​
antifraud
object

​
Response

A resposta varia ligeiramente dependendo do método de pagamento escolhido. A API sempre tentará devolver um 201 Created.

​
Sucesso: Criação de PIX

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

​
Sucesso: Criação de Boleto

{
  "id": "payin_12346",
  "externalId": "tx_998878",
  "referenceId": "meu-pedido-1235",
  "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://adquirente.holdinglegacy.io/boleto/12346"
  }
}

​
Sucesso: Cartão de Crédito

{
  "id": "payin_12347",
  "externalId": "tx_998879",
  "referenceId": "meu-pedido-1236",
  "status": "APPROVED",
  "amount": 10000,
  "paymentMethod": "CREDIT_CARD",
  "createdAt": "2026-03-02T12:10:00.000Z"
}

​
Pendente: Desafio 3DS (pós-ordem)

Quando a adquirente exige um desafio 3D Secure após a criação do payin, a resposta vem com status: "PENDING_3DS" e os campos do desafio. Use o SDK (client.handlePendingThreeDS()) para concluir. 
{
  "id": "payin_12348",
  "externalId": "tx_998880",
  "referenceId": "meu-pedido-1237",
  "status": "PENDING_3DS",
  "amount": 10000,
  "paymentMethod": "CREDIT_CARD",
  "threeDSecurePending": true,
  "threeDSecureSession": "eyJhbGciOiJIUzI1NiJ9...",
  "threeDSecureTransactionId": "05a1f7e4-d8c9-4c5e-b2a3-1f2e3d4c5b6a",
  "threeDSecureSdkUrl": "https://cdn.provider.com/3ds-sdk.min.js",
  "createdAt": "2026-03-02T12:15:00.000Z"
}
status: "APPROVED" na resposta do /payin não garante liquidação. Confirme sempre a venda final via webhook ou GET /payin/{id}.

​
Exemplo de request com cartão tokenizado

{
  "paymentMethod": "CREDIT_CARD",
  "amount": 29900,
  "referenceId": "pedido-003",
  "isPhysicalProduct": false,
  "payerIp": "200.100.50.3",
  "customer": { "name": "João Oliveira", "document": "12345678900", "email": "joao@email.com", "phone": "5511988887777" },
  "items": [{ "title": "Plano Mensal", "quantity": 1, "unitPrice": 29900 }],
  "card": {
    "token": "cvt_live_5XY8...",
    "installments": 1,
    "threeDSecure": { "cavv": "jJ2CBDUHAA0CAwECBQYGBAECBAE=", "eci": "05" }
  },
  "antifraud": { "sessionId": "mfp_live_abc123xyz" }
}