API REST · v1

Integre PIX em minutos

Crie cobranças, receba confirmações instantâneas e configure webhooks com poucas linhas de código.

Base URLhttps://api.moovepay.uk

Formatoapplication/json

AuthHTTP Basic

Autenticação

Todas as requisições usam HTTP Basic Auth. Gere suas credenciais em Painel → Configurações → Credenciais.

Campo	Tipo	Req.	Descrição
`client_id`	`string`	✓	Identificador público — ex: wp_prod_a1b2c3
`client_secret`	`string`	✓	Chave secreta — exibida só na criação, não recuperável

O client_secret é exibido apenas uma vez. Se perder, gere um novo (o antigo é invalidado imediatamente).

const CLIENT_ID = process.env.MOOVEPAY_CLIENT_ID
const CLIENT_SECRET = process.env.MOOVEPAY_CLIENT_SECRET
const BASE = "https://api.moovepay.uk"

// Basic Auth: base64(client_id:client_secret)
const auth = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")

const res = await fetch(`${BASE}/v1/charges`, {
  headers: { Authorization: `Basic ${auth}` },
})

Idempotência

Toda criação de cobrança precisa do header Idempotency-Key com um UUID único por pedido. Reenvios com o mesmo key retornam a cobrança original — sem criar duplicata.

Gere o UUID antes de chamar a API e salve-o no seu banco de dados. Em caso de timeout, reenvie com o mesmo key com segurança.

Header obrigatório

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

// ✓  Mesmo key → retorna cobrança existente
// ✗  Key diferente → cria nova cobrança

Erros

Todas as respostas de erro retornam JSON com uma mensagem descritiva.

400Dados inválidos na requisição

401Credenciais ausentes ou inválidas

404Recurso não encontrado

422Regra de negócio violada

429Rate limit — aguarde antes de retentar

502Erro no banco parceiro — retentar

Formato de erro

// Toda resposta de erro segue esse formato
{
  "message": "amount must be greater than zero"
}

// 422 — regra de negócio
{
  "message": "withdrawal amount (100) must be greater than fee (350)"
}