Acessar minha contaAbrir uma conta
POST/api/v2/pix/pagamentos/chave

Por chave

Consulta a chave no DICT, valida transação local (mesmo ISPB) e persiste pagamento INICIADO (status: "0", tipo: 1). Valor tipicamente 0 até a confirmação. Scope: pix.write.

Parâmetros

AcceptObrigatório
header

Tipo de conteúdo aceito na resposta

Tipo:string
Content-TypeObrigatório
header

Tipo de conteúdo da requisição

Tipo:string

Autenticação e scopes

Requer Bearer token com scope pix.write.

Headers

HeaderObrigatórioDescrição
AuthorizationSimBearer {{access_token}}
AcceptSimapplication/json
Content-TypeSimapplication/json

Body

CampoObrigatórioTipoDescrição
chaveSimStringChave Pix do recebedor (CPF, CNPJ, e-mail, telefone ou EVP).
txidNãoStringSe omitido, gerado automaticamente (~26 caracteres).
uuidNãoStringUUID externo opcional do pagamento.

Retorno 200 (iniciação)

Objeto PagamentoResource no nível raiz (status: "0" = INICIADO). Características desta rota:

CampoValor típico
endToEndIdPresente (DICT)
chaveChave consultada
valor0 (definir na confirmação)
tipo1 (dict)
idUUID — usar em confirmar

Campos principais: id, endToEndId, chave, valor, txid, status, tipo, id_req, recebedor, pagador, dataHoraCriacao, dataHoraAtualizacao, tipo_transacao (-1), rec_status (null). Opcional: correlationId.

Schema completo e mapeamentos: Visão geral.

Fluxo

  1. Inicie com este endpoint.
  2. Confirme em POST /api/v2/pix/pagamentos/confirmar com id e valor.

Códigos de resposta

CódigoSignificadoDescrição
200OKPagamento iniciado.
201CreatedPagamento iniciado.
400Bad RequestParâmetros inválidos.
401UnauthorizedToken inválido ou expirado.
403ForbiddenScope ausente ou pagador = recebedor.
422Unprocessable EntityValidação rejeitada.
500Internal Server ErrorErro interno do servidor.

Notas

curl --location 'https://api-h.nuvende.com.br/api/v2/pix/pagamentos/chave' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "chave": "{{chave_pix_recebedor}}",
  "txid": ""
}'

{
  "id": "794d7b9e-1a42-4a12-93c2-b48c0d63f730",
  "endToEndId": "E382973742026070812519TFXDFWFD11",
  "chave": "efca2b48-0d8a-4f10-9f07-26e6b5a1b921",
  "valor": 0,
  "txid": "qykhwjRKogXV28MnPcQTmC36iO",
  "status": "0",
  "tipo": 1,
  "id_req": null,
  "recebedor": {
    "pessoa": {
      "nome": "Maria Souza Exemplo",
      "cpfCnpj": "52998224725",
      "tipo": 0
    },
    "conta": {
      "ispb": "38297374",
      "agencia": "0001",
      "conta": "00001234",
      "dataAbertura": "2025-06-18T11:21:45.000000Z",
      "tipo": 0
    }
  },
  "pagador": {
    "pessoa": {
      "nome": "João Silva Exemplo",
      "cpfCnpj": "39053344705",
      "tipo": 0
    },
    "conta": {
      "ispb": "38297374",
      "agencia": "0001",
      "conta": "00005678",
      "dataAbertura": "2026-06-26T20:06:56.000000Z",
      "tipo": 0
    }
  },
  "dataHoraAtualizacao": "2026-07-08T12:51:31.000000Z",
  "dataHoraCriacao": "2026-07-08T12:51:31.000000Z",
  "tipo_transacao": -1,
  "rec_status": null
}

const axios = require("axios");

axios
  .post(
    "https://api-h.nuvende.com.br/api/v2/pix/pagamentos/chave",
    {
      chave: "{{chave_pix_recebedor}}",
      txid: "",
    },
    {
      headers: {
        Accept: "application/json",
        Authorization: "Bearer {{access_token}}",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => console.log(JSON.stringify(response.data)))
  .catch((error) => console.log(error.response?.data || error.message));

import requests

url = "https://api-h.nuvende.com.br/api/v2/pix/pagamentos/chave"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "Content-Type": "application/json",
}
payload = {"chave": "{{chave_pix_recebedor}}", "txid": ""}
response = requests.post(url, headers=headers, json=payload)
print(response.text)

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api-h.nuvende.com.br/api/v2/pix/pagamentos/chave',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Accept: application/json',
    'Authorization: Bearer {{access_token}}',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'chave' => '{{chave_pix_recebedor}}',
    'txid' => '',
  ]),
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;