Transaction Status

Two endpoints return the current state of a transaction. Both take the credentials in the token and secret headers; body and query values are ignored.

Transaction	Endpoint
PIX-IN or card charge	`GET /transactions/payment/{idTransaction}`
PIX-OUT	`GET /transactions/pixout/{idTransaction}`

Use them as a fallback for callbacks and before acting on a callback (see Webhooks).

PIX-IN and card

curl https://dominipay.com/api/transactions/payment/3f2b8c1e-7a4d-4e3b-9c2a-1d5e6f7a8b9c \
  -H "Accept: application/json" \
  -H "token: YOUR_TOKEN" \
  -H "secret: YOUR_SECRET"

The endpoint looks for a PIX charge first and then for a card charge. Read paymentMethod to know which shape you got.

PIX-IN response

{
  "status": "paid",
  "idTransaction": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "paymentMethod": "pix",
  "amount": 50.00,
  "taxes": 0.50,
  "liquid": 49.50
}

`status`	Meaning
`pending`	Waiting for payment.
`paid`	Paid. `liquid` was credited to your BRL balance.
`cancelled`	Cancelled.

Card response

{
  "status": "paid",
  "idTransaction": "3f2b8c1e-7a4d-4e3b-9c2a-1d5e6f7a8b9c",
  "paymentMethod": "card",
  "amount": 100.00,
  "refunded_amount": 0,
  "net_amount": 100.00,
  "currency": "USD",
  "amount_credited_brl": 530.40,
  "fx_rate": 5.304,
  "card": { "brand": "visa", "last4": "4242" },
  "paid_at": "2026-10-01T13:30:00+00:00",
  "refunded_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_is_final": true,
  "dispute": null
}

`status`	Meaning
`pending`	Waiting for the customer to pay.
`requires_action`	3D Secure pending.
`paid`	Confirmed. USD balance credited.
`cancelled`	Failed or expired without payment.
`refunded`	Fully refunded.
`partially_refunded`	Partly refunded. See `refunded_amount`.
`disputed`	Chargeback open. Funds held.
`dispute_won`	Chargeback won. Funds restored.
`dispute_lost`	Chargeback lost. Funds debited.

Field	Meaning
`amount`, `currency`	Gross amount charged (USD).
`refunded_amount`	Total refunded so far. 0 when none.
`net_amount`	`amount - refunded_amount`.
`amount_credited_brl`, `fx_rate`	BRL equivalent at the FX snapshot when the payment was confirmed. Reference only; the balance stays in USD.
`card`	Brand and last 4 digits, or `null` before a card is known.
`paid_at`, `refunded_at`	ISO 8601 timestamps or `null`. `refunded_at` is the time of the last refund.
`failure_code`, `failure_message`	Decline code and reason of the last failed attempt. `failure_message` is never empty when `failure_code` is set.
`failure_is_final`	`false` while the charge can still be paid (`pending`, `requires_action`).
`dispute`	`null`, or `id`, `status` (network stage such as `needs_response`, `under_review`, `won`, `lost`), `reason`, `amount` (USD) and `created_at`.

Read `failure_is_final` before acting on a failure

On the hosted checkout a declined attempt does not end the session. The customer can try another card on the same transaction, so you can see:

{
  "status": "pending",
  "failure_code": "insufficient_funds",
  "failure_message": "Your card has insufficient funds.",
  "failure_is_final": false
}

This is not a failed payment yet. Only cancel the order when status is cancelled (and failure_is_final is true).

Missed callbacks are recovered

For card charges still pending, processing or requires_action more than 3 minutes after creation, the endpoint refreshes the state from the card processor before answering (at most once per minute per charge). Polling it recovers a paid whose callback was lost.

Not found

{ "status": "error", "message": "Transação não existe." }

HTTP 404.

PIX-OUT

curl https://dominipay.com/api/transactions/pixout/F3A9C2D18B7E4C6A9D0E1F2A3B4C5D6E \
  -H "Accept: application/json" \
  -H "token: YOUR_TOKEN" \
  -H "secret: YOUR_SECRET"

{
  "status": "paid",
  "idTransaction": "F3A9C2D18B7E4C6A9D0E1F2A3B4C5D6E",
  "amount": 100.00,
  "taxes": 1.00,
  "liquid": 99.00
}

status is pending, paid or cancelled. Note that the PIX-OUT callback spells it canceled.

When the transaction does not exist, this endpoint answers HTTP 200 with:

{ "status": "error", "message": "Transação não exite." }

Always check the status field, not only the HTTP code.

Errors

HTTP	When
400	`token` or `secret` header missing.
401	Invalid credentials or blocked account.
403	Account limited to refunds (`REFUND_ONLY`).
404	PIX-IN or card transaction not found.