Primeira chamada em cinco minutos

Esta API é servidor-a-servidor. Ela não roda no navegador e não deve: a chave assina cada chamada, e uma chave no front é uma chave publicada.

O que você precisa ter em mãos

Duas coisas, entregues quando a credencial foi criada:

clientId — identifica a chave, e viaja no cabeçalho X-Api-Key;
clientSecret — assina a chamada, e nunca viaja. Ele foi mostrado uma única vez, na criação. Se você não o tem mais, o caminho é revogar e criar outra — não existe "ver de novo".

Além disso, o endereço da sua API: https://<sua-conta>-api.connectionpay.io, onde <sua-conta> é o identificador da sua conta, o mesmo do endereço do seu painel (https://<sua-conta>.connectionpay.io). Os exemplos usam minhaloja-api.connectionpay.io.

Comece pelo saldo

GET /integration/v1/balances é a chamada mais barata para provar que a credencial funciona: não cria nada, não move nada e falha de um jeito só.

curl https://minhaloja-api.connectionpay.io/integration/v1/balances \
  -H "X-Api-Key: $CLIENT_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIG"

A montagem de X-Signature está em Autenticação, com código pronto em PHP, Python e Node.

Resposta:

{
  "success": true,
  "status": 200,
  "body": [
    {
      "asset": "BRL",
      "available": "1500.00",
      "held": "0.00",
      "receivable": "320.75",
      "reserve": "16.03",
      "blocked": "0.00",
      "owed": "0.00",
      "total": "1836.78"
    }
  ],
  "meta": {
    "requestId": "0f3c8a1e-4b2d-4a77-9c1e-2f5b8d9a0c31",
    "timestamp": "2026-08-20T14:03:11Z"
  }
}

Se veio 401 com error.code: "invalid_signature", a causa é quase sempre uma das três: o relógio do seu servidor está fora dos 300 segundos de tolerância, o corpo foi reserializado antes de assinar, ou o nonce foi repetido.

Depois disso

Envelope de resposta — o formato que toda resposta tem, inclusive as de erro.
Ambientes — teste e produção não se cruzam.
Receber por PIX — a primeira cobrança.
Webhooks — como saber que ela foi paga sem consultar em laço.

:::note Ids são UUID Cobranças, saques e ordens são identificados por UUID ("id": "3f7c2a9e-…"). Se você guardou o número antigo, ele ainda é aceito nas rotas de consulta até 10/02/2027: a resposta traz o id novo e os cabeçalhos Deprecation e Sunset. Depois dessa data, o número responde 404. Troque o que você tem guardado pelo UUID. :::

:::tip Valores são string Todo valor monetário vai e volta como string decimal: "1500.00", nunca 1500.00. Um float em JSON perde precisão antes mesmo de chegar ao servidor, e aqui a fração perdida tem dono. Use decimal do seu lado também. :::

O que você precisa ter em mãos​

Comece pelo saldo​

Depois disso​

O que você precisa ter em mãos

Comece pelo saldo

Depois disso