Comece aqui

Exemplos de Uso

Esta página apresenta exemplos práticos de como interagir com a API CorpX usando cURL, na ordem lógica de uma integração típica.

Variáveis de Ambiente

Configure estas variáveis antes de executar os exemplos:

# OAuth Credentials (provided during onboarding)
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"
# Account identifiers
export TENANT_ID="your-tenant-uuid"
export ACCOUNT_ID="your-account-uuid"
# Environment URLs
export API_URL="https://tenant.api.corpx.com"
export AUTH_URL="https://auth.api.corpx.com"

1. Autenticação

O primeiro passo é obter um access token OAuth2 utilizando suas credenciais de cliente.

curl -X POST "${AUTH_URL}/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=${CLIENT_ID}" \
     -d "client_secret=${CLIENT_SECRET}"

Resposta de sucesso:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300
}

Armazene o token para uso nas chamadas subsequentes:

export JWT="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

2. Consultar Saldo

Consulte o saldo disponível e bloqueado da sua conta em tempo real.

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/balance" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

Resposta:

{
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
  "total": 15000.00,
  "locked": 500.00,
  "available": 14500.00,
  "currency": "BRL",
  "updatedAt": "2024-01-15T10:30:00Z"
}

O saldo é lido em tempo real do parceiro. locked é apenas o valor bloqueado informado pela liquidante (não há detalhamento locks[] nem endpoint de lock/unlock nesta API).

3. Gerar QR Code Dinâmico (Recebimento)

Gere um QR Code dinâmico para receber um pagamento PIX de um valor específico.

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code/dynamic" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "pixKey": "contact@mycompany.com",
       "value": 150.00,
       "expirationDate": "2024-12-31T23:59:59Z",
       "allowChangeValue": false,
       "message": "Payment for order #12345",
       "identifier": "order-12345",
     }'
ValorDescrição
IMAGERetorna uma imagem Base64 do QR Code
EMVRetorna apenas a string copia e cola

4. Gerar QR Code Estático

QR Codes estáticos não expiram e são ideais para exibição permanente.

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code/static" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "pixKey": "contact@mycompany.com",
       "value": 50.00,
       "message": "Donation to project XYZ",
       "identifier": "doacao-xyz-001",
     }'

5. Consultar Status do QR Code

Verifique se o QR Code gerado anteriormente foi pago ou ainda está pendente.

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code/lookup?identifier=order-12345" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

6. PIX Out (Transferência via Chave)

Envie um PIX para uma chave de terceiros (transferência de saída).

Precisa enviar PIX sem chave PIX? Se você possui apenas os dados bancários do destinatário (ISPB, agência e conta), utilize o endpoint específico POST /v1/accounts/{accountId}/pix/out/bank-account. Veja o changelog v1.27.0 para detalhes.

6.1 PIX para CPF

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 150.00,
       "currency": "BRL",
       "keyType": "CPF",
       "key": "12345678900",
       "description": "Service payment",
       "identifier": "order-456"
     }'

6.2 PIX para Email

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 75.50,
       "currency": "BRL",
       "keyType": "EMAIL",
       "key": "supplier@company.com",
       "description": "Pagamento NF 789"
     }'

6.3 PIX para Telefone

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 200.00,
       "currency": "BRL",
       "keyType": "PHONE",
       "key": "+5511999999999",
       "description": "Transfer"
     }'

6.4 PIX para Chave Aleatória (EVP)

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 500.00,
       "currency": "BRL",
       "keyType": "EVP",
       "key": "123e4567-e89b-12d3-a456-426614174000",
       "description": "Pagamento de fornecedor"
     }'

Valores para keyType:

ValorDescriçãoFormato
CPFCPF do destinatário11 dígitos (somente números)
CNPJCNPJ do destinatário14 dígitos (somente números)
EMAILEmail do destinatárioEmail válido
PHONETelefone do destinatário+55 + DDD + número
EVPChave aleatóriaUUID v4

Resposta de sucesso:

{
  "transactionId": "txn-abc123-def456",
  "status": "APPROVED",
  "endToEndId": "E12345678202401151234abcdefghijkl",
  "amount": 150.00,
  "currency": "BRL"
}

Valores para status:

ValorDescrição
APPROVEDTransferência aprovada e concluída
PENDINGAguardando confirmação do banco
PROCESSINGEm processamento
REJECTEDRejeitada (verifique a mensagem de erro)

6.5 Consultar Status da Transferência

Consulte o status de uma transferência usando o E2E ID:

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/transactions?endToEndId=E12345678202401151234abcdefghijkl" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

Resposta:

{
  "transactionId": "txn-abc123-def456",
  "endToEndId": "E12345678202401151234abcdefghijkl",
  "status": "COMPLETED",
  "type": "CASH_OUT",
  "amount": -150.00,
  "currency": "BRL",
  "description": "PIX - MARIA DA SILVA",
  "transactionDate": "2024-01-15T12:34:00-03:00",
  "counterparty": {
    "name": "MARIA DA SILVA",
    "document": "123***01",
    "bankCode": "001"
  },
  "balance": 14350.00
}

Parâmetros de consulta:

ParâmetroDescrição
accountIdID da conta (obrigatório)
endToEndIdID E2E da transação
identifierIdentificador da cobrança ou referência

Nota: Pelo menos um dos parâmetros endToEndId ou identifier é obrigatório.

7. Pagar QR Code (PIX Out via EMV)

Pague um QR Code PIX utilizando a string EMV (copia e cola). Preferir o fluxo assíncrono (/pix/out/qr-code/async). O sync (/pix/out/qr-code) está deprecated (Sunset 2026-11-21).

7.1 Pagar QR Code assíncrono (recomendado, 202 imediato)

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/qr-code/async" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000520400005303986540010.005802BR5913Loja Exemplo6008Sao Paulo62070503***6304EFGH",
       "amount": 150.00,
       "description": "Service payment",
       "identifier": "pay-qr-async-001"
     }'

Resposta 202 com status: "ACCEPTED". O resultado final chega por webhook (pix.out.completed / failed / timeout) ou via lookup por identifier.

7.2 [DEPRECATED] Pagar QR Code síncrono

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/qr-code" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000520400005303986540510.005802BR5913Loja Exemplo6008Sao Paulo62070503***6304ABCD",
       "amount": 150.00,
       "description": "Pagamento de compra online"
     }'

Retorna headers Deprecation / Sunset / Link. Migre para /qr-code/async.

8. Solicitar Devolução

Devolva um PIX recebido anteriormente (estorno total — amount deve ser igual ao valor original).

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/refund" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "originalEndToEnd": "E12345678202401101234abcdefghijkl",
       "amount": 150.00,
       "currency": "BRL",
       "reason": "Product not available in stock"
     }'

Resposta:

{
  "refundId": "ref-abc123-def456",
  "status": "PROCESSING",
  "amount": 150.00,
  "currency": "BRL"
}

Valores para status da devolução:

ValorDescrição
PROCESSINGDevolução em processamento
COMPLETEDDevolução concluída com sucesso
REJECTEDDevolução rejeitada

9. Listar Transações Recentes (Extrato)

Recupere o histórico recente de transações da conta.

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/statement?limit=10&order=desc" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

Parâmetros de consulta:

ParâmetroTipoDescrição
pageintegerÍndice da página (base 0)
sizeintegerTeto da página (máx. 500). items pode ter menos entradas; avance com hasNext
startDatedatetimeFiltro de data inicial (ISO 8601)
endDatedatetimeFiltro de data final (ISO 8601)
limitintegerLimite total de registros (máx. 1000)
orderstringOrdem de classificação: asc ou desc

10. Gerenciar Chaves PIX

10.1 Listar Chaves PIX

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

10.2 Registrar uma Nova Chave PIX

E-mail e telefone exigem OTP

POST /v1/accounts/{accountId}/pix/keys com email ou phone responde 202 e a facade envia o código. Confirme em POST .../pix/keys/verify. Falha de envio é 503 otp_send_failed.

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "keyType": "cpf",
       "pixKey": "12345678900"
     }'

Valores para keyType no cadastro:

ValorDescrição
cpfCPF do titular da conta
cnpjCNPJ do titular da conta
randomChave aleatória (EVP) - gerada automaticamente pelo sistema
phoneTelefone E.164 — 202 + OTP (Twilio)
emailE-mail — 202 + OTP (SES)

10.3 Registrar uma Chave Aleatória (EVP)

Para chaves aleatórias, omita o campo pixKey:

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "keyType": "random"
     }'

10.4 Excluir uma Chave PIX

curl -X DELETE "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys/contact%40mycompany.com" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

11. Consultar MEDs (Mecanismo Especial de Devolução)

Liste as disputas abertas contra a conta. A lista é montada a partir dos webhooks pix.med.opened / pix.med.updated — sem assiná-los ela fica vazia. Ver Disputas (MED).

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med?limit=20" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

Parâmetros:

ParâmetroValoresDescrição
limitintegerMáximo de itens (padrão 50, teto 200)
offsetintegerDeslocamento para paginar

Não há filtro por status: a API não expõe status de disputa. O liquidante não tem consulta de relato, então o estado atual não é verificável — o que a API mostra é answered (se você respondeu) e o prazo.

11.1 Anexar evidência

Três passos, e todos antes de responder — anexo depois da resposta não entra na defesa (409 conflict).

# 1. URL de upload
PRESIGN=$(curl -sS -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med/${MED_ID}/evidence/upload-url" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d '{"filename":"comprovante.pdf","contentType":"application/pdf","sizeBytes":184320}')
UPLOAD_URL=$(echo "$PRESIGN" | jq -r .uploadUrl)
KEY=$(echo "$PRESIGN" | jq -r .key)
# 2. PUT direto no armazenamento (sem header de auth nosso)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @comprovante.pdf
# 3. Registrar o anexo na disputa
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med/${MED_ID}/evidence/add" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d "{\"key\":\"${KEY}\",\"filename\":\"comprovante.pdf\",\"contentType\":\"application/pdf\",\"sizeBytes\":184320}"

Limites: 5 MB por arquivo, 6 MB e 10 arquivos por disputa, e só PDF/JPEG/PNG/WebP/TXT/CSV. Cada arquivo passa por antivírus e sanitização antes de valer como evidência (scanStatus).

11.2 Responder a um MED

O titular tem 48h desde a abertura (clientAnswerDeadline) para se defender. A resposta é enviada uma vez: a segunda chamada recebe 409 conflict.

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med/204cc938-da3d-4f04-baf3-0b2e6a2f1283/answer" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d '{
       "result": "DISAGREE",
       "reason": "Venda legítima: cliente cadastrado há 14 meses, entrega com rastreio confirmado."
     }'

Valores para result:

ValorDescrição
AGREEReconhece a fraude relatada
DISAGREEContesta o relato. Exige reason (422 invalid_payload sem ele)

A resposta é 202. Ela registra a sua defesa e a encaminha, com os anexos, ao time que conduz a disputa — nada é enviado ao liquidante por esta chamada e nenhum status muda. Não existe rota de decisão: devolver ou recusar o PIX disputado não é feito por esta API.

12. Transferência Interna

Transfira fundos entre contas do mesmo banco (sem custo, instantânea).

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/transfers/internal" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "branch": "0001",
       "account": "123456-7",
       "taxNumber": "12345678900",
       "value": 500.00,
       "message": "Transfer between accounts",
       "identifier": "transf-int-12345"
     }'

Tratamento de Erros Comuns

Saldo Insuficiente

{
  "errorCode": "insufficient_balance",
  "message": "insufficient available balance: 50.00 (total: 100.00, locked: 50.00, requested: 150.00)"
}

Chave PIX Inválida

{
  "errorCode": "invalid_payload",
  "message": "keyType must be one of: CPF, CNPJ, EMAIL, PHONE, EVP"
}

Conflito de Idempotência

{
  "errorCode": "idempotency_conflict",
  "message": "Request with same Idempotency-Key but different payload"
}

Boas Práticas

  1. Sempre use Idempotency-Key em operações POST/PUT/PATCH para evitar duplicidades
  2. Armazene o endToEndId das transações para rastreamento e devoluções
  3. Implemente retry com backoff exponencial para erros 5xx
  4. Valide o saldo antes de operações de saída para melhor experiência do usuário
  5. Configure webhooks para receber notificações em tempo real

Para mais detalhes sobre cada endpoint, consulte a Referência da API ou o Guia de Integração.