Acessar minha contaAbrir uma conta
POST/api/v2/baas/pix/payments/key

Por chave

Produto BaaS (titular). Requer Bearer JWT do login da conta e assinatura HMAC obrigatória. Scope: baas.pix-payments.write. Guia: documentação técnica.

Parâmetros

AcceptObrigatório
header
Tipo:string
X-SignatureObrigatório
header

Assinatura HMAC-SHA256 da requisição (hex).

Tipo:string
X-TimestampObrigatório
header

Timestamp Unix (segundos, UTC) usado na assinatura.

Tipo:string
X-NonceObrigatório
header

Nonce único por requisição (anti-replay).

Tipo:string

Autenticação e headers

Requer Bearer token do login da conta e assinatura HMAC obrigatórios. Scope: baas.pix-payments.write.

HeaderObrigatórioDescrição
AuthorizationSimBearer {{access_token}}
AcceptSimapplication/json
X-SignatureSimAssinatura HMAC
X-TimestampSimTimestamp da assinatura
X-NonceSimNonce único por requisição

Corpo

Valores em centavos. Consulte a chave no DICT antes de type_initiation = 1.

CampoObrigatório HTTPDescrição
valueSimInteiro > 0 (ex.: 10050 = R$ 100,50). App limita a R$ 15.000,00
type_initiationSim0 manual (agência/conta), 1 por chave
ispbSimISPB do banco destino
agencySimAgência destino
accountSimConta destino (diferente da conta origem)
account_typeSim0 corrente, 1 salário, 2 poupança, 3 pagamento, 4 PI
documentSimCPF ou CNPJ do destinatário, sem pontuação
person_typeSim0 PF, 1 PJ
idempotency_keySimUUID v4, máx. 36 caracteres
keyCondicionalObrigatório se type_initiation = 1
nameCondicionalObrigatório se type_initiation = 1; no manual (0) o app sempre envia
favoriteNão (fluxo: sim)Salvar favorito; default false
appointment_dateCondicionalY-m-d, após hoje, se agendar
schedule_monthsCondicional1 a 12, se recorrência
descriptionNãoMáx. 60 caracteres

Erros comuns

CódigoCorpoCausa
422You cannot transfer to your own account.Destino é a própria conta
422Invalid key.Chave inválida no DICT
422The key data was not validated, try again later.Consulta DICT sem documento
400Insufficient balance.Saldo insuficiente
400Value exceeds pix limit.Limite diário Pix
400You have reached the limit of transfers per minute.Rate limit
400invalid_userConta em análise

Notas

curl --request POST \
  --url 'https://api-h.nuvende.com.br/api/v2/baas/pix/payments/key' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'X-Timestamp: {{timestamp}}' \
  --header 'X-Nonce: {{nonce}}' \
  --header 'X-Signature: {{signature}}' \
  --data '{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "type_initiation": 1,
  "value": 10050,
  "key": "[email protected]",
  "name": "João Recebedor Exemplo",
  "ispb": "60701190",
  "agency": "0001",
  "account": "1234567",
  "account_type": 0,
  "document": "52998224725",
  "person_type": 0,
  "favorite": false,
  "description": "Pagamento servico exemplo"
}'

const axios = require("axios");

const data = {
  idempotency_key: "550e8400-e29b-41d4-a716-446655440000",
  type_initiation: 1,
  value: 10050,
  key: "[email protected]",
  name: "João Recebedor Exemplo",
  ispb: "60701190",
  agency: "0001",
  account: "1234567",
  account_type: 0,
  document: "52998224725",
  person_type: 0,
  favorite: false,
  description: "Pagamento servico exemplo",
};

axios({
  method: "post",
  url: "https://api-h.nuvende.com.br/api/v2/baas/pix/payments/key",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
    Authorization: "Bearer {{access_token}}",
    "X-Timestamp": "{{timestamp}}",
    "X-Nonce": "{{nonce}}",
    "X-Signature": "{{signature}}",
  },
  data,
})
  .then((response) => console.log(JSON.stringify(response.data)))
  .catch((error) => console.log(error.response?.data || error.message));

import json
import requests

url = "https://api-h.nuvende.com.br/api/v2/baas/pix/payments/key"
payload = {
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
    "type_initiation": 1,
    "value": 10050,
    "key": "[email protected]",
    "name": "João Recebedor Exemplo",
    "ispb": "60701190",
    "agency": "0001",
    "account": "1234567",
    "account_type": 0,
    "document": "52998224725",
    "person_type": 0,
    "favorite": false,
    "description": "Pagamento servico exemplo",
}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "X-Timestamp": "{{timestamp}}",
    "X-Nonce": "{{nonce}}",
    "X-Signature": "{{signature}}",
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.text)

<?php
$curl = curl_init();
$opts = [
  CURLOPT_URL => 'https://api-h.nuvende.com.br/api/v2/baas/pix/payments/key',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "type_initiation": 1,
  "value": 10050,
  "key": "[email protected]",
  "name": "João Recebedor Exemplo",
  "ispb": "60701190",
  "agency": "0001",
  "account": "1234567",
  "account_type": 0,
  "document": "52998224725",
  "person_type": 0,
  "favorite": false,
  "description": "Pagamento servico exemplo"
}',
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer {{access_token}}',
    'X-Timestamp: {{timestamp}}',
    'X-Nonce: {{nonce}}',
    'X-Signature: {{signature}}',
  ],
];
curl_setopt_array($curl, $opts);
$response = curl_exec($curl);
curl_close($curl);
echo $response;

{
  "id": 1268,
  "receiver_account_id": 84,
  "payer_account_id": 33,
  "movement_date": "15/07/2026 14:30:00",
  "value": "100.50",
  "type": 23,
  "status": 1,
  "status_details": "CONFIRMADO",
  "transaction_type": "pix",
  "end_to_end_id": "E3829737420260715173040123456789",
  "qr_code_payload": null,
  "end_to_end_devolution_id": null,
  "internal_id_request": "550e8400-e29b-41d4-a716-446655440000",
  "jd_id": "JDPI-20260715143000-001",
  "description": "Pagamento servico exemplo",
  "payment_description": "Pagamento servico exemplo",
  "receiver_account": {
    "id": 84,
    "name": "Joao Recebedor Exemplo",
    "document": "52998224725",
    "customer_id": 63,
    "company_id": null,
    "bank": {
      "id": 1,
      "name": "Instituicao Exemplo",
      "compe_code": "260",
      "ispb_code": "38297374"
    },
    "key": "[email protected]",
    "key_type": 2,
    "agency": "0001",
    "account": "00001252",
    "type": 0,
    "is_local": false
  },
  "payer_account": {
    "id": 33,
    "name": "Maria Pagadora Exemplo",
    "document": "11144477735",
    "customer_id": 62,
    "company_id": null,
    "bank": {
      "id": 1,
      "name": "Instituicao Exemplo",
      "compe_code": "260",
      "ispb_code": "38297374"
    },
    "key": null,
    "key_type": null,
    "agency": "0001",
    "account": "00000337",
    "type": 0,
    "is_local": true
  },
  "is_favorite": false,
  "is_local": true,
  "is_receiver": false,
  "appointment_date": null,
  "error_description": null,
  "created_at": "2026-07-15 14:30:00",
  "rec_status": null
}

curl --request POST \
  --url 'https://api-h.nuvende.com.br/api/v2/baas/pix/payments/key' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'X-Timestamp: {{timestamp}}' \
  --header 'X-Nonce: {{nonce}}' \
  --header 'X-Signature: {{signature}}' \
  --data '{"idempotency_key":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type_initiation":0,"value":1050,"ispb":"60701190","agency":"0001","account":"1234567","account_type":0,"document":"52998224725","person_type":0,"description":"Pagamento manual exemplo"}'

curl --request POST \
  --url 'https://api-h.nuvende.com.br/api/v2/baas/pix/payments/key' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'X-Timestamp: {{timestamp}}' \
  --header 'X-Nonce: {{nonce}}' \
  --header 'X-Signature: {{signature}}' \
  --data '{"idempotency_key":"c3d4e5f6-a7b8-9012-cdef-123456789abc","type_initiation":1,"value":1050,"key":"[email protected]","name":"João Recebedor Exemplo","ispb":"60701190","agency":"0001","account":"1234567","account_type":0,"document":"11144477735","person_type":0,"description":"Pagamento agendado exemplo","appointment_date":"2025-02-01"}'

curl --request POST \
  --url 'https://api-h.nuvende.com.br/api/v2/baas/pix/payments/key' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'X-Timestamp: {{timestamp}}' \
  --header 'X-Nonce: {{nonce}}' \
  --header 'X-Signature: {{signature}}' \
  --data '{"idempotency_key":"d4e5f6a7-b8c9-0123-def0-23456789abcd","type_initiation":1,"value":50000,"key":"[email protected]","name":"Loja Exemplo LTDA","ispb":"60701190","agency":"0001","account":"9876543","account_type":0,"document":"43587980000107","person_type":1,"description":"Pagamento fornecedor exemplo"}'

{
  "value": [
    "The value field is required."
  ],
  "message": "You cannot transfer to your own account."
}

{
  "message": "Invalid key."
}

{
  "message": "The key data was not validated, try again later."
}

{
  "message": "Insufficient balance."
}

{
  "message": "Your account is under review. This may take up to 1 business day.",
  "error_type": "invalid_user",
  "status": "pending",
  "document_status": "waiting"
}