Listar cobranças - Vext

Listar cobranças

curl --request GET \
  --url https://api.usevext.com/v1/charges \
  --header 'Authorization: Bearer <token>'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usevext.com/v1/charges",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.usevext.com/v1/charges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "object": "list",
  "data": [
    {
      "object": "charge",
      "id": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2",
      "status": "paid",
      "payment_method": "pix",
      "amount": 10000,
      "currency": "BRL",
      "platform_fee": 798,
      "net_amount": 9202,
      "refunded_amount": 0,
      "description": "Curso de Vue 3",
      "reference": "pedido-1042",
      "customer": {
        "name": "João Comprador",
        "email": "joao@exemplo.com.br",
        "document": "111.***.***-35"
      },
      "pix": {
        "qr_code": "00020101021226840014br.gov.bcb.pix2562qrcodepix.example.com/v2/abcd1234",
        "expires_at": "2026-08-04T15:00:00+00:00",
        "end_2_end_id": "E12345678202608041200"
      },
      "created_at": "2026-08-04T14:00:00+00:00",
      "paid_at": "2026-08-04T14:03:11+00:00",
      "expired_at": null,
      "refunded_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

GET

/

v1

/

charges

Listar cobranças

curl --request GET \
  --url https://api.usevext.com/v1/charges \
  --header 'Authorization: Bearer <token>'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usevext.com/v1/charges",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.usevext.com/v1/charges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "object": "list",
  "data": [
    {
      "object": "charge",
      "id": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2",
      "status": "paid",
      "payment_method": "pix",
      "amount": 10000,
      "currency": "BRL",
      "platform_fee": 798,
      "net_amount": 9202,
      "refunded_amount": 0,
      "description": "Curso de Vue 3",
      "reference": "pedido-1042",
      "customer": {
        "name": "João Comprador",
        "email": "joao@exemplo.com.br",
        "document": "111.***.***-35"
      },
      "pix": {
        "qr_code": "00020101021226840014br.gov.bcb.pix2562qrcodepix.example.com/v2/abcd1234",
        "expires_at": "2026-08-04T15:00:00+00:00",
        "end_2_end_id": "E12345678202608041200"
      },
      "created_at": "2026-08-04T14:00:00+00:00",
      "paid_at": "2026-08-04T14:03:11+00:00",
      "expired_at": null,
      "refunded_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

Filtrar por reference é o caminho para reencontrar uma cobrança sem guardar o id que devolvemos. O laço de paginação completo está em Conciliar cobranças com os seus pedidos.

Authorizations

Authorization

string

header

required

Chave secreta do vendedor, criada no painel em Desenvolvedores.

O valor em claro existe uma única vez, na criação. Guardamos só o hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto: um dump do nosso banco não permite cobrar em nome de ninguém.

A chave vai no servidor. Colocá-la no navegador do comprador a entrega a qualquer pessoa que abra a página.

Query Parameters

status

enum<string>

Filtra por situação. Situação da cobrança. Todos os estados exceto pending são terminais - exceto os que ainda admitem estorno.

partially_refunded é estado próprio, e não um refunded com asterisco: tratar uma venda devolvida pela metade como estornada faria seu relatório descontar o valor inteiro.

Available options:

pending,

paid,

expired,

canceled,

partially_refunded,

refunded,

failed

reference

string

Sua referência, exatamente como enviada em reference na criação. É o caminho para reencontrar uma cobrança sem guardar o id que devolvemos.

Maximum string length: 120

created_from

string<date-time>

Criadas a partir desta data e hora (ISO 8601).

created_to

string<date-time>

Criadas até esta data e hora (ISO 8601).

per_page

integer

default:25

Itens por página. O teto de 100 existe porque uma página gigante de um vendedor com histórico degrada a consulta para todos os outros.

Required range: 1 <= x <= 100

page

integer

default:1

Required range: x >= 1

Response

Página de cobranças.

object

string

required

Allowed value: "list"

data

object[]

required

Show child attributes

pagination

object

required

Show child attributes

⌘I