Documentação da API monetipag

Gateway de pagamento completo com suporte a PIX e Cartão de Crédito.

URL Base

https://api.monetipag.com

Autenticação

Todas as requisições à API devem incluir o header de autenticação:

HTTP Header

Authorization: Bearer <token>

Importante: O token de autenticação deve ser obtido através do painel administrativo ou via endpoint de autenticação.

SDK JavaScript (Frontend)

O SDK JavaScript permite a tokenização segura de cartões de crédito diretamente no navegador, garantindo conformidade com PCI DSS.

Instalação

HTML

<script type="module">
  import { createCh } from "https://scalefy.sfo3.cdn.digitaloceanspaces.com/sdk/v1/script.min.js";
</script>

Tokenização de Cartão

Use o método encrypt() para tokenizar os dados do cartão antes de enviar para a API.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número do cartão (sem espaços)
`holder_name`	string	Sim	Nome impresso no cartão
`exp_month`	string	Sim	Mês de expiração (MM)
`exp_year`	string	Sim	Ano de expiração (YYYY)
`cvv`	string	Sim	Código de segurança (3-4 dígitos)

Exemplo de Uso

JavaScript

import { createCh } from "https://scalefy.sfo3.cdn.digitaloceanspaces.com/sdk/v1/script.min.js";

const cardData = {
  number: "4111111111111111",
  holder_name: "João Silva",
  exp_month: "12",
  exp_year: "2025",
  cvv: "123"
};

const token = await createCh.encrypt(cardData);
console.log(token); // Use este token na criação da fatura

Resposta

JSON

{
  "token": "tok_abc123xyz456..."
}

Criar Fatura

POST /api/v2/invoices

Cria uma nova fatura para pagamento via PIX ou Cartão de Crédito.

Parâmetros do Body

Nível Raiz

Campo	Tipo	Obrigatório	Descrição
`method`	string	Sim	Método de pagamento: `pix` ou `credit_card`
`product_fisical`	string	Não	Indica se o produto é físico
`ip_payer`	string	Não	IP do pagador
`total_price_cents`	integer	Não	Valor total em centavos (se não informado, é calculado a partir dos itens)
`postback_url`	string	Não	URL para receber notificações de mudança de status
`payer`	object	Sim	Dados do pagador
`card`	object	Condicional	Obrigatório se `method = credit_card`
`items`	array	Sim	Lista de itens da fatura

Objeto `payer`

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo do pagador
`cpf_cnpj`	string	Sim	CPF ou CNPJ (apenas números)
`email`	string	Sim	E-mail do pagador
`phone`	string	Sim	Telefone com DDD
`address_zip`	string	Sim	CEP (apenas números)
`address_line`	string	Sim	Logradouro (rua, avenida, etc.)
`address_number`	string	Sim	Número do endereço
`address_complement`	string	Não	Complemento do endereço
`address_city`	string	Sim	Cidade
`address_state`	string	Sim	Estado (sigla, ex: SP)

Objeto `card`

Campo	Tipo	Obrigatório	Descrição
`token`	string	Condicional	Token gerado pelo SDK (use no lugar dos dados brutos do cartão)
`installment`	integer	Não	Número de parcelas
`number`	string	Condicional	Número do cartão (use somente se não utilizar token)
`first_name`	string	Condicional	Primeiro nome impresso no cartão
`last_name`	string	Condicional	Sobrenome impresso no cartão
`month`	string	Condicional	Mês de expiração (MM)
`year`	string	Condicional	Ano de expiração (YYYY)
`security_code`	string	Condicional	Código de segurança (CVV)
`cavv`	string	Não	Valor de autenticação para 3D Secure
`xid`	string	Não	ID de transação para 3D Secure
`eci`	string	Não	Electronic Commerce Indicator (3D Secure)
`version`	string	Não	Versão do protocolo 3D Secure
`referenceid`	string	Não	ID de referência da autenticação 3D Secure

Objeto `items`

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do item
`description`	string	Não	Descrição do item
`quantity`	integer	Sim	Quantidade
`unit_price`	integer	Sim	Preço unitário em centavos

Exemplo de Request (PIX)

JSON

{
  "method": "pix",
  "postback_url": "https://seusite.com/webhook",
  "payer": {
    "name": "João Silva",
    "cpf_cnpj": "12345678900",
    "email": "joao@example.com",
    "phone": "11999999999",
    "address_zip": "01234567",
    "address_line": "Rua Exemplo",
    "address_number": "123",
    "address_complement": "Apto 45",
    "address_city": "São Paulo",
    "address_state": "SP"
  },
  "items": [
    {
      "name": "Produto Exemplo",
      "description": "Descrição do produto",
      "quantity": 2,
      "unit_price": 5000
    }
  ]
}

Exemplo de Request (Cartão de Crédito)

JSON

{
  "method": "credit_card",
  "postback_url": "https://seusite.com/webhook",
  "ip_payer": "177.0.0.1",
  "payer": {
    "name": "João Silva",
    "cpf_cnpj": "12345678900",
    "email": "joao@example.com",
    "phone": "11999999999",
    "address_zip": "01234567",
    "address_line": "Rua Exemplo",
    "address_number": "123",
    "address_complement": "Apto 45",
    "address_city": "São Paulo",
    "address_state": "SP"
  },
  "card": {
    "token": "tok_abc123xyz456...",
    "installment": 1
  },
  "items": [
    {
      "name": "Produto Exemplo",
      "description": "Descrição do produto",
      "quantity": 1,
      "unit_price": 10000
    }
  ]
}

Exemplo de Response

JSON

{
  "invoice_id": "inv_123456789",
  "status": "pending",
  "method": "pix",
  "amount": 10000,
  "currency": "BRL",
  "qr_code_pix": "00020126580014br.gov.bcb.pix...",
  "qr_code_url": "https://api.monetipag.com/qr/inv_123456789.png",
  "created_at": "2026-02-11T14:15:00Z",
  "expires_at": "2026-02-11T14:30:00Z"
}

Consultar Fatura

GET /api/v2/invoices

Consulta o status e detalhes de uma fatura existente.

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID da fatura

Exemplo de Request

HTTP

GET https://api.monetipag.com/api/v2/invoices?id=inv_123456789
Authorization: Bearer <token>

Exemplo de Response

JSON

{
  "invoice_id": "inv_123456789",
  "status": "paid",
  "method": "credit_card",
  "amount": 10000,
  "currency": "BRL",
  "paid_at": "2026-02-11T14:20:00Z",
  "payer": {
    "name": "João Silva",
    "email": "joao@example.com"
  },
  "items": [
    {
      "name": "Produto Exemplo",
      "quantity": 1,
      "unit_price": 10000
    }
  ]
}

3D Secure: Para pagamentos com autenticação 3DS, a resposta incluirá o campo url_3ds com a URL de redirecionamento para autenticação.

Trocar Token

POST /api/v2/tokens/exchange

Troca um token temporário do SDK por um token persistente para transações recorrentes.

Request Body

Campo	Tipo	Obrigatório	Descrição
`temporary_token`	string	Sim	Token temporário gerado pelo SDK

Exemplo de Request

JSON

{
  "temporary_token": "tok_temp_abc123..."
}

Exemplo de Response

JSON

{
  "persistent_token": "tok_persist_xyz789...",
  "card_brand": "visa",
  "last_digits": "1111",
  "expires_at": "2025-12-31"
}

Status das Faturas

Possíveis status de uma fatura:

Status	Descrição
pending	Aguardando pagamento
paid	Pagamento confirmado
canceled	Fatura cancelada
expired	Prazo de pagamento expirado
failed	Falha no processamento do pagamento

Códigos de Erro

Códigos HTTP retornados pela API:

Código	Descrição
`200`	Requisição bem-sucedida
`400`	Requisição inválida (bad request)
`401`	Não autorizado (token inválido ou ausente)
`404`	Recurso não encontrado
`422`	Erro de validação nos campos enviados
`500`	Erro interno no servidor

Postback (Webhook)

Quando o campo postback_url é configurado na criação da fatura, a API enviará uma requisição POST para essa URL sempre que o status da fatura mudar.

Payload do Webhook

JSON

{
  "invoice_id": "inv_123456789",
  "status": "paid",
  "payment_method": "pix",
  "amount": 10000,
  "currency": "BRL",
  "paid_at": "2026-02-11T14:20:00Z"
}

Dica: Seu endpoint deve responder com status HTTP 200 para confirmar o recebimento. A API tentará reenviar o webhook em caso de falha.

Documentação da API monetipag

URL Base

Autenticação

SDK JavaScript (Frontend)

Instalação

Tokenização de Cartão

Parâmetros

Exemplo de Uso

Resposta

Criar Fatura

Parâmetros do Body

Nível Raiz

Objeto payer

Objeto card

Objeto items

Exemplo de Request (PIX)

Exemplo de Request (Cartão de Crédito)

Exemplo de Response

Consultar Fatura

Query Parameters

Exemplo de Request

Exemplo de Response

Trocar Token

Request Body

Exemplo de Request

Exemplo de Response

Status das Faturas

Códigos de Erro

Postback (Webhook)

Payload do Webhook

Objeto `payer`

Objeto `card`

Objeto `items`