Criar Transação

Crie uma nova transação (venda) na plataforma. Você pode processar pagamentos via PIX, Cartão de Crédito, Cartão de Débito ou Boleto.

Autenticação

Este endpoint requer autenticação via API Keys:

X-Api-Public-Key

string

required

Sua chave pública da API

X-Api-Private-Key

string

required

Sua chave privada da API

Parâmetros do Body

amount

integer

required

Valor da transação em centavos (ex: 10000 = R$ 100,00)

paymentMethod

string

required

Método de pagamento. Valores possíveis: CREDIT_CARD, DEBIT_CARD, BOLETO, PIX, TRANSFER

customer

object

required

Dados do cliente

customer.name

string

required

Nome completo do cliente

customer.email

string

required

Email do cliente

customer.document

object

Documento do cliente (CPF ou CNPJ)

customer.document.type

string

Tipo do documento: cpf ou cnpj

customer.document.number

string

Número do documento

customer.phone

string

Telefone do cliente no formato 11999999999 (sem caracteres especiais)

card

object

Informações do cartão (obrigatório para CREDIT_CARD ou DEBIT_CARD)

card.number

string

Número do cartão (será tokenizado - apenas últimos 4 dígitos são armazenados)

card.holderName

string

Nome do portador do cartão (será tokenizado)

card.expirationMonth

string

Mês de expiração no formato MM

card.expirationYear

string

Ano de expiração no formato YYYY

card.cvv

string

CVV do cartão (não é armazenado conforme PCI DSS)

card.installments

integer

Número de parcelas (apenas para cartão de crédito)

pix

object

Informações do PIX (obrigatório para PIX)

pix.key

string

Chave PIX do recebedor

pix.expiresInDays

integer

Número de dias para expiração do PIX

boleto

object

Informações do boleto (obrigatório para BOLETO)

boleto.expiresInDays

integer

Número de dias para expiração do boleto

items

array

required

Lista de itens da transação

items[].title

string

required

Nome do produto

items[].unitPrice

integer

required

Preço unitário em centavos

items[].quantity

integer

required

Quantidade do item

items[].tangible

boolean

required

Se o item é físico (true) ou digital (false)

items[].productId

integer

ID do produto (opcional)

items[].planId

string

ID do plano (opcional)

items[].planName

string

Nome do plano (opcional)

items[].id

string

ID customizado do item (opcional)

shipping

object

Informações de entrega (obrigatório quando há itens físicos com tangible: true)

shipping.street

string

Rua

shipping.streetNumber

string

Número

shipping.complement

string

Complemento

shipping.zipCode

string

CEP

shipping.neighborhood

string

Bairro

shipping.city

string

Cidade

shipping.state

string

Estado (2 dígitos em maiúscula, ex: SP)

shipping.country

string

País (2 dígitos, ex: br)

installments

object

Configuração de parcelas (apenas para cartão de crédito)

installments.number

integer

Número de parcelas (1 a 12)

postbackUrl

string

URL para receber notificações de mudança de status da venda

utmSource

string

Origem da campanha (UTM Source)

utmMedium

string

Meio da campanha (UTM Medium)

utmCampaign

string

Nome da campanha (UTM Campaign)

utmContent

string

Conteúdo da campanha (UTM Content)

utmTerm

string

Termo da campanha (UTM Term)

src

string

Fonte personalizada

sck

string

Código de campanha personalizado

metadata

object

Dados adicionais da venda (objeto JSON livre)

Exemplos de Requisição

Nota sobre os exemplos: Os dados apresentados são apenas exemplos didáticos. Substitua:

sua_chave_publica_aqui e sua_chave_privada_aqui pelas suas chaves de API reais
seupostbackurl.com.br pela URL do seu servidor que receberá as notificações
Os dados do cliente, cartão e produtos pelos dados reais da sua aplicação

PIX - Produto Digital
PIX - Produto Físico
Cartão de Crédito

curl -X POST https://api.nextpagamentos.io/api/sales \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "paymentMethod": "PIX",
    "customer": {
      "name": "João Silva Santos",
      "email": "[email protected]",
      "document": {
        "type": "cpf",
        "number": "12345678900"
      },
      "phone": "11999999999"
    },
    "items": [
      {
        "title": "Produto Digital - Assinatura Premium",
        "unitPrice": 5000,
        "quantity": 1,
        "tangible": false
      }
    ],
    "postbackUrl": "https://seupostbackurl.com.br/webhook/transacao",
    "metadata": {
      "source": "website",
      "campaign": "promocao-verao-2025"
    }
  }'

curl -X POST https://api.nextpagamentos.io/api/sales \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15680,
    "paymentMethod": "PIX",
    "customer": {
      "name": "Maria Santos Oliveira",
      "email": "[email protected]",
      "document": {
        "type": "cpf",
        "number": "98765432100"
      },
      "phone": "11988887777"
    },
    "items": [
      {
        "title": "Curso Avançado de Desenvolvimento Web",
        "unitPrice": 15680,
        "quantity": 1,
        "tangible": true
      }
    ],
    "shipping": {
      "street": "Rua das Flores",
      "streetNumber": "123",
      "complement": "Apartamento 45",
      "zipCode": "04567-010",
      "neighborhood": "Jardim Paulista",
      "city": "São Paulo",
      "state": "SP",
      "country": "br"
    },
    "postbackUrl": "https://seupostbackurl.com.br/webhook/transacao",
    "metadata": {
      "source": "website",
      "campaign": "promocao-verao-2025"
    }
  }'

curl -X POST https://api.nextpagamentos.io/api/sales \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "paymentMethod": "CREDIT_CARD",
    "installments": {
      "number": 1
    },
    "customer": {
      "name": "Carlos Eduardo Pereira",
      "email": "[email protected]",
      "document": {
        "type": "cpf",
        "number": "11122233344"
      },
      "phone": "11977776666"
    },
    "card": {
      "number": "4111111111111111",
      "holderName": "CARLOS E PEREIRA",
      "expirationMonth": "12",
      "expirationYear": "2025",
      "cvv": "123"
    },
    "items": [
      {
        "id": "produto-001",
        "title": "Produto Digital - Licença Anual",
        "unitPrice": 10000,
        "quantity": 1,
        "tangible": false
      }
    ],
    "postbackUrl": "https://seupostbackurl.com.br/webhook/transacao",
    "metadata": {
      "source": "website",
      "campaign": "promocao-verao-2025"
    }
  }'

Resposta de Sucesso

message

string

Mensagem de sucesso

sale

object

Dados da venda criada

Show Propriedades da venda

sale.id

integer

ID da venda

sale.status

string

Status da venda. Valores possíveis: PENDENTE, EM_PROCESSAMENTO, PAGO, CANCELADO, RECUSADO, ESTORNADO, FALHA, CHARGEBACK, MED

sale.amount

integer

Valor em centavos

sale.pixKey

string

Chave PIX gerada (apenas para PIX)

sale.qrCode

string

QR Code para pagamento em base64 (apenas para PIX/Boleto)

sale.payment

object

Informações do pagamento

Show Propriedades do pagamento

sale.payment.method

string

Método de pagamento utilizado

sale.payment.pix

object

Dados do PIX (apenas para pagamentos PIX)

Show Propriedades do PIX

sale.payment.pix.key

string

Chave PIX completa

sale.payment.pix.qrCodeBase64

string

QR Code em formato base64 para exibição

sale.payment.pix.expiresAt

string | null

Data de expiração do PIX (ISO 8601). null se não expira.

Exemplo de Resposta

{
  "message": "Venda criada com sucesso",
  "sale": {
    "id": 2486,
    "amount": "5000",
    "status": "PENDENTE",
    "paymentMethod": "PIX",
    "customer": {
      "name": "João Silva Santos",
      "email": "[email protected]",
      "document": "14793766633",
      "phone": "5511943034718"
    },
    "payment": {
      "method": "PIX",
      "installments": null,
      "pix": {
        "key": "00020101021226830014BR.GOV.BCB.PIX2561qrcodespix.sejaefi.com.br/v2/e3c7c60f73e44469a1c7a628970b1bd45204000053039865802BR5905EFISA6008SAOPAULO62070503***6304481B",
        "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOQAAADkCAYAAACIV4iNAAAAAklEQVR4AewaftIAAAxhSURBVO3BQW4sy7LgQDKh/W+ZfYY+CiBRJb24v93M/mGtdYWHtdY1HtZa13hYa13jYa11jYe11jUe1lrXeFhrXeNhrXWNh7XWNR7WWtd4WGtd42GtdY2HtdY1HtZa13hYa13jhw+p/KWKE5WpYlL5RMWkclIxqUwVJypTxaRyUvGGylTxhspU8ZtUpopJ5S9VfOJhrXWNh7XWNR7WWtf44csqvknlRGWqmFROKn6TyjepfJPKJ1Q+ofKXKr5J5Zse1lrXeFhrXeNhrXWNH36ZyhsVb1TcrOJEZao4qZhUTlTeqDhReUPlExWTyjepvFHxmx7WWtd4WGtd42GtdY0f/o9R+YTKScVUMalMKicVk8pU8UbFpPKGylRxUvGGylQxqbxR8X/Jw1rrGg9rrWs8rLWu8cN/nMpvqphU/pLKGypvVEwqk8pU8YbKGxUnFf+XPay1rvGw1rrGw1rrGj/8sorfVPGGyqQyVZxUTCqfUHmj4g2VNyomlUnlpGKqmFTeUJkqvqniJg9rrWs8rLWu8bDWusYPX6byl1SmikllqphUTlSmipOKSWWqmFSmiknlRGWqOKmYVKaKk4pJ5URlqphUpoo3VKaKE5WbPay1rvGw1rrGw1rrGvYP/4eoTBWfUJkqvknljYo3VKaKE5WTihOVqeJE5aTi/ycPa61rPKy1rvGw1rrGDx9SmSomlaliUpkqJpWp4hMqn1D5RMVUMamcqHyTylQxqZyoTBVvVEwqk8pUMalMFW+oTBUnKlPFNz2sta7xsNa6xsNa6xr2Dx9QOak4UZkq3lD5popJZaqYVKaKSeW/rOJE5Y2KSeWkYlJ5o2JS+UTFpDJVfOJhrXWNh7XWNR7WWtf44UMVv0nljYo3VCaVNyomlaliUjmpOFGZKiaVqeINlTcqJpUTlW+qeKNiUpkq3qj4poe11jUe1lrXeFhrXeOHP6byRsWkMlVMKlPFScU3VUwqU8WJyknFGypTxaQyVUwqJxVTxaQyVUwq36QyVUwqn1CZKr7pYa11jYe11jUe1lrXsH/4gMpUMamcVJyoTBW/SWWqmFSmiknlExWTyknFN6m8UTGpnFScqEwVn1D5RMWJylTxiYe11jUe1lrXeFhrXcP+4QMqb1ScqEwVk8onKr5JZaqYVE4qJpWp4g2VqeI3qUwVn1D5RMWkclIxqbxR8U0Pa61rPKy1rvGw1rqG/cMHVP5SxRsqb1T8JpVPVEwqb1RMKlPFpPJGxaRyUnGiMlVMKlPFpPJGxaQyVUwqU8UnHtZa13hYa13jYa11jR8+VPEJlaniDZWp4ptUpooTlTcqJpWp4hMVJxWTylTxhspU8YbKVDGpTBWTylRxonJSMalMFd/0sNa6xsNa6xoPa61r2D98QGWqmFSmihOV31QxqZxUfEJlqphU3qh4Q2WqmFTeqJhU3qiYVKaKSeWkYlI5qZhUpopJZaqYVKaKTzysta7xsNa6xsNa6xo/fJnKVDGpnFScqLxR8UbFicpJxVQxqUwVb6hMFZPKVHFSMalMFScVk8pUcVIxqUwVk8pvUpkq/tLDWusaD2utazysta7xw5dVvFFxovJGxf+SylTxCZU3KiaVqWJSOVGZKiaVE5WpYlKZKiaVT1RMKjd7WGtd42GtdY2HtdY17B++SGWq+C9RmSp+k8obFZPKScWk8k0Vk8pU8YbKVPGGylTxhspUMamcVHziYa11jYe11jUe1lrX+OFDKlPFpPJGxaRyUjGpfKLiRGWqmFROKt6oOKmYVCaVNyreUPmmikllqphUpoo3VKaK/6WHtdY1HtZa13hYa13jhw9VvFExqUwqU8Wk8r9U8UbFpPKGylTxRsWkMlVMKlPFpHJSMamcVJxUTCpTxYnKVDFVTCpTxVQxqXzTw1rrGg9rrWs8rLWuYf/wh1R+U8WJyicqvkllqphUblIxqZxUnKjcpOINlaniEw9rrWs8rLWu8bDWuob9wy9SmSomlaniDZWpYlI5qThRmSomlU9UTConFW+oTBUnKlPFGyonFScqn6h4Q+WNit/0sNa6xsNa6xoPa61r/PAhld+kMlWcqJxUnKhMFZPKTVSmiv8SlTcqJpUTlanijYpJZar4poe11jUe1lrXeFhrXeOHy1V8omJSeUNlqnhD5UTlExVvqNykYlKZKiaVNyo+oTJVTCpTxSce1lrXeFhrXeNhrXUN+4c/pPKbKj6hclJxonKziknljYpJ5aTiDZWTiknlL1VMKlPFJx7WWtd4WGtd42GtdY0fPqQyVUwqU8WkclJxonKi8ptUvqliUnmj4psqTiomlUllqphU3lCZKiaVqeI3VXzTw1rrGg9rrWs8rLWu8cNlKiaVk4pJ5aRiUjmp+ETFicpJxaTyhspUcVIxqUwVk8obKlPFicpUMalMFZPKVPGGyhsVn3hYa13jYa11jYe11jV++FDFpDJVTCpTxaQyVZyoTBV/qWJSmVSmijdUTiomlTcqJpWpYlJ5o2JSmVROKt5QmSomlanipGJSmSq+6WGtdY2HtdY1HtZa17B/+IDKVDGpTBWTylQxqZxUTCpTxRsqU8WJyknFGypTxaRyUjGpTBUnKp+omFSmihOVT1RMKlPFicpJxaQyVXziYa11jYe11jUe1lrXsH/4gMpUMalMFb9JZaqYVL6pYlI5qZhUpopJ5aTiRGWq+ITKVHGTh7XWNR7WWtd4WGtd44fLqUwVJxWTylQxqZxUTCqTylRxonKiMlV8omJSeaNiUnmjYlJ5o+JE5Y2KSeWkYlI5qfjEw1rrGg9rrWs8rLWuYf/wh1TeqJhUpopJZaqYVE4qJpWp4g2Vk4o3VKaKSeUTFZPKGxWTyhsVk8pJxaQyVZyoTBVvqEwVn3hYa13jYa11jYe11jV++GUqU8UbKp9Q+UTFGyonFZ+omFSmiknlpOITFZ+o+KaKb1L5Sw9rrWs8rLWu8bDWuob9wx9SOak4UfmmikllqjhReaNiUpkq3lCZKt5QeaPif0llqjhR+UTFpHJS8YmHtdY1HtZa13hYa13jh1+mMlVMKpPKScWkMlVMKlPF/5LKVPGGyhsqU8VUMamcqLxRcaJyUnGi8k0Vk8pUMal808Na6xoPa61rPKy1rmH/8EUqJxWTylTxl1TeqJhUpooTlTcqJpWpYlKZKiaVNyreUHmj4hMqU8Wk8omKSWWq+KaHtdY1HtZa13hYa13jh19WcVIxqXyiYlKZKk4qJpVJ5URlqjipOFF5o2JSmSomlU+onFScqJxUnFScVJyovFExqUwVn3hYa13jYa11jYe11jXsH75I5Y2K/yWVk4pJ5b+k4kTljYpJ5aTiN6lMFZPKVHGiMlVMKlPFNz2sta7xsNa6xsNa6xr2Dx9QeaPiDZWTiknlpOINlaniEypTxYnKN1WcqEwVb6icVEwqJxUnKr+p4i89rLWu8bDWusbDWusaP3yo4jdVnKhMFZPKpDJVTConKicVn1A5qXhD5RMqU8Wk8ptU3qh4Q+VEZaqYVKaKTzysta7xsNa6xsNa6xo/fEjlL1VMFd9UMalMFZPKicpvUpkq/lLFpPJGxaQyVZyonKhMFScVk8pJxTc9rLWu8bDWusbDWusaP3xZxTepfFPFicpUMalMFW9UnFRMKicVn1CZKr6pYlKZKqaKE5U3Kt5QmSomlZOKTzysta7xsNa6xsNa6xo//DKVNyreUJkqpoq/pHKiclJxovJNFZPKScVJxUnFGypTxaQyqXyiYlKZKiaVb3pYa13jYa11jYe11jV++I+rmFTeqHijYlKZKiaVk4qTihOVqWJSmVSmiqniROWNiknljYqTik+onFRMKlPFNz2sta7xsNa6xsNa6xo//MepvFExqUwVb1RMKlPFpDKpvFExVZxUfELljYqTikllqphU3qiYVKaKE5WpYqqYVKaKTzysta7xsNa6xsNa6xo//LKK31RxonJScaLyRsUbFW+onFRMKlPFicpU8YbKVHFSMalMFZPKVPGGyjdVfNPDWusaD2utazysta7xw5ep/CWVqWKqmFSmik9UvFFxonJSMal8QuVEZaqYVE5UpopJ5URlqphUpoqTijdUpopJZar4xMNa6xoPa61rPKy1rmH/sNa6wsNa6xoPa61rPKy1rvGw1rrGw1rrGg9rrWs8rLWu8bDWusbDWusaD2utazysta7xsNa6xsNa6xoPa61rPKy1rvH/AEJo7NEFG8fzAAAAAElFTkSuQmCC",
        "expiresAt": null
      }
    },
    "shipping": null,
    "createdAt": "2025-12-20T05:55:39.372Z"
  }
}

Códigos de Erro

{
  "message": "Campos obrigatórios faltando",
  "error": "Dados inválidos",
  "details": {
    "missingFields": ["customer.email", "items"]
  }
}

{
  "message": "Combinação de chaves de API inválida",
  "details": "Verifique se ambas as chaves pertencem ao mesmo usuário e estão corretas"
}

{
  "message": "Erro ao criar venda",
  "error": "Falha ao processar pagamento no momento. Tente novamente mais tarde."
}

Status HTTP

Código	Descrição
`201`	Venda criada com sucesso
`400`	Dados inválidos ou campos obrigatórios faltando
`401`	Não autorizado - Chaves de API inválidas ou ausentes
`422`	Erro de validação (ex: valor mínimo não atingido)
`500`	Erro interno do servidor

Começando

Transações

Transferências

Saldo

Criar Transação

Criar Transação

Autenticação

Parâmetros do Body

Exemplos de Requisição

Resposta de Sucesso

Exemplo de Resposta

Códigos de Erro

Status HTTP

Começando

Transações

Transferências

Saldo

​Criar Transação

​Autenticação

​Parâmetros do Body

​Exemplos de Requisição

​Resposta de Sucesso

​Exemplo de Resposta

​Códigos de Erro

​Status HTTP

Criar Transação

Autenticação

Parâmetros do Body

Exemplos de Requisição

Resposta de Sucesso

Exemplo de Resposta

Códigos de Erro

Status HTTP