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.sandbox.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.sandbox.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.sandbox.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 '{
  "amount": "100.00",
  "currency": "BRL",
  "type_charge": "credit_card",
  "card": {
    "number": "4111111111111111",
    "holder_name": "TEST CARDHOLDER",
    "expiration_month": "12",
    "expiration_year": "2030",
    "cvv": "123"
  },
  "payer": {
    "name": "Test User",
    "email": "test@example.com",
    "document": "12345678909",
    "document_type": "CPF"
  },
  "description": "Quickstart test charge"
}' | 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={
          "amount": "100.00",
          "currency": "BRL",
          "type_charge": "credit_card",
          "card": {
              "number": "4111111111111111",
              "holder_name": "TEST CARDHOLDER",
              "expiration_month": "12",
              "expiration_year": "2030",
              "cvv": "123",
          },
          "payer": {
              "name": "Test User",
              "email": "test@example.com",
              "document": "12345678909",
              "document_type": "CPF",
          },
          "description": "Quickstart test charge",
      },
  )
  response.raise_for_status()
  charge = response.json()
  print(f"Charge UUID: {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({
      amount: "100.00",
      currency: "BRL",
      type_charge: "credit_card",
      card: {
        number: "4111111111111111",
        holder_name: "TEST CARDHOLDER",
        expiration_month: "12",
        expiration_year: "2030",
        cvv: "123",
      },
      payer: {
        name: "Test User",
        email: "test@example.com",
        document: "12345678909",
        document_type: "CPF",
      },
      description: "Quickstart test charge",
    }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const charge = await res.json();
  console.log("Charge UUID:", charge.uuid);
  console.log("Status:", charge.status);
  return charge;
} catch (err) {
  console.error("Charge failed:", err.message);
  throw err;
}
}

Resposta:

{
  "uuid": "chg_f1e2d3c4-b5a6-7890-fedc-ba0987654321",
  "status": "confirmed",
  "amount": "100.00",
  "currency": "BRL",
  "type_charge": "credit_card",
  "created_at": "2026-03-21T12:01:00Z"
}

Verifique o status da cobrança

Consulte a cobrança para confirmar o status final.

cURL
Python
Node.js

CHARGE_UUID="chg_f1e2d3c4-b5a6-7890-fedc-ba0987654321"

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 = "chg_f1e2d3c4-b5a6-7890-fedc-ba0987654321"

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("chg_f1e2d3c4-b5a6-7890-fedc-ba0987654321");

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