API Documentation

Integração rápida e segura com nossa API RESTful. Autenticação via Bearer Token, respostas em JSON padronizado.

Base URL https://api.moneria.com.br/

Introdução

Bem-vindo à documentação oficial da API. Este guia contém todas as informações necessárias para uma integração rápida e segura.

A API utiliza HTTPS obrigatório e retorna respostas em JSON padronizado com os campos status, message e data.

Características

  • HTTPS obrigatório para todas as requisições
  • Métodos GET e POST conforme endpoint
  • Respostas padronizadas em JSON
  • Autenticação via Bearer Token

Autenticação

Todas as requisições devem incluir um Bearer Token no header de autorização.

Gerando seu Token

https://web.moneria.com.br/gateway/

Exemplo de Header

HTTP Header 
{
  "Authorization": "Bearer SUA_CHAVE_API"
}
Importante: Nunca compartilhe ou exponha sua chave API em código público.

Consulta de Saldo

Recupera o saldo disponível da conta em tempo real.

GET https://api.moneria.com.br/v1/accounts/balance/

Resposta de Sucesso

JSON 
{
  "success": true,
  "message": "Saldo da carteira recuperado com sucesso.",
  "data": {
    "total_balance": 0.01,
    "available_balance": 0.01,
    "blocked_balance": 0,
    "reserved_balance": 0
  }
}

Consulta de Comprovante

Recupera o comprovante de uma transação de retirada (cash-out).

GET https://api.moneria.com.br/v1/accounts/comprovante/?idtransaction=ID

Parâmetros

idtransaction string Obrigatório

ID único da transação de cash-out

Resposta de Sucesso

JSON 
{
    "success": true,
    "message": "Transação localizada com sucesso",
    "data": {
        "idtransaction": "abc123xyz",
        "amount": 100.50,
        "status": "COMPLETED",
        "date": "2025-08-04 14:30:00",
        "beneficiary": "João da Silva",
        "document": "123.456.789-00",
        "pixkey": "joao@email.com",
        "type_keypix": "EMAIL",
        "comprovante_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAB4AAAA..."
    }
}

Criar Cliente (Customer)

Cria um novo cliente que pode ser usado ao criar transações.

POST https://api.moneria.com.br/v2/customers/create

Parâmetros do Body

name string Obrigatório

Nome completo do cliente

email string Obrigatório

E-mail válido

document string Obrigatório

CPF ou CNPJ

phone string Opcional

Telefone com DDD

externalRef string Opcional

Referencia externa da sua api

cURL Request 
curl -X POST https://api.moneria.com.br/v2/customers/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678900",
    "phone": "11999999999",
    "externalRef": "abc-123",
    "address": {
        "street": "Rua A",
        "number": "123",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "postalCode": "01000-000",
        "country": "BR"
    }
  }'
200 Success
JSON Response 200 
{
  "status": "success",
  "customer_id": "7994cc4f-69ea-4b5a-8398-d39618usw2b"
}

Buscar Clientes

Liste todos os clientes criados

GET https://api.moneria.com.br/v2/customers/find

Parâmetros

customer_id uuid Opcional

Busca um unico cliente pelo customer_id

external_ref string Opcional

Busca um unico cliente pelo external_ref

cURL Request 
curl -X GET https://api.moneria.com.br/v2/customers/find \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
200 Success
JSON Response 200 
[
  {
    "customer_id": "8ea41cbb-5835-4576-ac85-466d10b3a4b5",
    "user_id": "fab.aquiles1235664",
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678900",
    "phone": "11999999999",
    "external_ref": "abc-123",
    "address_street": "Rua A",
    "address_number": "123",
    "address_complement": null,
    "address_postal_code": "01000-000",
    "address_neighborhood": null,
    "address_city": "São Paulo",
    "address_state": "SP",
    "address_country": "BR",
    "created_at": "2026-01-05 20:37:03",
    "updated_at": "2026-01-05 20:37:03"
  }
]
cURL Request 
curl -X GET https://api.moneria.com.br/v2/customers/find?customer_id=8ea41cbb-5835-4576-ac85-466d10b3a4b5 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
200 Success
JSON Response 200 
{
    "customer_id": "8ea41cbb-5835-4576-ac85-466d10b3a4b5",
    "user_id": "fab.aquiles1235664",
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678900",
    "phone": "11999999999",
    "external_ref": "abc-123",
    "address_street": "Rua A",
    "address_number": "123",
    "address_complement": null,
    "address_postal_code": "01000-000",
    "address_neighborhood": null,
    "address_city": "São Paulo",
    "address_state": "SP",
    "address_country": "BR",
    "created_at": "2026-01-05 20:37:03",
    "updated_at": "2026-01-05 20:37:03"
  }

Validar Chave PIX

Valide uma chave PIX e obtenha os dados bancários associados

POST https://api.moneria.com.br/v2/pix-key/validate

Parâmetros

pix_key string Obrigatório

A chave PIX a ser validada (CPF, CNPJ, e-mail, telefone ou chave aleatória)

pix_key_type string Obrigatório

Tipo da chave PIX. Valores aceitos: CPF, CNPJ, EMAIL, TELEFONE, CHAVE_ALEATORIA

cpf_cnpj string Opcional

CPF ou CNPJ do titular da chave PIX para validação de titularidade

Resposta

name string

Nome do titular da conta

agency string

Número da agência bancária

account string

Número da conta bancária

account_digit string

Dígito verificador da conta

account_type string

Tipo da conta. Ex: CONTA_CORRENTE, CONTA_POUPANCA

bank_code string

Código do banco (ex: 077 para Inter)

bank_ispb string

Código ISPB do banco

valid boolean

Indica se a validação foi bem-sucedida

errors array

Lista de erros encontrados durante a validação (vazio se válido)

Rate Limit: Esta API possui limite de 1 requisição por segundo por chave de API.
cURL Request 
curl -X POST https://api.moneria.com.br/v2/pix-key/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "pix_key": "12345678901",
    "pix_key_type": "CPF",
    "cpf_cnpj": "12345678901"
  }'
200 Success
400 Bad Request
401 Unauthorized
429 Rate Limit
JSON Response 200 
{
    "name": "JOAO DA SILVA",
    "agency": "1234",
    "account": "98765432",
    "pix_key": "12345678901",
    "cpf_cnpj": "12345678901",
    "account_type": "CONTA_CORRENTE",
    "agency_digit": null,
    "pix_key_type": "CPF",
    "account_digit": "5",
    "pix_key_validation": {
        "cpf_cnpj": "12345678901"
    },
    "bank_code": "001",
    "bank_ispb": "00000000",
    "valid": true,
    "errors": []
}
JSON Response 400 
{
    "success": false,
    "message": "The document informed for validation is invalid"
}
JSON Response 401 
{
    "success": false,
    "message": "Unauthorized. Invalid API key."
}
JSON Response 429 
{
    "success": false,
    "message": "Rate limit exceeded. Please wait 1 second."
}

Validar Conta Bancária

Valide uma conta bancária e verifique a titularidade através de micro depósito

POST https://api.moneria.com.br/v2/bank-account/validate

Parâmetros

bank_code string Obrigatório

Código do banco (COMPE). Ex: 001 (BB), 237 (Bradesco), 341 (Itaú)

agency string Obrigatório

Número da agência bancária (sem dígito verificador)

account_number string Obrigatório

Número da conta bancária incluindo o dígito verificador. Ex: 1234567 (onde 7 é o dígito)

account_type string Obrigatório

Tipo da conta bancária. Valores aceitos: CONTA_CORRENTE, CONTA_POUPANCA

cpf_cnpj string Obrigatório

CPF ou CNPJ do titular da conta para validação de titularidade

Resposta

agency string

Número da agência bancária

account string

Número da conta bancária (sem dígito)

account_digit string

Dígito verificador da conta

account_type string

Tipo da conta. Ex: CONTA_CORRENTE, CONTA_POUPANCA

cpf_cnpj string

CPF ou CNPJ do titular validado

bank_code string

Código do banco (COMPE)

bank_ispb string

Código ISPB do banco

valid boolean

Indica se a validação foi bem-sucedida

errors array

Lista de erros encontrados durante a validação (vazio se válido)

Rate Limit: Esta API possui limite de 1 requisição por segundo por chave de API.
Tempo de resposta: A validação utiliza micro depósito e pode levar alguns segundos para ser processada.
cURL Request 
curl -X POST https://api.moneria.com.br/v2/bank-account/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "bank_code": "341",
    "agency": "1234",
    "account_number": "567890",
    "account_type": "CONTA_CORRENTE",
    "cpf_cnpj": "12345678900"
  }'
200 Success
400 Bad Request
401 Unauthorized
429 Rate Limit
JSON Response 200 
{
    "agency": "1234",
    "account": "56789",
    "cpf_cnpj": "12345678900",
    "bank_code": "341",
    "account_type": "CONTA_CORRENTE",
    "account_digit": "0",
    "bank_ispb": "60701190",
    "valid": true,
    "errors": []
}
JSON Response 400 
{
    "success": false,
    "message": "Campos obrigatórios: bank_code, agency, account_number, account_type, cpf_cnpj"
}
JSON Response 401 
{
    "success": false,
    "message": "Unauthorized. Invalid API key."
}
JSON Response 429 
{
    "success": false,
    "message": "Rate limit exceeded. Please wait 1 second."
}

Autorizar endereço de IP

Autorize endereços de ip para realizar transferencias.

POST https://api.moneria.com.br/v2/account/authorize

Parâmetros

ip string Obrigatório

Endereço de IP do servidor que vai realizar a requisição.

Resposta

status string

Status da operação

message string

Mensagem de resposta da operação

Rate Limit: Esta API possui limite de 1 requisição por segundo por chave de API.
cURL Request 
curl -X POST https://api.moneria.com.br/v2/account/authorize \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "ip": "10.0.0.1"
  }'
200 Success
400 Bad Request
401 Unauthorized
429 Rate Limit
JSON Response 200 
{
    "status": "success",
    "message": "IP autorizado com sucesso.",
}
JSON Response 400 
{
    "success": "error",
    "message": "Esse endereco de ip ja esta cadastrado."
}
JSON Response 401 
{
    "success": "unauthorized",
    "message": "Token invalido."
}
JSON Response 429 
{
    "success": false,
    "message": "Rate limit exceeded. Please wait 1 second."
}

Listar IP's autorizados.

Liste todos os endereços de ips autorizados.

GET https://api.moneria.com.br/v2/account/authorize

Resposta

JSON 
[
    {
    "id": 1202,
    "ip": "10.0.0.1",
    "created_at": "2025-01-12 19:00:41"
    }
]

Criar Transação (Cash-In)

Cria uma nova transação usando PIX, Boleto ou Cartão de Crédito.

POST https://api.moneria.com.br/v2/transactions/

Parâmetros do Body

amount decimal Obrigatório

Valor da transação (ex: 10.0)

provider string Obrigatório

Sempre utilize "v2"

method string Obrigatório

"pix", "boleto" ou "credit_card"

installments integer Obrigatório

Número de parcelas

productName string Opcional

Nome do produto ou serviço

customerId uuid Opcional

Id do cliente criado na plataforma

postBackUrl string Opcional

URL para receber webhooks

cURL Request 
curl -X POST https://api.moneria.com.br/v2/transactions/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "amount": 10,
    "provider": "v2",
    "method": "pix",
    "pix": {
      "expiration": "3600",
    },
    "customer": {
      "name": "Maria Silva",
      "document": "12345678912",
      "phone": "99987654321",
      "email": "maria@email.com"
      "address": {
        "street": "Test Street",
        "number": "999",
        "neighborhood": "Test Neighborhood",
        "city": "Test City",
        "state": "TS",
        "postalCode": "00000111",
        "country": "BR",
        "complement": "Near Test Point"
      },
    },
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "promocao_novembro",
      "term": "comprar+produto",
      "content": "banner_lateral"
    },
    "split": {
      "userId": "user_model233",
      "percentage": "10"
    },
    "productName": "Produto Padrão",
    "customerId": "80461338-addf-41f7-bc39-ed9d91e61e57",
    "postBackUrl": "https://seusite.com/webhook"
  }'
200 Success
400 Bad Request
401 Unauthorized
503 No Acquirer Available
JSON Response 200 
{
  "status": "success",
  "message": "ok",
  "paymentCode": "00020126580014br.gov.bcb.pix...",
  "idTransaction": "7994cc4f-69ea-4b5a-8398-d39618usw2b"
}
JSON Response 400 
{
  "status": "error",
  "message": "Campo obrigatório: 'campo'."
}
JSON Response 401 
{
  "status": "unauthorized",
  "message": "Chave de API inválida"
}
JSON Response 503 
{
  "status": "error",
  "message": "Nenhuma adquirente disponível no momento"
}
cURL Request 
curl -X POST https://api.moneria.com.br/v2/transactions/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "amount": 10,
    "provider": "v2",
    "method": "credit_card",
    "installments": 1,
    "customer": {
      "name": "Maria Silva",
      "document": "12345678912",
      "phone": "99987654321",
      "email": "maria@email.com"
      "address": {
        "street": "Test Street",
        "number": "999",
        "neighborhood": "Test Neighborhood",
        "city": "Test City",
        "state": "TS",
        "postalCode": "00000111",
        "country": "BR",
        "complement": "Near Test Point"
      },
    },
    "card": {
      "number": "1111222233334444",
      "holderName": "MARIA SILVA",
      "expirationMonth": "12",
      "expirationYear": "25",
      "cvv": "123"
    },
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "promocao_novembro",
      "term": "comprar+produto",
      "content": "banner_lateral"
    },
    "split": {
      "userId": "user_model233",
      "percentage": "10"
    },
    "productName": "Produto Padrão",
    "customerId": "80461338-addf-41f7-bc39-ed9d91e61e57",
  }'
200 Success
400 Bad Request
401 Unauthorized
422 Card Declined
503 No Acquirer Available
JSON Response 200 
{
  "status": "success",
  "message": "ok",
  "idTransaction": "7994cc4f-69ea-4b5a-8398-d39618usw2b"
}
JSON Response 400 
{
  "status": "error",
  "message": "Campo obrigatório: 'campo'."
}
JSON Response 401 
{
  "status": "unauthorized",
  "message": "Chave de API inválida"
}
JSON Response 422 
{
  "status": "refused",
  "message": "Transação recusada"
}
JSON Response 503 
{
  "status": "error",
  "message": "Nenhuma adquirente disponível no momento"
}

Buscar Transações

Liste todas as transações da sua conta com paginação.

GET https://api.moneria.com.br/v2/transactions/me/?page={page}&limit={limit}

Parâmetros

page number Opcional

Número da página

limit number Opcional

Número de transações por página

Resposta

JSON 
[
    {
    "id": 1202,
    "customer": {
        "name": "Maria Souza",
        "document": "98765432100",
        "email": "maria@email.com",
        "phone": "11988888888"
    },
    "amount": 80.00,
    "netAmount": 78.90,
    "status": "WAITING_FOR_APPROVAL",
    "type": "pix",
    "installments": 1,
    "createdAt": "2025-01-12 19:00:41",
    "paymentDate": null,
    "transactionId": "8350e5a3e24c153df2275c9f80692773"
    }
]

Consultar Transação

Consulta os detalhes de uma transação específica pelo ID.

GET https://api.moneria.com.br/v2/transactions/me/?transactionId={id}

Parâmetros

transactionId string Obrigatório

ID único da transação

Resposta

JSON 
{
  "id": 1202,
  "customer": {
    "name": "Maria Souza",
    "document": "98765432100",
    "email": "maria@email.com",
    "phone": "11988888888"
  },
  "amount": 80.00,
  "netAmount": 78.90,
  "status": "WAITING_FOR_APPROVAL",
  "type": "pix",
  "installments": 1,
  "createdAt": "2025-01-12 19:00:41",
  "paymentDate": null,
  "transactionId": "8350e5a3e24c153df2275c9f80692773"
}

Criar Transferência (Cash-Out)

Cria uma nova transferência usando PIX ou Transferência Bancária.

POST https://api.moneria.com.br/v2/transfers/

Parâmetros do Body

method string Obrigatório

"pix" ou "bank"

amount decimal Obrigatório

Valor da transferência (ex: 10.0)

postBackUrl string Opcional

URL para receber webhooks

cURL Request 
curl -X POST /v2/transfers/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "method": "pix",
    "amount": 100.00,
    "pix": {
      "type": "CPF",
      "key": "12345678900"
    },
    "beneficiary": {
      "name": "João Silva",
      "document": "12345678909"
    },
    "postBackUrl": "https://seusite.com/webhook"
  }'
200 Success
400 Bad Request
401 Unauthorized
422 Transfer Failed
JSON Response 200 
{
  "status": "success",
  "message": "Cashout em processamento",
  "idtransaction": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
}
JSON Response 400 
{
  "status": "error",
  "message": "Campo obrigatório: 'pix.key'"
}
JSON Response 401 
{
  "status": "unauthorized",
  "message": "Chave de API inválida"
}
JSON Response 422 
{
  "status": "failed",
  "message": "Transferência recusada - saldo insuficiente"
}
cURL Request 
curl -X POST /v2/transfers/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "method": "bank",
    "amount": 100.00,
    "bank": {
      "ispb": "12345678",
      "bankCode": "123",
      "agency": "1234",
      "account": "123456",
      "accountDigit": "7",
      "accountType": "CONTA_CORRENTE"
    },
    "beneficiary": {
      "name": "João Silva",
      "document": "12345678909"
    },
    "postBackUrl": "https://seusite.com/webhook"
  }'
200 Success
401 Unauthorized
422 Transfer Failed
JSON Response 200 
{
  "status": "success",
  "message": "Cashout em processamento",
  "idtransaction": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
}
JSON Response 400 
{
  "status": "error",
  "message": "Campo obrigatório: 'bank.account'"
}
JSON Response 401 
{
  "status": "unauthorized",
  "message": "Chave de API inválida"
}
JSON Response 422 
{
  "status": "failed",
  "message": "Dados bancários inválidos"
}

Webhooks

Receba notificações em tempo real.

Seu endpoint deve aceitar POST, responder 200 OK em até 5 segundos.

Webhook de Transação

JSON
{
  "type": "transaction",
  "transaction_id": "98765432",
  "store_name": "Loja Exemplo - Checkout API",
  "method": "pix",
  "total_price": "350.00",
  "status": "paid",
  "customer": {
    "name": "João da Silva",
    "document": "12345678901",
    "email": "joao@email.com",
    "phone": "11999998888"
  },
  "utms": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "black_friday",
    "utm_term": "checkout pix",
    "utm_content": "banner_topo"
  },
  "created_at": "2025-01-27 12:50:31",
  "updated_at": "2025-01-27 12:51:10",
  "refund_at": null,
  "pix_qrcode": "00020101021226880014br.gov.bcb.pix...",
  "pix_qrcode_image": null
}

Status Possíveis

waiting_paymentAguardando pagamento
paidPagamento confirmado
refundedEstornado
chargebackChargeback
refusedRecusado

Webhook de Cashout

JSON Payload
{
  "type": "cashout",
  "idtransaction": "5f5d22ab-34e2...",
  "external_reference": "de660b86-3475...",
  "status": "completed",
  "amount": "200.00",
  "net_amount": "195.00",
  "method": "PIX",
  "beneficiary": {
    "name": "John Doe",
    "document": "12345678901",
    "pix_key": "12345678901",
    "pix_key_type": "CPF",
    "bank_ispb": "43521234",
    "bank_account_number": "1234567",
    "bank_agency": "00001"
  },
  "description": "Solicitação de saque Baas",
  "created_at": "2025-01-27 12:50:31",
  "updated_at": "2025-01-27 19:23:45"
}

Status do Cashout

pendingProcessando
completedConcluído
cancelledCancelado