Transactions

Transactions are a core part of our system — they represent payments made by customers using different methods. On this page, we’ll dive into the different transaction endpoints you can use to manage payments programmatically. We'll look at how to create, retrieve, and update transactions.

The Transaction Model

The transaction model contains all the necessary details about a payment. Each transaction includes information about the customer, payment method, and order details.

POST/transaction

Create a Transaction

This endpoint allows you to create a new transaction for a customer.

Required attributes

Name
amount
Type
integer
Description
Required The amount of the transaction in cents.
Name
customer
Type
object
Description
Required Customer details including name, email, and address.
Name
items
Type
array
Description
Required List of items being purchased.
Name
method
Type
enum
Description
Required The selected payment method (e.g.: "PIX", "CARD", "INVOICE").
Name
installments
Type
integer
Description
Number of installments for the payment (if payment method is 'CARD').
Name
externalRef
Type
string
Description
Unique external reference for tracking.
Name
postback
Type
string
Description
URL to receive transaction updates.
Name
card
Type
object
Description
Credit card details (if payment method is "CARD").

Request

POST

/transaction

curl -X POST https://api.domain.com/transaction \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 400,
    "externalRef": "external_ref_order",
    "postback": "https://webhook.site/839b308b-adc7-465b-af9f-9d3999001196",
    "customer": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "11 99999-9999",
      "document": "124.682.390-08",
      "address": {
        "street": "Rua das Flores",
        "number": "123",
        "city": "São Paulo",
        "state": "SP",
        "country": "Brasil",
        "zip": "12345-678"
      }
    },
    "items": [
      {
        "title": "Produto",
        "unitPrice": 400,
        "quantity": 1,
        "tangible": true
      }
    ],
    "method": "PIX",
    "installments": 1,
    "card": {
      "number": "1234567890123456",
      "holder_name": "John Doe",
      "expiration_month": "07",
      "expiration_year": "2030",
      "cvv": "613"
    }
  }'

Properties Response

Name
id
Type
string
Description
Unique identifier for the transaction.
Name
status
Type
enum
Description
The current status of the transaction (e.g.: "CREATED","PENDING","REFUSED","APPROVED").
Name
total
Type
integer
Description
The total amount of the transaction in cents.
Name
method
Type
enum
Description
The payment method used (e.g.: "PIX", "CARD", "INVOICE").
Name
qrcode
Type
string
Description
The QR code for PIX transactions, if applicable.
Name
invoice
Type
string | null
Description
The invoice ID if the transaction generates an invoice; otherwise, null.
Name
currency
Type
string
Description
The currency of the transaction (e.g.: "BRL").
Name
identifier
Type
string
Description
Transaction identifier created.
Name
external_ref
Type
string
Description
External reference.
Name
customer
Type
object
Description
Customer details including ID, name, email, phone, and document.
Name
created_at
Type
string (ISO 8601)
Description
The date and time when the transaction was created.
Name
updated_at
Type
string (ISO 8601)
Description
The date and time when the transaction was last updated.

Response

{
  "id": "18017579377364992",
  "status": "PENDING",
  "total": 400,
  "method": "PIX",
  "qrcode": "00020101021226870014br.gov.bcb.pix2565qrcode.santsbank.com/dynamic/cf1e1064-930c-42ec-9abf-03871cad65c15204000053039865802BR5910SYFRA LTDA6009SAO PAULO62070503***63045B62",
  "invoice": null,
  "currency": "BRL",
  "identifier": "38169107220140032",
  "external_ref": "external_ref_order",
  "customer": {
    "id": "18017579247341568",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "11999999999",
    "document": "12468239008",
  },
  "created_at": "2025-02-19T17:15:25.688Z",
  "updated_at": "2025-02-19T17:15:26.703Z",
}