Criar cobrança

curl --request POST \
  --url https://api.upag.io/v1/charges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "amount": 123,
  "customer": {},
  "card": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({type: '<string>', amount: 123, customer: {}, card: '<string>'})
};

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

const url = 'https://api.upag.io/v1/charges';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({type: '<string>', amount: 123, customer: {}, card: '<string>'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

POST

https://api.upag.io

charges

Criar cobrança

curl --request POST \
  --url https://api.upag.io/v1/charges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "amount": 123,
  "customer": {},
  "card": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({type: '<string>', amount: 123, customer: {}, card: '<string>'})
};

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

const url = 'https://api.upag.io/v1/charges';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({type: '<string>', amount: 123, customer: {}, card: '<string>'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Cria uma cobrança Pix (type: "pix") ou de cartão (type: "card"). Pix dinâmico exige customer; cartão exige card (UUID de um cartão tokenizado) e customer. Permissão: charge.write. Apenas chave secreta (sk_…).

Os exemplos usam o sandbox (https://api.upag.dev/v1). Em produção use https://api.upag.io/v1 com sk_live_….

Endpoint

Pix

curl -X POST https://api.upag.dev/v1/charges \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pix",
    "amount": 12550,
    "description": "Pedido #10482",
    "pix": { "method": "dynamic", "dueDate": "2026-07-28T12:00:00.000Z" },
    "customer": {
      "name": "Maria Pagadora",
      "document": { "type": "cpf", "number": "39053344705" }
    }
  }'

import { Upag } from 'upag';

const upag = new Upag('sk_test_your_api_key');

const charge = await upag.charges.create({
  type: 'pix',
  amount: 12550,
  description: 'Pedido #10482',
  pix: { method: 'dynamic', dueDate: '2026-07-28T12:00:00.000Z' },
  customer: {
    name: 'Maria Pagadora',
    document: { type: 'cpf', number: '39053344705' },
  },
});

Cartão

curl -X POST https://api.upag.dev/v1/charges \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "amount": 10000,
    "installments": 3,
    "card": "5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15",
    "customer": "8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83",
    "threeDSecureSession": "9b7c1e52-3f0a-4d86-a1c4-6e2d8f35b790",
    "ipAddress": "203.0.113.10",
    "meta": { "session_id": "7f3b2a91-5c4d-4e8f-b0a1-2d6c9e1f4a73" }
  }'

import { Upag } from 'upag';

const upag = new Upag('sk_test_your_api_key');

const charge = await upag.charges.create({
  type: 'card',
  amount: 10000,
  installments: 3,
  card: '5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15',
  customer: '8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83',
  threeDSecureSession: '9b7c1e52-3f0a-4d86-a1c4-6e2d8f35b790',
  ipAddress: '203.0.113.10',
  meta: { session_id: '7f3b2a91-5c4d-4e8f-b0a1-2d6c9e1f4a73' },
});

A cobrança de cartão é processada na hora: a resposta já traz o resultado (paid, in_review ou failed). O card precisa pertencer à conta; veja o fluxo completo em Cartão com 3DS.

Parâmetros

Comuns

string

required

pix ou card.

integer

required

Valor em centavos, maior que zero. Em cartão parcelado, é o preço cheio: os juros de parcelamento não entram aqui.

string

1 a 140 caracteres. Uso interno (conciliação); não vai no QR code nem o pagador vê.

object

Até 50 chaves (1 a 40 caracteres), valores string de até 500 caracteres. Devolvido como enviado em respostas e webhooks. Em cartão, session_id é lido pela plataforma como a sessão de dispositivo do pagador (antifraude), veja Antifraude.

array

Até 100 itens informativos (não alteram valor nem taxas):

name (obrigatório, 1 a 255 caracteres)
quantity (obrigatório, inteiro de 1 a 9999)
unitAmount (obrigatório, inteiro ≥ 0, em centavos)
kind: physical, digital, shipping ou other (padrão)
sku (até 64), externalId (até 255), url (HTTP/HTTPS, até 255)

quantity × unitAmount deve caber em inteiro de 32 bits (2.147.483.647). Em cartão, os itens também seguem junto com o pagamento.

array

Repasses para outras contas: { "account": "uuid", "amount": centavos } (amount inteiro maior que zero). A soma dos splits precisa ser menor que o valor líquido da cobrança (amount menos a taxa da plataforma). A conta recebedora precisa estar ativa e não pode ser a sua.

Pix (`type: "pix"`)

object

Configuração do QR code. Padrão: dinâmico, vencendo em 10 minutos.

method: dynamic (padrão) ou static.
dueDate (só dynamic): vencimento, data ISO 8601. Padrão: 10 minutos a partir de agora.

string | object

Obrigatório no Pix dinâmico; opcional no estático. UUID de um cliente existente ou um objeto cliente inline (mesmos campos de Criar cliente). No objeto inline, o document.number identifica o cliente: se já existir na conta, é reutilizado e os demais valores enviados o atualizam; campos omitidos ou null não apagam nada.

Cartão (`type: "card"`)

string

required

UUID de um cartão tokenizado da conta.

string | object

required

UUID do cliente ou objeto cliente inline (aceita também ipAddress, com o mesmo sentido do campo da cobrança; se ambos forem enviados, vale o do cliente, e ele nunca é gravado no cadastro). O cliente precisa ter email e phone.

integer

1 a 12. Padrão 1. Acima de 1 exige parcelamento habilitado na conta, respeitando o máximo configurado. Com sessão 3DS, deve ser igual ao da sessão.

string

UUID de uma sessão 3D Secure concluída para este cartão, valor e parcelas. A sessão é consumida pela cobrança, qualquer que seja o resultado, e o cartão é cobrado no finalAmount da sessão. Sem ela, o cartão é cobrado sem 3DS.

string

IPv4 ou IPv6 público do pagador. Não é aceito em Pix.

object

Localização do pagador resolvida a partir do IP: city (até 50), state (2 letras), country (2 letras), zip (até 9). Usada só para completar o endereço de cobrança exigido pela adquirente; nunca é gravada no cliente.

string

Texto na fatura do pagador, 1 a 13 caracteres. Padrão: o descritivo da conta.

Antifraude

Em cobranças de cartão, envie meta.session_id com o identificador da sessão de dispositivo do pagador e ipAddress com o IP dele. No browser, o upag-js gera o identificador e carrega o coletor de dispositivo:

upag-js

import { UpagJs } from 'upag-js';

const upag = new UpagJs('pk_test_your_public_key');

// envie ao seu servidor junto com o card e o clientSecret/sessão 3DS
const sessionId = upag.antifraud.sessionId();

// antes de uma nova tentativa de pagamento
upag.antifraud.rotate();

Gere um session_id novo a cada tentativa de pagamento: reutilizar reduz a aprovação. Mais detalhes em SDK frontend.

Resposta

201 Created

{
  "id": "1f7d3c8a-4b52-4c9e-8a11-6d0e2f5b7c34",
  "type": "pix",
  "status": "pending",
  "amount": 12550,
  "failureCode": null,
  "description": "Pedido #10482",
  "meta": null,
  "customer": "8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83",
  "pix": {
    "reference": "9d4c2b7f6a1e40538c9b2d7f1a6e0c34",
    "qrCode": "00020101021226930014br.gov.bcb.pix...",
    "expiresAt": "2026-07-28T12:00:00.000Z"
  },
  "splits": [
    {
      "id": "b0a9c7d4-2e51-4c8f-9a3b-7d5e1f0c6a92",
      "type": "mdr",
      "status": "pending",
      "amount": 126,
      "createdAt": "2026-07-27T18:06:02.113Z",
      "updatedAt": "2026-07-27T18:06:02.113Z"
    }
  ],
  "items": [],
  "ipAddress": null,
  "paidAt": null,
  "createdAt": "2026-07-27T18:06:02.113Z",
  "updatedAt": "2026-07-27T18:06:02.113Z"
}

{
  "id": "c2a5e8d1-3b47-4f90-a6d2-9e1f0b7c4a58",
  "type": "card",
  "status": "paid",
  "amount": 10000,
  "failureCode": null,
  "description": null,
  "meta": { "session_id": "7f3b2a91-5c4d-4e8f-b0a1-2d6c9e1f4a73" },
  "customer": "8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83",
  "card": {
    "id": "5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15",
    "installments": 3,
    "nsu": "284751",
    "authorizationCode": "A1B2C3",
    "acquirerStatusCode": "0000"
  },
  "splits": [],
  "items": [],
  "ipAddress": "203.0.113.10",
  "paidAt": "2026-07-27T18:06:04.331Z",
  "createdAt": "2026-07-27T18:06:02.113Z",
  "updatedAt": "2026-07-27T18:06:04.331Z"
}

Se a adquirente recusar, a resposta continua 201, com status: "failed" e failureCode preenchido (ver códigos de falha). Campos completos em Referência de cobranças.

Erros

Status	Mensagem / código	Causa
`400`	`Account is not active`	Conta ainda não pode receber
`400`	`Splits exceed the charge amount`	Splits (mais taxa) não cabem no valor
`400`	`Split recipient cannot be the charged account`	Split para a própria conta
`400`	`Split recipient account not found or inactive`	Recebedor do split inexistente ou inativo
`400`	`Installments are not enabled for this account`	Parcelamento desabilitado
`400`	`Installments exceed the maximum of N for this account`	Parcelas acima do máximo da conta
`400`	`Card is not active` / `Card is expired`	Cartão inutilizável
`400`	`Customer is missing fields required for card payments: …`	Cliente sem `email` e/ou `phone`
`404`	`Customer not found`	UUID de cliente inexistente na conta
`404`	`Card not found`	Cartão inexistente, removido ou de outra conta
`404`	`Pix key not found`	A conta não tem chave Pix para receber
`404`	`session_not_found`	Sessão 3DS inexistente na conta
`409`	`invalid_session_state`	Sessão 3DS não concluída ou já usada
`409`	`threeds_session_mismatch`	Sessão autenticada para outro cartão, valor ou parcelas
`410`	`session_expired`	Sessão 3DS expirada
`422`	`VALIDATION_FAILED`	Corpo inválido, inclusive Pix dinâmico sem `customer`

Formato dos erros em Erros.

Cobranças

Cartões

3D Secure

Clientes

Produtos

Preços

Cupons

Faturas

Assinaturas

Links de pagamento

Sessões de checkout

Layouts de checkout

Transferências Pix

Subcontas

Apps

Chave de API

Criar cobrança

Endpoint

Pix

Cartão

Parâmetros

Comuns

Pix (`type: "pix"`)

Cartão (`type: "card"`)

Antifraude

Resposta

Erros

​Endpoint

​Pix

​Cartão

​Parâmetros

​Comuns

​Pix (type: "pix")

​Cartão (type: "card")

​Antifraude

​Resposta

​Erros

Endpoint

Pix

Cartão

Parâmetros

Comuns

Pix (`type: "pix"`)

Cartão (`type: "card"`)

Antifraude

Resposta

Erros