Sua Primeira Cobrança em 5 Minutos

Quick Reference

WhatFaça sua primeira cobrança de cartão de crédito no sandbox da A55

WhyValide sua configuração de integração de ponta a ponta antes de escrever código de produção

Reading Time5 min

DifficultyBeginner

PrerequisitesCredenciais sandbox (client_id + client_secret)

Visão Geral

Este guia orienta você pelo fluxo completo: autenticar, criar uma carteira, cobrar um cartão de crédito e verificar o resultado. Todos os comandos são executados no sandbox — nenhum dinheiro real é movimentado.

Cartões de Teste

Card Number	Brand	Scenario	Expected Status
`4111 1111 1111 1111`	Visa	Pagamento confirmado	confirmed
`4000 0000 0000 0002`	Visa	Cartão recusado	declined
`4000 0000 0000 0069`	Visa	Erro de processamento	error

Passos

Obtenha suas credenciais sandbox

Envie um e-mail para tech.services@a55.tech solicitando acesso ao sandbox. Você receberá:

Credencial	Descrição
`client_id`	Identificador de cliente OAuth2
`client_secret`	Segredo de cliente OAuth2
`entity_uuid`	Identificador da sua entidade
`merchant_uuid`	Identificador do seu comerciante

Armazene-os como variáveis de ambiente:

export A55_CLIENT_ID="your_client_id"
export A55_CLIENT_SECRET="your_client_secret"

Obtenha um token de acesso

A A55 utiliza o fluxo OAuth2 client_credentials. Troque suas credenciais por um token bearer.

cURL
Python
Node.js

curl -s -X POST "https://auth.a55.tech/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=${A55_CLIENT_ID}" \
-d "client_secret=${A55_CLIENT_SECRET}" \
-d "scope=api/readwrite" | python3 -m json.tool

import os
import requests

try:
  response = requests.post(
      "https://auth.a55.tech/oauth2/token",
      data={
          "grant_type": "client_credentials",
          "client_id": os.environ["A55_CLIENT_ID"],
          "client_secret": os.environ["A55_CLIENT_SECRET"],
          "scope": "api/readwrite",
      },
  )
  response.raise_for_status()
  token = response.json()["access_token"]
  print(f"Token: {token[:20]}...")
except requests.RequestException as e:
  print(f"Authentication failed: {e}")
  raise

const fetch = require("node-fetch");

async function getToken() {
try {
  const res = await fetch("https://auth.a55.tech/oauth2/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: process.env.A55_CLIENT_ID,
      client_secret: process.env.A55_CLIENT_SECRET,
      scope: "api/readwrite",
    }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const { access_token } = await res.json();
  console.log("Token:", access_token.slice(0, 20) + "...");
  return access_token;
} catch (err) {
  console.error("Authentication failed:", err.message);
  throw err;
}
}

getToken();

Salve o token:

export A55_ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIs..."

Crie uma carteira

Uma carteira agrupa cobranças sob uma única entidade. Você precisa de uma antes de criar cobranças.

cURL
Python
Node.js

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/" \
-H "Authorization: Bearer ${A55_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "name": "My First Wallet"
}' | python3 -m json.tool

import os
import requests

try:
  response = requests.post(
      "https://sandbox.api.a55.tech/api/v1/bank/wallet/",
      headers={"Authorization": f"Bearer {os.environ['A55_ACCESS_TOKEN']}"},
      json={"name": "My First Wallet"},
  )
  response.raise_for_status()
  wallet = response.json()
  print(f"Wallet UUID: {wallet['uuid']}")
except requests.RequestException as e:
  print(f"Wallet creation failed: {e}")
  raise

async function createWallet() {
try {
  const res = await fetch("https://sandbox.api.a55.tech/api/v1/bank/wallet/", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.A55_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "My First Wallet" }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const wallet = await res.json();
  console.log("Wallet UUID:", wallet.uuid);
  return wallet;
} catch (err) {
  console.error("Wallet creation failed:", err.message);
  throw err;
}
}

Resposta:

{
  "uuid": "wal_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My First Wallet",
  "status": "active",
  "created_at": "2026-03-21T12:00:00Z"
}

Crie uma cobrança de cartão de crédito

Envie um POST para o endpoint de cobrança com o cartão de teste 4111 1111 1111 1111.

cURL
Python
Node.js

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/" \
-H "Authorization: Bearer ${A55_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "merchant_id": "YOUR_MERCHANT_UUID",
  "wallet_uuid": "YOUR_WALLET_UUID",
  "payer_name": "John Does Silva",
  "payer_email": "johndoes123@gmail.com",
  "description": "Teste rápido de cobrança",
  "due_date": "2025-12-31",
  "installment_count": 1,
  "installment_value": 100.00,
  "currency": "BRL",
  "type_charge": "credit_card",
  "card_name": "John Does",
  "card_number": "4111111111111111",
  "card_expiry_year": "2030",
  "card_expiry_month": "12",
  "card_cvv": "123"
}' | python3 -m json.tool

import os
import requests

try:
  response = requests.post(
      "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
      headers={"Authorization": f"Bearer {os.environ['A55_ACCESS_TOKEN']}"},
      json={
          "merchant_id": "YOUR_MERCHANT_UUID",
          "wallet_uuid": "YOUR_WALLET_UUID",
          "payer_name": "John Does Silva",
          "payer_email": "johndoes123@gmail.com",
          "description": "Teste rápido de cobrança",
          "due_date": "2025-12-31",
          "installment_count": 1,
          "installment_value": 100.00,
          "currency": "BRL",
          "type_charge": "credit_card",
          "card_name": "John Does",
          "card_number": "4111111111111111",
          "card_expiry_year": "2030",
          "card_expiry_month": "12",
          "card_cvv": "123",
      },
  )
  response.raise_for_status()
  charge = response.json()
  print(f"Charge UUID: {charge['charge_uuid']}")
  print(f"Status: {charge['status']}")
except requests.RequestException as e:
  print(f"Charge failed: {e}")
  raise

async function createCharge() {
try {
  const res = await fetch("https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.A55_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      merchant_id: "YOUR_MERCHANT_UUID",
      wallet_uuid: "YOUR_WALLET_UUID",
      payer_name: "John Does Silva",
      payer_email: "johndoes123@gmail.com",
      description: "Teste rápido de cobrança",
      due_date: "2025-12-31",
      installment_count: 1,
      installment_value: 100.00,
      currency: "BRL",
      type_charge: "credit_card",
      card_name: "John Does",
      card_number: "4111111111111111",
      card_expiry_year: "2030",
      card_expiry_month: "12",
      card_cvv: "123",
    }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const charge = await res.json();
  console.log("Charge UUID:", charge.charge_uuid);
  console.log("Status:", charge.status);
  return charge;
} catch (err) {
  console.error("Charge failed:", err.message);
  throw err;
}
}

Resposta:

{
  "charge_uuid": "a34f2499-2a40-40a5-8f5a-578002a88f51",
  "local_currency": 100.00,
  "currency": "BRL",
  "usd_currency": 18.52,
  "type": "credit_card",
  "date": "2026-03-25",
  "description": "Teste rápido de cobrança",
  "due_date": "2025-12-31",
  "status": "confirmed",
  "message": [],
  "installment_count": 1,
  "installments": [],
  "pix_payload": {},
  "qra_payload": {},
  "applepay_payload": {},
  "charge_payment_url": null,
  "action_url": "",
  "session_id": null,
  "subscription": {},
  "reference_external_id": null,
  "is_async": false
}

Verifique o status da cobrança

Consulte a cobrança para confirmar o status final.

cURL
Python
Node.js

CHARGE_UUID="a34f2499-2a40-40a5-8f5a-578002a88f51"

curl -s -X GET "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/?charge_uuid=${CHARGE_UUID}" \
-H "Authorization: Bearer ${A55_ACCESS_TOKEN}" | python3 -m json.tool

import os
import requests

charge_uuid = "a34f2499-2a40-40a5-8f5a-578002a88f51"

try:
  response = requests.get(
      "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
      headers={"Authorization": f"Bearer {os.environ['A55_ACCESS_TOKEN']}"},
      params={"charge_uuid": charge_uuid},
  )
  response.raise_for_status()
  charge = response.json()
  print(f"Status: {charge['status']}")
except requests.RequestException as e:
  print(f"Status check failed: {e}")
  raise

async function checkStatus(chargeUuid) {
try {
  const url = new URL("https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/");
  url.searchParams.set("charge_uuid", chargeUuid);
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.A55_ACCESS_TOKEN}` },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const charge = await res.json();
  console.log("Status:", charge.status);
  return charge;
} catch (err) {
  console.error("Status check failed:", err.message);
  throw err;
}
}

checkStatus("a34f2499-2a40-40a5-8f5a-578002a88f51");

O que acontece quando você cria uma cobrança

A A55 recebe sua solicitação de cobrança e valida todos os campos
A solicitação é roteada para o melhor adquirente disponível com base no BIN do cartão, moeda e configuração do comerciante
O adquirente processa a autorização junto à bandeira do cartão (Visa/Mastercard)
A A55 retorna o resultado da autorização de forma síncrona
Se você configurou uma webhook_url, a A55 envia uma notificação assíncrona com o status final

Próximos Passos

Autenticação →Ciclo de vida do token, estratégias de renovação e escopos Integração Host-to-Host →Guia completo de integração servidor-a-servidor Webhooks →Receba notificações de pagamento em tempo real