api

API de Transações

A API de Transações abrange todo o ciclo de vida do pagamento: criação de sessões de checkout, consulta do status da transação e verificação de confirmações na blockchain.

Atualizado: 09/03/2026

A API de Transações cobre o ciclo de vida completo do pagamento: criação de sessões de checkout, consulta do status da transação e verificação de confirmações na blockchain.

Visão Geral do Fluxo de Pagamento

┌─────────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────────┐
│ Your Server │───>│ Create       │───>│ Customer     │───>│ Blockchain    │
│             │    │ Checkout     │    │ Pays on      │    │ Confirms      │
│ POST api.php│    │ Session      │    │ Payment Page │    │ Transaction   │
└─────────────┘    └──────────────┘    └──────────────┘    └───────────────┘
                         │                                        │
                         │ payment_url                             │
                         ▼                                        ▼
                   ┌──────────────┐                         ┌───────────────┐
                   │ Redirect     │                         │ Webhook POST  │
                   │ Customer     │                         │ to Your Server│
                   │ to pay.php   │                         │               │
                   └──────────────┘                         └───────────────┘

Seu servidorchamacreate-checkout-sessioncom o valor e a moeda do pagamento.
Você recebe umapayment_urle redireciona o cliente para ela.
O cliente seleciona uma criptomoeda, escaneia o código QR e envia o pagamento.
A QuantaPay monitora a blockchain e aguarda as confirmações.
Uma vez confirmado, a QuantaPay envia umwebhookpara o seu servidor e/ou redireciona o cliente.

create-checkout-session

Cria uma nova sessão de pagamento. Retorna uma URL de pagamento para redirecionar seu cliente.

Requisição

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=create-checkout-session" \
  -d "api-key=YOUR_API_KEY" \
  -d "price=49.99" \
  -d "currency=USD"

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`price`	number	Sim	Valor do pagamento na moeda especificada.
`currency`	string	Sim	Código de moeda ISO 4217 (por exemplo,`USD`, `EUR`, `GBP`).
`order_id`	string	Não	Seu ID de pedido interno para referência.
`redirect`	string	Não	URL para redirecionar o cliente após o pagamento bem-sucedido.
`cancel_url`	string	Não	URL para redirecionar o cliente caso ele cancele.
`note`	string	Não	Nota interna anexada à transação.
`items`	String JSON	Não	Array de itens de linha (veja abaixo).
`customer`	String JSON	Não	Objeto de informações do cliente.
`signature`	string	Não	Assinatura HMAC-SHA256 para proteção contra adulteração.
`timestamp`	integer	Não	Timestamp Unix (obrigatório se a assinatura for fornecida).
`external_reference`	string	Não	Referência criptografada do plugin WordPress.
`plugin`	string	Não	Identificador do plugin de origem (por exemplo,`woo`, `edd`).

Formato dos Itens

[
  {
    "name": "Product Name",
    "qty": 2,
    "price": 24.99,
    "image": "https://example.com/product.jpg"
  }
]

Máximo de 50 itens por sessão.
name: Máximo de 200 caracteres.
image: Deve ser URL HTTP ou HTTPS, máximo de 500 caracteres.

Resposta

{
  "success": true,
  "response": {
    "session_id": "cs_a1b2c3d4e5f6a1b2c3d4",
    "payment_url": "https://cloud.quantapay.app/pay.php?session=cs_a1b2c3d4e5f6a1b2c3d4",
    "expires_at": "2026-03-08T11:00:00+00:00"
  }
}

session_id: Identificador de sessão exclusivo (formato:cs_+ 24 caracteres hexadecimais).
payment_url: URL para redirecionar o cliente para concluir o pagamento.
expires_at: Timestamp ISO 8601. As sessões expiram após60 minutos.

Respostas de Erro

Message	Cause
`Campos obrigatórios ausentes: price, currency`	`price`está 0/ausente ou`currency`está vazio.
`Assinatura inválida`	Falha na verificação da assinatura HMAC.
`Solicitação expirada`	O timestamp está com uma diferença de mais de 5 minutos em relação à hora do servidor.
`Falha ao criar a sessão de checkout`	Erro de banco de dados.

get-checkout-session

Consulta o status atual de uma sessão de checkout.

Requisição

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-checkout-session" \
  -d "api-key=YOUR_API_KEY" \
  -d "session_id=cs_a1b2c3d4e5f6a1b2c3d4"

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`session_id`	string	Sim	O ID da sessão de checkout (começa com`cs_`).

Resposta

{
  "success": true,
  "response": {
    "session_id": "cs_a1b2c3d4e5f6a1b2c3d4",
    "status": "paid",
    "price": 49.99,
    "currency": "usd",
    "order_id": "ORD-12345",
    "created_at": "2026-03-08T10:00:00+00:00",
    "expires_at": "2026-03-08T11:00:00+00:00",
    "paid_at": "2026-03-08T10:15:23+00:00"
  }
}

Status da Sessão

Status	Descrição
`active`	A sessão está aberta e aguardando pagamento.
`paid`	O pagamento foi recebido e confirmado na blockchain.
`expired`	A sessão expirou sem receber o pagamento (após 60 minutos).
`cancelled`	A sessão foi cancelada antes do recebimento do pagamento.

get-transactions

Consulta uma lista paginada de transações. Útil para conciliação e relatórios.

Requisição

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-transactions" \
  -d "api-key=YOUR_API_KEY" \
  -d "pagination=0"

Parâmetros

Todos os parâmetros são opcionais:

Parâmetro	Tipo	Descrição
`pagination`	integer	Número da página (indexado em 0). Cada página retorna até 100 transações.
`search`	string	Pesquisa por ID da transação, hash, valor ou descrição.
`status`	string	Filtrar por status:`C`(concluído),`P`(pendente),`X`(pago parcialmente),`E`(expirado).
`cryptocurrency`	string	Filtrar por código de criptomoeda (por exemplo,`btc`, `eth`).
`date_range`	array	Filtro de intervalo de datas como um array de dois elementos:`date_range[0]=2026-01-01&date_range[1]=2026-03-01`.
`checkout_id`	string	Filtrar por ID do botão de checkout/pagamento.

Resposta

Retorna um array de objetos de transação:

{
  "success": true,
  "response": [
    {
      "id": "123",
      "title": "Payment #ORD-12345",
      "description": "",
      "from": "0xCustomerAddress...",
      "to": "0xYourAddress...",
      "hash": "0xTransactionHash...",
      "amount": "0.025",
      "amount_fiat": "49.99",
      "cryptocurrency": "eth",
      "currency": "usd",
      "external_reference": "",
      "creation_time": "2026-03-08 10:00:00",
      "status": "C",
      "webhook": "1",
      "vat": ""
    }
  ]
}

Status da Transação

Código	Status	Descrição
`C`	Concluída	Pagamento confirmado na blockchain.
`P`	Pendente	Aguardando pagamento ou confirmação na blockchain.
`X`	Pago a menos	Pagamento recebido, mas o valor foi menor do que o necessário.
`E`	Expirado	Janela de pagamento expirou sem pagamento suficiente.
`R`	Reembolsado	O pagamento foi reembolsado.

get-transaction

Obter detalhes de uma única transação por ID.

Requisição

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-transaction" \
  -d "api-key=YOUR_API_KEY" \
  -d "transaction_id=123"

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`transaction_id`	integer	Sim	O ID da transação.

Resposta

Retorna um único objeto de transação (mesmo formato deget-transactions).

check-transaction

Acionar manualmente uma verificação de confirmação na blockchain para uma transação específica.

Requisição

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=check-transaction" \
  -d "api-key=YOUR_API_KEY" \
  -d "transaction=TRANSACTION_JSON"

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`transaction`	String JSON	Sim	O objeto de transação a ser verificado (conforme retornado por`get-transaction`).

Resposta

Retorna o objeto de transação atualizado com o status de confirmação atual. Se o número necessário de confirmações for alcançado, o status da transação mudará paraC(concluída).

Observação: Esta função normalmente não é necessária na operação normal. O QuantaPay verifica automaticamente as confirmações por meio de seu sistema cron. Use isso apenas se precisar forçar uma verificação imediata.