Create Transaction

Creates a payment transaction. Supports PIX, BOLETO and CREDIT_CARD. Monetary values are always in cents (integers).

POST/api/v1/transactions/create

Headers

Header	Value	Status
Content-Type	application/json	Required
Accept	application/json	Required
X-Client-Id	<client_id>	Required
X-API-Key	<api_key>	Required
X-Operation-Token	<token with scope transaction:create>	Required
Idempotency-Key	tx_<unique>	Recommended

The X-Operation-Token header is required and must be generated at POST /api/v1/operation-auth/token with scope transaction:create. See Authentication for details.

The Idempotency-Key header is recommended to avoid duplicate transactions.

Important

All monetary values (amount, unitPrice, fee) must be sent in cents (integers).

Request Body (PIX)

Body

{
  "amount": 500,
  "currency": "BRL",
  "paymentMethod": "PIX",
  "installments": 1,
  "customer": {
    "id": "CUST-1729131560000",
    "name": "John Test",
    "email": "john.test+1729131560000@example.com",
    "document": { "number": "24577481600", "type": "CPF" },
    "phone": "11987654321",
    "externalRef": "LEAD-1234"
  },
  "shipping": {
    "fee": 0,
    "address": {
      "street": "Rua dos Testes",
      "streetNumber": "123",
      "complement": "Sala 2",
      "zipCode": "01001000",
      "neighborhood": "Centro",
      "city": "Sao Paulo",
      "state": "SP",
      "country": "BR"
    }
  },
  "items": [
    {
      "title": "Product X",
      "unitPrice": 500,
      "quantity": 1,
      "tangible": true,
      "externalRef": "SKU-001"
    }
  ],
  "pix": { "expiresInDays": 1 },
  "postbackUrl": "",
  "metadata": "{\"source\":\"n8n\",\"environment\":\"staging\"}",
  "traceable": true,
  "ip": "177.123.45.67"
}

Response 200 (PIX)

Minimal Example

Basic response as seen in production:

Response

{
  "data": {
    "id": "ebe485c6-cdf4-4736-aa3e-464044c4d4eb",
    "externalRef": "686725",
    "amount": 500,
    "refundedAmount": 0,
    "providerCompanyId": "b6877393-8a98-4e4e-8a20-e086aacf3d8c",
    "companyId": null,
    "installments": 1,
    "paymentMethod": "PIX",
    "status": "WAITING_PAYMENT",
    "postbackUrl": "",
    "metadata": null,
    "traceable": true,
    "secureId": null,
    "secureUrl": null
  },
  "status": 200,
  "message": "Transacao criada com sucesso."
}

Full Example

When the provider returns additional fields:

Full Response

{
  "data": {
    "id": "43836dbe-be02-47bc-965b-c51487b83b06",
    "externalRef": "686671",
    "amount": 500,
    "refundedAmount": 0,
    "providerCompanyId": "b6877393-8a98-4e4e-8a20-e086aacf3d8c",
    "installments": 1,
    "paymentMethod": "PIX",
    "status": "WAITING_PAYMENT",
    "postbackUrl": "",
    "metadata": null,
    "traceable": true,
    "createdAt": "2025-10-17T01:38:51.943Z",
    "updatedAt": "2025-10-17T01:38:51.943Z",
    "paidAt": "2025-10-17T01:38:58.193Z",
    "ip": "146.190.148.63",
    "endToEndId": null,
    "externalNsu": null,
    "currency": "BRL",
    "pix": {
      "qrcode": "0002010102122682...6304",
      "url": null,
      "expirationDate": "2025-10-18T01:38:51.943Z"
    }
  },
  "status": 200,
  "message": "Transacao criada com sucesso."
}

Important Notes

•amount, unitPrice, fee are in cents
•providerCompanyId is the provider's GUID (different from the internal companyId)
•For PIX, if pix.url is null, use qrcode as the BR Code
•Dates may be missing in some cases; when present, they are ISO-8601 UTC
•Store data.id as providerTxId for later lookups and reconciliation

Errors

All errors follow the RFC 7807 Problem Details format (text fields are in Portuguese):

Error

{
  "type": "https://httpstatuses.com/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Campo 'amount' e obrigatorio",
  "errors": { "amount": ["O valor precisa ser inteiro em centavos."] },
  "traceId": "00-3a2b...-01"
}

Code	Description
400	Bad Request: invalid data or missing required fields
401	Unauthorized: invalid or missing credentials
403	Forbidden: access to the resource denied
404	Not Found: resource not found
409	Conflict: state conflict (e.g. duplicate transaction)
422	Unprocessable Entity: business validation failed
500	Internal Server Error: internal server error

cURL Example

cURL

# 1. First, generate the operation token
TOKEN=$(curl -s -X POST https://baanko.app/api/v1/operation-auth/token \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -d '{"scopes": ["transaction:create"]}' | jq -r '.token')
# 2. Create the transaction with the token
curl -X POST https://baanko.app/api/v1/transactions/create \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Operation-Token: $TOKEN" \
  -H "Idempotency-Key: tx_$(date +%s)_$RANDOM" \
  -d '{
    "amount": 500,
    "currency": "BRL",
    "paymentMethod": "PIX",
    "installments": 1,
    "customer": {
      "id": "CUST-123",
      "name": "John",
      "email": "john@ex.com",
      "document": {"number": "24577481600", "type": "CPF"},
      "phone": "11987654321"
    },
    "items": [{
      "title": "Product X",
      "unitPrice": 500,
      "quantity": 1,
      "tangible": true
    }],
    "pix": { "expiresInDays": 1 },
    "postbackUrl": "",
    "traceable": true,
    "ip": "177.123.45.67"
  }'

JavaScript Example (fetch)

JavaScript

// 1. Generate the operation token
const tokenResponse = await fetch("https://baanko.app/api/v1/operation-auth/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Client-Id": "<CLIENT_ID>",
    "X-API-Key": "<API_KEY>"
  },
  body: JSON.stringify({
    scopes: ["transaction:create"],
    expiresInSeconds: 300
  })
});
const { token } = await tokenResponse.json();
// 2. Create the transaction with the token
const response = await fetch("https://baanko.app/api/v1/transactions/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Client-Id": "<CLIENT_ID>",
    "X-API-Key": "<API_KEY>",
    "X-Operation-Token": token,
    "Idempotency-Key": `tx_${Date.now()}_${Math.floor(Math.random()*1e6)}`
  },
  body: JSON.stringify({
    amount: 500,
    currency: "BRL",
    paymentMethod: "PIX",
    installments: 1,
    customer: {
      id: "CUST-123",
      name: "John",
      email: "john@ex.com",
      document: { number: "24577481600", type: "CPF" },
      phone: "11987654321"
    },
    items: [{
      title: "Product X",
      unitPrice: 500,
      quantity: 1,
      tangible: true
    }],
    pix: { expiresInDays: 1 },
    postbackUrl: "",
    traceable: true,
    ip: "177.123.45.67"
  })
});
const data = await response.json();
console.log(data);

Final Notes

Save the returned id as providerTxId for later lookups and reconciliation.

Status updates also arrive through the webhook configured in postbackUrl.

Polling GET /api/checkout/status/{id} is optional, but useful to check the transaction's current status.