Referência

Transferências Pix (entrada e saída) da conta da chave de API. Com chave secreta, o Pix de saída não exige PIN. Todos os endpoints exigem chave secreta (sk_…). Valores sempre em centavos.

Método	Path	Permissão
`POST`	`/v1/transfers/lookup`	`transfer.read`
`POST`	`/v1/transfers`	`transfer.write`
`GET`	`/v1/transfers`	`transfer.read`
`GET`	`/v1/transfers/{transferId}`	`transfer.read`
`GET`	`/v1/transfers/{transferId}/receipt`	`transfer.read`

Sandbox: https://api.upag.dev/v1 com sk_test_…. Produção: https://api.upag.io/v1 com sk_live_….

Estrutura

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "direction": "out",
  "type": "key",
  "amount": 10000,
  "pixKey": "55ce1aae-0d2b-4d76-bc77-294d6407349e",
  "pixKeyType": "random",
  "from": {
    "name": "Acme LTDA",
    "taxNumber": "12345678000199",
    "bankName": "Upag"
  },
  "to": {
    "name": "Maria Receiver",
    "taxNumber": "111.444.777-35",
    "bankName": "FitBank"
  },
  "endToEndId": null,
  "providerTransactionId": "555",
  "url": null,
  "createdAt": "2026-03-18T12:00:00.000Z",
  "updatedAt": "2026-03-18T12:00:00.000Z"
}

Na criação (POST /v1/transfers) a resposta inclui também transaction, o lançamento contábil (ver Criar transferência).

Atributos

string

UUID da transferência.

string

awaiting_approval, pending, processing, completed, canceled ou failed. Veja Status.

string

in (Pix recebido) ou out (Pix enviado).

string

Como o destino foi resolvido: key (chave Pix), hash (copia-e-cola) ou beneficiary (conta salva). Pela chave de API só é possível criar key e hash.

integer

Valor em centavos.

string | null

Chave Pix do destino.

string | null

email, phone, cpf, cnpj ou random.

object

Quem enviou: name, taxNumber (somente dígitos) e bankName.

object

Quem recebeu: name, taxNumber (formatado nas respostas da API, ex.: 111.444.777-35) e bankName. Nos payloads de webhook o taxNumber vem só com dígitos.

string | null

Identificador fim a fim do Pix, quando disponível.

string | null

Referência da transação no provedor.

string | null

Endereço do comprovante usado pelo dashboard (exige sessão de usuário). Com chave de API, use Comprovante.

string

ISO 8601.

string

ISO 8601.

Status

Status	Significado
`awaiting_approval`	Reservado: exige aprovação manual antes do envio
`pending`	Criada, pronta para ser enviada ao provedor
`processing`	Enviada ao provedor, aguardando liquidação
`completed`	Liquidada
`canceled`	Cancelada antes do envio
`failed`	Recusada pelo provedor (o débito é estornado)

Acompanhe por webhooks de transferência.

Próximos passos

Guia: transferência Pix

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

Estrutura

Atributos

Status

Próximos passos

​Estrutura

​Atributos

​Status

​Próximos passos

Estrutura

Atributos

Status

Próximos passos