Skip to main content
POST
/
payment
/
execute
/
on-chain
curl --request POST \
  --url https://api.starkfi.io/payment/execute/on-chain \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "executor_id": "api_transaction",
    "payment_id": "cmoejr9eh000401nyffxgmxtj",
    "signed_transaction": "0x02f8b282a4ec..."
  }'

{
  "statusCode": 200,
  "success": true,
  "status": "payment_confirmed",
  "message": "Payment confirmed",
  "data": {
    "id": "cmoejr9eh000401nyffxgmxtj",
    "tid_hash": "0xabc123...def456"
  }
}
​
x-api-key
string
required
Your StarkFi API key. You can find it in your dashboard.
You must always use this endpoint for all on-chain operations. Never send transactions via your own broadcast or directly through the user’s wallet (e.g. using sendTransaction). The user should only sign the transaction — after signing, your backend must forward it here. This ensures all required steps for payment processing and order confirmation are properly executed.
​
executor_id
string
required
Transaction executor type. Use api_transaction when the request comes via API.
​
payment_id
string
required
Unique payment identifier generated in the Create Transaction step.
​
signed_transaction
string
required
Signed transaction hex string generated by the user’s wallet after signing the crypto_tx received from the create transaction endpoint.
curl --request POST \
  --url https://api.starkfi.io/payment/execute/on-chain \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "executor_id": "api_transaction",
    "payment_id": "cmoejr9eh000401nyffxgmxtj",
    "signed_transaction": "0x02f8b282a4ec..."
  }'

{
  "statusCode": 200,
  "success": true,
  "status": "payment_confirmed",
  "message": "Payment confirmed",
  "data": {
    "id": "cmoejr9eh000401nyffxgmxtj",
    "tid_hash": "0xabc123...def456"
  }
}

​
Response

​
statusCode
number
required
HTTP status code. Returns 200 on success.
​
success
boolean
required
Whether the request succeeded.
​
status
enum<string>
required
Broadcast result status. Available options: payment_confirmed, payment_received
  • payment_confirmed — broadcast accepted and transaction receipt confirmed on-chain. Order status updated to success.
  • payment_received — transaction confirmed on source chain. Worker (FinalizerTransferWorker) takes over to monitor the bridge via LiFi. Order status updated to received.
​
message
string
required
Human-readable response message.
​
data
object
required
Broadcast result data.

​
Errors

​
Before broadcast

These occur during payload or order validation, before any transaction is sent to the network.
HTTPstatusWhen it occurs
400invalid_parametersInvalid payload — schema validation failed
400invalid_chainOrder’s chain is not enabled or not supported
404payment_not_foundpayment_id does not exist
409invalid_payment_statusOrder is not in registered or retry status
409missing_unsigned_transactionUnsigned tx was not generated before execute
400invalid_signed_transactionInvalid signature or mismatch with the unsigned tx
400stale_transaction_nonceTransaction nonce is out of sync

​
During broadcast

These occur after validation, during or after the broadcast to the network.
HTTPstatusWhen it occurs
500payment_failedReceipt received but transaction was reverted on-chain
500finalizer_payment_order_on_chain_failedUnexpected exception inside the finalizer
500blockchain_transaction_failedException caught by the controller before reaching the finalizer

​
Order status lifecycle

Once broadcast is submitted, the order moves through the following states: 
registered / retry
  → processing          (execute started)
  → processing          (signed_tx saved)
  → success             (FinalizerTransferOnChain: broadcast confirmed)
  → received            (FinalizerBridgeSwapOnChain: waiting for worker)
  → success             (worker completes the bridge)
  → error               (any failure along the way)
Use the Check Payment Info endpoint to poll the order status after broadcasting and confirm when it reaches success.