Criar transação

Cria uma transação de recebimento e retorna o ID e a URL de pagamento para o cliente concluir.

Overview

Fluxo de cash-in: crie a transação, obtenha paymentUrl e redirecione o cliente. Consulte por ID ou status, ou receba webhooks.

Endpoint

POSTPOST /transactions

Base URL:https://api.onnixpay.com/api/v1/sdk

Headers

Header	Obrigatório	Descrição
X-API-Key	Sim	Sua API Key.
Content-Type	Sim	Obrigatório para POST.

Body Parameters

Todas as propriedades do corpo da requisição, com tipo, obrigatoriedade, restrições e exemplo.

Campo	Tipo	Obrigatório	Descrição	Enum	Exemplo
amount	number	Sim	Valor em centavos. Ex.: 1000 = R$ 10,00.Inteiro > 0.	—	1000
description	string	Não	Descrição da transação.	—	Pedido #1234
externalId	string	Não	ID no seu sistema para conciliação.	—	pedido-1234
customerEmail	string	Não	E-mail do cliente.Formato e-mail válido.	—	cliente@email.com
customerName	string	Não	Nome do cliente.	—	—
customerDocument	string	Não	CPF ou CNPJ (apenas números).11 ou 14 dígitos.	—	—
callbackUrl	string	Não	URL para notificação de mudança de status.	—	https://seu-site.com/callback
metadata	object	Não	Metadados chave/valor para uso interno.	—	{}

Exemplo cURL

cURL

curl -X POST "https://api.onnixpay.com/api/v1/sdk/transactions" \
  -H "X-API-Key: ox_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 1000,
  "description": "Pedido #1234",
  "externalId": "pedido-1234",
  "customerEmail": "cliente@email.com"
}'

Response — Sucesso (201)

JSON

{
  "id": "txn_abc123",
  "status": "pending",
  "amount": 1000,
  "description": "Pedido #1234",
  "externalId": "pedido-1234",
  "createdAt": "2025-02-09T12:00:00.000Z",
  "paymentUrl": "https://pay.onnixpay.com/..."
}

Campos da resposta

Campo	Tipo	Descrição
id	string	ID da transação. Use em GET /transactions/{id} e /transactions/{id}/status.
status	string	Status inicial: pending.
amount	number	Valor em centavos.
description	string	Descrição informada.
externalId	string	ID externo informado.
createdAt	string	Data/hora de criação (ISO 8601).
paymentUrl	string	URL para o cliente concluir o pagamento.

Status codes e erros comuns

Status	Código	Mensagem
400	INVALID_REQUEST	Payload inválido ou campos obrigatórios faltando.
401	INVALID_API_KEY	Chave de API inválida ou ausente.
429	RATE_LIMIT_EXCEEDED	Limite de criações por minuto excedido.

Exemplo de resposta de erro

JSON

{
  "code": "INVALID_REQUEST",
  "message": "Os dados enviados são inválidos.",
  "details": { "field": "amount", "reason": "Deve ser um número positivo." }
}

Headers

X-API-Key: ox_sua_chave_aqui
Content-Type: application/json

Request body (JSON)

{
  "amount": 1000,
  "description": "Pedido #1234",
  "externalId": "pedido-1234",
  "customerEmail": "cliente@email.com"
}

cURL

curl -X POST "https://api.onnixpay.com/api/v1/sdk/transactions" \
  -H "X-API-Key: ox_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 1000,
  "description": "Pedido #1234",
  "externalId": "pedido-1234",
  "customerEmail": "cliente@email.com"
}'

Response (201)

{
  "id": "txn_abc123",
  "status": "pending",
  "amount": 1000,
  "description": "Pedido #1234",
  "externalId": "pedido-1234",
  "createdAt": "2025-02-09T12:00:00.000Z",
  "paymentUrl": "https://pay.onnixpay.com/..."
}