Transaction Lifecycle

The transaction APIs cover creation, pagination, status checks, full info lookup, customer redirects, and callback delivery.

​

Creation Flows

​

Signed Flow

Use POST /api/transaction when your integration signs the raw request body with the project secret key. Required fields:

• project_uid
• amount
• currency
• success_url
• failed_url
• callback_url

Optional field:

• tx_hash

​

Unsigned Flow

Use POST /api/transaction/no_signature when wallet ownership is asserted through wallet_id. Required fields:

• project_uid
• amount
• currency
• wallet_id
• wallet_address

Optional fields:

• success_url
• failed_url
• callback_url
• tx_hash

​

Creation Response

Both creation flows return:

• status: ok
• tx, the created transaction record
• frontend_link, a redirectable frontend URL for the customer flow

​

Status Model

Transactions may appear in these states:

• pending
• confirmed
• failed
• reverted

Key transaction fields include id, amount, currency_symbol, wallet_address, event_timestamp, expiration_time, and tx_hash.

​

Listing Transactions

The API provides two ways to list project transactions:

• GET /api/transactions
• POST /api/transactions

Both support:

• project_uid
• limit, from 1 to 100
• offset, starting at 0

The response contains transactions plus meta with limit, offset, and returned.

​

Reading a Single Transaction

​

Redirect Behavior

GET /api/transaction/{id}/redirect returns a Location header on success. If the transaction state does not yet map to a redirect target, the API may return 400 instead of redirecting.

​

Operational Guidance

• use callbacks for asynchronous result delivery;
• keep status polling available for recovery and observability;
• store transaction ids as opaque values;
• handle pagination explicitly when backfilling or syncing history.

Continue with Callbacks, Widgets, and Redirects to cover delivery patterns around the transaction lifecycle.