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.
Create a Transaction
This endpoint allows you to create a new transaction for a customer.
Authorizations
- Name
x-api-key- Type
- string (header)
- Description
Required Project API key sent in
x-api-keyheader.
- Name
x-token- Type
- string (header)
- Description
Required Session token sent in
x-tokenheader.
Headers
- Name
idempotency-key- Type
- string (header)
- Description
Required Unique key that makes POST requests idempotent.
Required attributes
- Name
amount- Type
- number
- Description
Required Amount in BRL (two decimal places).
- Name
external_ref- Type
- string
- Description
Required Unique external reference for tracking.
- Name
requester- Type
- object
- Description
Required Requester details including name, email, phone, and document.
- Name
payment_method- Type
- enum
- Description
Required The selected payment method (e.g.: "Pix").
- Name
expires_in- Type
- integer
- Description
Seconds until the QR code expires.
- Name
description- Type
- string
- Description
Transaction description.
Request
curl --request POST \
--url https://my.domain.io/api/transactions \
--header 'Content-Type: application/json' \
--header 'idempotency-key: <idempotency-key>' \
--header 'x-api-key: <api-key>' \
--header 'x-token: <api-key>' \
--data '
{
"amount": 4.00,
"external_ref": "external_ref_order",
"requester": {
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "11 99999-9999",
"document": "124.682.390-08"
},
"payment_method": "Pix",
"expires_in": 3600,
"description": "Order payment"
}
'
Use the returned magic_id or external_ref to reconcile and query status.
Properties Response
- Name
code- Type
- integer
- Description
Status code of the response.
- Name
message- Type
- string
- Description
Response message.
- Name
timestamp- Type
- string (ISO 8601)
- Description
Response timestamp.
- Name
content- Type
- object
- Description
Transaction details.
- Name
content.magic_id- Type
- string
- Description
Unique identifier for the transaction.
- Name
content.amount- Type
- number
- Description
Amount in BRL.
- Name
content.currency- Type
- string
- Description
The currency of the transaction (e.g.: "BRL").
- Name
content.status- Type
- string
- Description
The current status of the transaction (e.g.: "PENDING", "REFUSED", "APPROVED").
- Name
content.decline_reason- Type
- string | null
- Description
Reason for decline, if any.
- Name
content.description- Type
- string | null
- Description
Transaction description.
- Name
content.payment_method- Type
- string
- Description
The payment method used (e.g.: "Pix").
- Name
content.qr_code- Type
- string | null
- Description
The QR code for Pix transactions, if applicable.
- Name
content.end_to_end- Type
- string | null
- Description
End-to-end identifier for the Pix transaction.
- Name
content.requester- Type
- object
- Description
Requester details including name, email, phone, and document.
- Name
content.external_ref- Type
- string
- Description
External reference.
- Name
content.created_at- Type
- string (ISO 8601)
- Description
The date and time when the transaction was created.
- Name
content.updated_at- Type
- string (ISO 8601)
- Description
The date and time when the transaction was last updated.
Response
{
"code": 201,
"content": {
"magic_id": "18017579377364992",
"amount": 4.00,
"currency": "BRL",
"status": "PENDING",
"decline_reason": null,
"description": "Order payment",
"payment_method": "Pix",
"qr_code": "00020101021226870014br.gov.bcb.pix2565qrcode.santsbank.com/dynamic/cf1e1064-930c-42ec-9abf-03871cad65c15204000053039865802BR5910SYFRA LTDA6009SAO PAULO62070503***63045B62",
"end_to_end": "38169107220140032",
"requester": {
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "11999999999",
"document": "12468239008"
},
"external_ref": "external_ref_order",
"created_at": "2025-02-19T17:15:25.688Z",
"updated_at": "2025-02-19T17:15:26.703Z"
},
"message": "Transaction created",
"timestamp": "2025-02-19T17:15:26.703Z"
}
Query Transaction
This endpoint allows you to query a transaction.
List transactions using filters like magic_id, status, external_ref,
end_to_end, and limit.
Send x-api-key and x-token on every request.
Authorizations
- Name
x-api-key- Type
- string (header)
- Description
Required Project API key sent in
x-api-keyheader.
- Name
x-token- Type
- string (header)
- Description
Required Session token sent in
x-tokenheader.
Query Parameters
- Name
magic_id- Type
- string
- Description
Internal transaction magic ID.
- Name
status- Type
- string
- Description
Transaction status.
- Name
external_ref- Type
- string
- Description
Merchant external reference.
- Name
end_to_end- Type
- string
- Description
Bank end-to-end identifier.
- Name
limit- Type
- integer
- Description
Max items to return. Default: 20.
- Name
resend- Type
- boolean
- Description
When true, resend webhook notifications for matching transactions. Default: false.
Request
curl --request GET \
--url 'https://my.domain.io/api/transactions?limit=20' \
--header 'x-api-key: <api-key>' \
--header 'x-token: <api-key>'
Use the same external_ref you set on creation to reconcile easily.
Webhook Resend
You can request a webhook resend by adding the resend=true query parameter.
This is useful when you need to receive the webhook notification again for a
specific transaction.
The webhook will be resent with the current transaction status and data.
Properties Response
Transactions listed.
- Name
code- Type
- integer
- Description
Status code of the response. Example: 200.
- Name
content- Type
- object[]
- Description
List of transactions.
- Name
content.magic_id- Type
- string
- Description
Unique identifier for the transaction.
- Name
content.amount- Type
- number
- Description
Amount in BRL.
- Name
content.currency- Type
- string
- Description
The currency of the transaction (e.g.: "BRL").
- Name
content.status- Type
- string
- Description
The current status of the transaction (e.g.: "PENDING", "REFUSED", "APPROVED").
- Name
content.decline_reason- Type
- string | null
- Description
Reason for decline, if any.
- Name
content.description- Type
- string | null
- Description
Transaction description.
- Name
content.payment_method- Type
- string
- Description
The payment method used (e.g.: "Pix").
- Name
content.qr_code- Type
- string | null
- Description
The QR code for Pix transactions, if applicable.
- Name
content.end_to_end- Type
- string | null
- Description
End-to-end identifier for the Pix transaction.
- Name
content.requester- Type
- object
- Description
Requester details including name, email, phone, and document.
- Name
content.requester.name- Type
- string
- Description
Requester name.
- Name
content.requester.email- Type
- string
- Description
Requester email.
- Name
content.requester.phone- Type
- string
- Description
Requester phone.
- Name
content.requester.document- Type
- string
- Description
Requester document.
- Name
content.external_ref- Type
- string
- Description
External reference.
- Name
content.created_at- Type
- string (date-time)
- Description
The date and time when the transaction was created.
- Name
content.updated_at- Type
- string (date-time)
- Description
The date and time when the transaction was last updated.
- Name
message- Type
- string
- Description
Response message.
- Name
timestamp- Type
- string (date-time)
- Description
Response timestamp.
200
{
"code": 200,
"content": [
{
"magic_id": "03UdoKvLNLHg",
"amount": 4.00,
"currency": "BRL",
"status": "PENDING",
"decline_reason": null,
"description": "Order payment",
"payment_method": "Pix",
"qr_code": "00020101021126700014br.gov.bcb.pix0136e390c530-90e7-4ba4-9920-019dfd890bcf0208opcional52040000530398654044.005802BR5925Example Payments e6009Sao Paulo6108033420006229052535167e5e8be04eef991258faa6304E574",
"end_to_end": "E607894312025071873189DAHJSKH12",
"requester": {
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "11 99999-9999",
"document": "124.682.390-08"
},
"external_ref": "external_ref_order",
"created_at": "2025-02-19T17:15:25.688Z",
"updated_at": "2025-02-19T17:15:26.703Z"
}
],
"message": "Transactions listed",
"timestamp": "2025-02-19T17:15:26.703Z"
}