POST

Criar Transação

Cria uma transação de pagamento. Suporta PIX. Valores monetários são sempre em centavos (inteiros).

Endpoint

POST/api/v1/transactions/create

Cria uma nova transação PIX com QR Code dinâmico

Headers

Parametro	Tipo	Descricao
`Content-Type`obrigatorio	`string`	application/json
`Accept`obrigatorio	`string`	application/json
`X-Client-Id`obrigatorio	`string`	Client ID do seu aplicativo
`X-API-Key`obrigatorio	`string`	Chave secreta da sua empresa
`Idempotency-Key`	`string`	Chave única para evitar duplicidade (ex: tx_123456789). Recomendado

Idempotency-Key

O header Idempotency-Key é recomendado para evitar duplicidade de transações.

Request Body (PIX)

Importante

Todos os valores monetários (amount, unitPrice, fee) devem ser informados em centavos (inteiros).

request-body.json

json

{
  "amount": 500,
  "currency": "BRL",
  "paymentMethod": "PIX",
  "installments": 1,
  "customer": {
    "id": "CUST-1729131560000",
    "name": "João Teste",
    "email": "joao.teste@exemplo.com",
    "document": { "number": "24577481600", "type": "CPF" },
    "phone": "11987654321",
    "externalRef": "LEAD-1234"
  },
  "shipping": {
    "fee": 0,
    "address": {
      "street": "Rua dos Testes",
      "streetNumber": "123",
      "complement": "Sala 2",
      "zipCode": "01001000",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    }
  },
  "items": [
    {
      "title": "Produto X",
      "unitPrice": 500,
      "quantity": 1,
      "tangible": true,
      "externalRef": "SKU-001"
    }
  ],
  "pix": { "expiresInDays": 1 },
  "postbackUrl": "",
  "metadata": "{\"origem\":\"api\",\"ambiente\":\"producao\"}",
  "traceable": true,
  "ip": "177.123.45.67"
}

Campos do Body

Parametro	Tipo	Descricao
`amount`obrigatorio	`integer`	Valor em centavos (500 = R$ 5,00)
`currency`obrigatorio	`string`	Moeda (BRL)
`paymentMethod`obrigatorio	`string`	Método de pagamento (PIX)
`installments`obrigatorio	`integer`	Número de parcelas (1 para PIX)
`customer`obrigatorio	`object`	Dados do cliente
`customer.name`obrigatorio	`string`	Nome completo do cliente
`customer.email`obrigatorio	`string`	Email do cliente
`customer.document`obrigatorio	`object`	Documento (number + type: CPF/CNPJ)
`customer.phone`obrigatorio	`string`	Telefone do cliente
`items`obrigatorio	`array`	Lista de itens da transação
`pix.expiresInDays`	`integer`	Dias para expirar o QR Code (padrão: 1)
`postbackUrl`	`string`	URL de callback para webhooks
`metadata`	`string`	Metadados em JSON string
`traceable`	`boolean`	Habilitar rastreamento
`ip`	`string`	IP do cliente

Response 200 (PIX)

Exemplo Mínimo

response-minimo.json

json

{
  "data": {
    "id": "ebe485c6-cdf4-4736-aa3e-464044c4d4eb",
    "externalRef": "686725",
    "amount": 500,
    "refundedAmount": 0,
    "installments": 1,
    "paymentMethod": "PIX",
    "status": "WAITING_PAYMENT",
    "postbackUrl": "",
    "metadata": null,
    "traceable": true,
    "secureId": null,
    "secureUrl": null
  },
  "status": 200,
  "message": "Transação criada com sucesso."
}

Exemplo Completo

Quando o provedor retorna campos adicionais:

response-completo.json

json

{
  "data": {
    "id": "43836dbe-be02-47bc-965b-c51487b83b06",
    "externalRef": "686671",
    "amount": 500,
    "refundedAmount": 0,
    "installments": 1,
    "paymentMethod": "PIX",
    "status": "WAITING_PAYMENT",
    "postbackUrl": "",
    "metadata": null,
    "traceable": true,
    "createdAt": "2025-10-17T01:38:51.943Z",
    "updatedAt": "2025-10-17T01:38:51.943Z",
    "paidAt": null,
    "ip": "146.190.148.63",
    "endToEndId": null,
    "currency": "BRL",
    "pix": {
      "qrcode": "00020101021226820014br.gov.bcb.pix...",
      "url": null,
      "expirationDate": "2025-10-18T01:38:51.943Z"
    }
  },
  "status": 200,
  "message": "Transação criada com sucesso."
}

Observações Importantes

amount, unitPrice, fee estão em centavos
Em PIX, se pix.url vier null, use o qrcode como BR Code
Datas podem não vir em todos os cenários; quando presentes, são ISO-8601 UTC
Guarde o data.id para consultas posteriores e reconciliação

Erros

Todos os erros seguem o formato RFC 7807 Problem Details:

error.json

json

{
  "type": "https://httpstatuses.com/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Campo 'amount' é obrigatório",
  "errors": { "amount": ["O valor precisa ser inteiro em centavos."] },
  "traceId": "00-3a2b...-01"
}

Código	Nome	Descrição
`400`	Bad Request	Dados inválidos ou campos obrigatórios ausentes
`401`	Unauthorized	Credenciais inválidas ou ausentes
`403`	Forbidden	Acesso negado ao recurso
`409`	Conflict	Conflito de estado (ex: transação duplicada)
`422`	Unprocessable Entity	Validação de negócio falhou
`500`	Internal Server Error	Erro interno do servidor

Exemplo cURL

cURL

bash

curl -X POST https://rayopay.com.br/api/v1/transactions/create \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -H "Idempotency-Key: tx_$(date +%s)_$RANDOM" \
  -d '{
    "amount": 500,
    "currency": "BRL",
    "paymentMethod": "PIX",
    "installments": 1,
    "customer": {
      "id": "CUST-123",
      "name": "João",
      "email": "joao@ex.com",
      "document": {"number": "24577481600", "type": "CPF"},
      "phone": "11987654321"
    },
    "items": [{
      "title": "Produto X",
      "unitPrice": 500,
      "quantity": 1,
      "tangible": true
    }],
    "pix": { "expiresInDays": 1 },
    "postbackUrl": "",
    "traceable": true,
    "ip": "177.123.45.67"
  }'

Exemplo JavaScript (fetch)

JavaScript (fetch)

javascript

const response = await fetch("https://rayopay.com.br/api/v1/transactions/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Client-Id": "<CLIENT_ID>",
    "X-API-Key": "<API_KEY>",
    "Idempotency-Key": `tx_${Date.now()}_${Math.floor(Math.random()*1e6)}`
  },
  body: JSON.stringify({
    amount: 500,
    currency: "BRL",
    paymentMethod: "PIX",
    installments: 1,
    customer: {
      id: "CUST-123",
      name: "João",
      email: "joao@ex.com",
      document: { number: "24577481600", type: "CPF" },
      phone: "11987654321"
    },
    items: [{
      title: "Produto X",
      unitPrice: 500,
      quantity: 1,
      tangible: true
    }],
    pix: { expiresInDays: 1 },
    postbackUrl: "",
    traceable: true,
    ip: "177.123.45.67"
  })
});
 
const data = await response.json();
console.log(data);

Notas Finais

Salve o ID

Salve o id retornado para consultas posteriores e reconciliação.

Webhooks

Atualizações de status também chegam via webhook configurado no postbackUrl.