Create checkout session

POST/api/v1/bank/wallet/checkout/Bearer Token

---

Request headers

Header	Value	Required
Authorization	Bearer {A55_ACCESS_TOKEN}	Yes
Content-Type	application/json	Yes
Idempotency-Key	UUID v4	Recommended

Request body

Field	Type	Required	Description
wallet_uuid	string (UUID)	Yes	Wallet that receives the funds
merchant_id	string (UUID)	Yes	Merchant identifier
amount	number	Yes	Total charge amount (e.g., 250.00)
currency	string	Yes	ISO 4217 currency code
description	string	Yes	Charge description shown on checkout page
redirect_url	string	Yes	URL to redirect after payment completes
cancel_url	string	No	URL to redirect if payer cancels
due_date	string	Yes	Expiration date YYYY-MM-DD
payer_email	string	No	Pre-fill payer email on checkout page
allowed_methods	array	No	Restrict payment methods (e.g., ["credit_card", "pix"])
max_installments	integer	No	Max installments allowed (default: wallet config)
webhook_url	string	No	Override default webhook URL
reference_external_id	string	No	Your internal order ID
is_checkout	boolean	No	true (default for this endpoint)

---

Response fields

Field	Type	Description
checkout_uuid	string	Unique checkout session identifier
checkout_url	string	Hosted checkout page URL — redirect the payer here
status	string	active — session is ready for payment
amount	number	Checkout amount
currency	string	Currency code
expires_at	string	ISO 8601 session expiration
charge_uuid	string	Created when payer completes payment

---

HTTP status codes

Status	Description
200	Checkout session created
400	Invalid request body or missing required fields
401	Invalid or expired Bearer token
403	Insufficient permissions for this wallet
404	Wallet or merchant not found
422	Validation error (invalid currency, amount)
429	Rate limit exceeded
500	Internal server error — retry with exponential backoff

---

Code examples

cURL

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/checkout/ \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 990e8400-e29b-41d4-a716-446655440004" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "amount": 250.00,
    "currency": "BRL",
    "description": "Premium Plan — Monthly",
    "redirect_url": "https://your-app.com/payment/success",
    "cancel_url": "https://your-app.com/payment/cancel",
    "due_date": "2026-12-31",
    "payer_email": "maria@example.com",
    "allowed_methods": ["credit_card", "pix"],
    "max_installments": 6,
    "webhook_url": "https://your-app.com/webhooks/a55",
    "reference_external_id": "ORDER-2048"
  }'

Python

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://core-manager.a55.tech")

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/checkout/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "merchant_id": "11111111-1111-1111-1111-111111111111",
            "amount": 250.00,
            "currency": "BRL",
            "description": "Premium Plan — Monthly",
            "redirect_url": "https://your-app.com/payment/success",
            "cancel_url": "https://your-app.com/payment/cancel",
            "due_date": "2026-12-31",
            "payer_email": "maria@example.com",
            "allowed_methods": ["credit_card", "pix"],
            "max_installments": 6,
            "webhook_url": "https://your-app.com/webhooks/a55",
            "reference_external_id": "ORDER-2048",
        },
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "990e8400-e29b-41d4-a716-446655440004",
        },
    )
    response.raise_for_status()
    checkout = response.json()
    print(f"Checkout URL: {checkout['checkout_url']}")
    print(f"Session: {checkout['checkout_uuid']} — Expires: {checkout['expires_at']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Node.js

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://core-manager.a55.tech";

try {
  const response = await fetch(`${base}/api/v1/bank/wallet/checkout/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "990e8400-e29b-41d4-a716-446655440004",
    },
    body: JSON.stringify({
      wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      merchant_id: "11111111-1111-1111-1111-111111111111",
      amount: 250.00,
      currency: "BRL",
      description: "Premium Plan — Monthly",
      redirect_url: "https://your-app.com/payment/success",
      cancel_url: "https://your-app.com/payment/cancel",
      due_date: "2026-12-31",
      payer_email: "maria@example.com",
      allowed_methods: ["credit_card", "pix"],
      max_installments: 6,
      webhook_url: "https://your-app.com/webhooks/a55",
      reference_external_id: "ORDER-2048",
    }),
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  const checkout = await response.json();
  console.log(`Checkout URL: ${checkout.checkout_url}`);
  console.log(`Session: ${checkout.checkout_uuid} — Expires: ${checkout.expires_at}`);
} catch (error) {
  console.error("Checkout creation failed:", error.message);
}

---

Error response example

{
  "status": "error",
  "message": [
    {
      "code": "INVALID_REDIRECT_URL",
      "source": "validation",
      "description": "redirect_url must be a valid HTTPS URL"
    }
  ]
}

---

Payment link →Create reusable payment links for sharing.Get charge →Check charge status after checkout completion.Webhooks →Receive notification when checkout is paid.