Debugging Guide

Quick Reference

WhatDebug A55 API integration issues effectively

WhyReduce time-to-resolution when something goes wrong

Reading Time10 min

DifficultyIntermediate

PrerequisitesWorking sandbox integration

Using request_id for support

Every A55 API response includes a request_id in the response body. This identifier lets A55 support trace your exact request through the processing pipeline.

{
  "uuid": "chg_abc123...",
  "status": "declined",
  "request_id": "req_7f3a2b1c-4d5e-6f78-9a0b-cdef12345678"
}

When contacting tech.services@a55.tech, always include:

1. The request_id
2. Timestamp of the request (UTC)
3. The endpoint and HTTP method
4. The HTTP status code received

HTTP Status Codes

Code	Meaning	Action
200	Success	Process the response
201	Created	Resource created successfully
400	Bad Request	Fix the request body — check required fields and formats
401	Unauthorized	Token expired or invalid — re-authenticate
403	Forbidden	Your credentials lack permission for this resource
404	Not Found	Check the URL and resource UUID
409	Conflict	Duplicate idempotency key with different payload
422	Unprocessable Entity	Validation failed — see error.details for field-level errors
429	Too Many Requests	Rate limited — wait and retry with backoff
500	Internal Server Error	A55-side issue — retry with exponential backoff
502/503	Service Unavailable	Temporary outage — retry with exponential backoff

Reading Error Responses

A55 returns structured error responses:

{
  "error": {
    "code": "INVALID_CARD_NUMBER",
    "message": "The card number failed Luhn validation",
    "details": [
      {
        "field": "card.number",
        "reason": "Must be a valid card number (Luhn check failed)"
      }
    ]
  },
  "request_id": "req_7f3a2b1c..."
}

Field	Description
error.code	Machine-readable error code — use this in your error handling logic
error.message	Human-readable description
error.details	Array of field-level validation errors (when applicable)

Sandbox Testing

The sandbox environment mirrors production behavior:

• Use test cards from the test cards reference
• Test every decline scenario your code handles
• Webhooks fire in sandbox the same as in production
• Rate limits are the same (100 req/min)

# Quick sandbox health check
curl -s -o /dev/null -w "%{http_code}" \
  "https://sandbox.api.a55.tech/api/v1/health/"
# Expected: 200

Webhook Debugging

Local development with ngrok

# Start ngrok tunnel
ngrok http 8080

# Use the HTTPS URL as your webhook_url
# https://abc123.ngrok.io/webhooks/a55

Using webhook.site

1. Go to webhook.site
2. Copy your unique URL
3. Set it as your webhook_url in charge creation
4. Inspect incoming payloads in the browser

Verifying delivery

If webhooks are not arriving:

1. Confirm your endpoint returns HTTP 200 within 5 seconds
2. Check that your endpoint is publicly accessible (not behind VPN/firewall)
3. Verify HMAC signature validation is not rejecting valid payloads
4. Check A55 retries — webhooks retry up to 5 times with exponential backoff

Charge Status Transitions

If a charge is stuck in an unexpected status:

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

Common status flows:

Flow	Statuses
Successful charge	pending → authorized → captured → settled
Auto-capture charge	pending → confirmed → settled
Declined charge	pending → declined
Refunded charge	settled → refunded
3DS challenge	pending → awaiting_3ds → authorized → captured

cURL Debug Flags

Verbose output (-v)

Shows request/response headers and TLS handshake:

curl -v -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"}' 2>&1

Full trace (--trace)

Captures every byte sent and received:

curl --trace trace.log -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"}'

# Review the trace
less trace.log

Response timing

curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\nHTTP: %{http_code}\n" \
  "https://sandbox.api.a55.tech/api/v1/health/"

Common Mistakes →Avoid the top 15 integration pitfallsRate Limiting →Handle 429 responses correctlyStatus Lifecycle →Understand charge status transitions