Transactions

Transactions are incoming Bitcoin transactions paid for invoices or any transactions deposited to any of wallets addresses.

TIP

Do not use txid field (blockchain txid) as unique identificator, but use ID provided by Uniwire instead as it is possible to make multiple payments to same address within same transaction.

List Transactions

This endpoint retrieves all transactions. Endpoint uses pagination and returns 25 transactions per page. Transactions are sorted by creation time in descending order.

HTTP Request

GET /v1/transactions/

Query Parameters

Parameter	Default	Description
p	None	Page number.
txid	None	Filter transactions by txid.
address	None	Filter transactions by receiving address.
invoice_id	None	Filter transactions by Invoice ID.
profile_id	None	Filter transactions by Profile ID.

python

transactions = uniwire_api_request('/v1/transactions/')

javascript

uniwire_api_request('/v1/transactions/').then(function(response) {
  console.log(response);
}).catch(function(error) {
  console.log(error);
});

The above command returns JSON structured like this:

{
  "pagination": {
    "num_pages": 1,
    "count": 12,
    "page": 1,
    "next_page": null,
    "previous_page": null,
    "per_page": 25
  },
  "result": [
    {
      "id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
      "kind": "BTC",
      "txid": "7f96054005c8aab5101d48211cb23070b6a9d9b7ea25b3422de2c109eb57fad9",
      "invoice": {
        "id": "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa",
        "kind": "BTC",
        "created_at": "2019-02-07T22:13:15.093624+00:00",
        "profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
        "address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
        "lightning": null,
        "network": "mainnet",
        "amount": {
          "requested": {
            "amount": "10.00",
            "currency": "USD"
          },
          "invoiced": {
            "amount": "0.00293528",
            "currency": "BTC"
          }
        },
        "custom_fee": null,
        "min_confirmations": null,
        "zero_conf_enabled": null,
        "notes": null,
        "passthrough": "{\"test\":123}"
      },
      "amount": {
        "paid": {
          "amount": "0.00293528",
          "currency": "BTC",
          "quotes": {
            "USD": "10.00"
          }
        }
      },
      "currency_rates": {
        "BTC": {
          "USD": "3406.83001280968"
        }
      },
      "created_at": "2019-02-07T22:13:28.681005+00:00",
      "executed_at": "2019-02-07T22:21:59+00:00",
      "confirmed_at": "2019-02-07T23:09:31.983230+00:00",
      "confirmations": 6,
      "status": "complete",
      "zero_conf_status": null,
      "network": "mainnet",
      "risk_level": "low",
      "risk_data": {},
      "sub_kind": null
    }
  ]
}

Get Transaction

This endpoint retrieves a specific transaction.

HTTP Request

GET /v1/transactions/<ID>/

URL Parameters

Parameter	Description
ID	The ID of the transaction to retrieve.

python

transaction = uniwire_api_request('/v1/transactions/<ID>/')

javascript

uniwire_api_request('/v1/transactions/<ID>/').then(function(response) {
  console.log(response);
}).catch(function(error) {
  console.log(error);
});

The above command returns JSON structured like this:

{
  "result": {
    "id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
    "kind": "BTC",
    "txid": "7f96054005c8aab5101d48211cb23070b6a9d9b7ea25b3422de2c109eb57fad9",
    "invoice": {
      "id": "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa",
      "kind": "BTC",
      "created_at": "2019-02-07T22:13:15.093624+00:00",
      "profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
      "address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
      "lightning": null,
      "network": "mainnet",
      "amount": {
        "requested": {
          "amount": "10.00",
          "currency": "USD"
        },
        "invoiced": {
          "amount": "0.00293528",
          "currency": "BTC"
        }
      },
      "custom_fee": null,
      "min_confirmations": null,
      "zero_conf_enabled": null,
      "notes": null,
      "passthrough": "{\"test\":123}"
    },
    "amount": {
      "paid": {
        "amount": "0.00293528",
        "currency": "BTC",
        "quotes": {
          "USD": "10.00"
        }
      }
    },
    "currency_rates": {
      "BTC": {
        "USD": "3406.83001280968"
      }
    },
    "created_at": "2019-02-07T22:13:28.681005+00:00",
    "executed_at": "2019-02-07T22:21:59+00:00",
    "confirmed_at": "2019-02-07T23:09:31.983230+00:00",
    "confirmations": 6,
    "status": "complete",
    "zero_conf_status": null,
    "network": "mainnet",
    "risk_level": "low",
    "risk_data": {},
    "sub_kind": null
  }
}

Get Transaction Risk

This endpoint retrieves risk data for a specific transaction.

HTTP Request

GET /v1/transactions/<ID>/risk/

URL Parameters

Parameter	Description
ID	The ID of the transaction.

python

transaction = uniwire_api_request('/v1/transactions/<ID>/risk/')

javascript

uniwire_api_request('/v1/transactions/<ID>/risk/').then(function(response) {
  console.log(response);
}).catch(function(error) {
  console.log(error);
});

The above command returns JSON structured like this:

{
  "result": {
    "id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
    "kind": "BTC",
    "risk_data": {}
  }
}

Retrieve Confirmations

This endpoint returns confirmations for specified transaction ID(s).

HTTP Request

POST /v1/transactions/confirmations/

Payload Parameters

Parameter	Description	Required
id	Array/list of transaction ID.	Yes

python

import json

payload = {
    "id": [
        "9094fefe-3ac2-49b3-99ec-9b719331316c",
        "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa"
    ]
}
confirmations = uniwire_api_request('/v1/transactions/confirmations/', payload, 'POST')
print(json.dumps(confirmations, indent=2))

javascript

var payload = {
  "id": [
    "9094fefe-3ac2-49b3-99ec-9b719331316c",
    "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa"
  ]
}

uniwire_api_request('/v1/transactions/confirmations/', payload, 'POST').then(function(response) {
  console.log(response);
}).catch(function(error) {
  console.log(error);
});

The above command returns JSON structured like this:

{
  "result": [
    {
      "id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
      "confirmations": 2
    },
    {
      "id": "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa",
      "confirmations": 7
    }
  ]
}

Resend Transaction Callback

This endpoint manually resends the last callback for a specific transaction. Useful when the original callback failed or needs to be resent.

HTTP Request

POST /v1/transactions/<ID>/resend-callback/

URL Parameters

Parameter	Description
ID	The ID of the transaction to resend callback for.

Response Fields

Parameter	Description
status	Callback status: success, error, or pending
message	Human-readable message describing the result
error	Error type if status is error (e.g., no_profile_or_callback_url, callback_failed, exception_occurred)

python

callback_result = uniwire_api_request('/v1/transactions/<ID>/resend-callback/', {}, 'POST')

javascript

uniwire_api_request('/v1/transactions/<ID>/resend-callback/', {}, 'POST').then(function(response) {
  console.log(response);
}).catch(function(error) {
  console.log(error);
});

The above command returns JSON structured like this:

{
  "status": "success",
  "message": "Callback sent successfully",
  "callback_response": {
    "status_code": 200,
    "url": "https://example.com/callback"
  }
}

Custom Fees

With "Custom Fees" feature merchants can charge extra fee on top of every invoice. If "fee_amount" field is specified while creating invoice, extra fee will be added to invoiced amount and later on deducted from "paid" field. In such case response will also have extra "paid_total" key with an actual transaction values and relevant quotes.

Example response if custom fees are applied.

{
  "result": {
    "id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
    "kind": "BTC",
    "txid": "7f96054005c8aab5101d48211cb23070b6a9d9b7ea25b3422de2c109eb57fad9",
    "invoice": {
      "id": "cab4f4ff-6654-46c7-b22e-7d31da1eebcd",
      "kind": "BTC",
      "created_at": "2019-02-08T12:36:21.130435+00:00",
      "profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
      "address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
      "lightning": null,
      "network": "mainnet",
      "amount": {
        "requested": {
          "amount": "100.00",
          "currency": "USD"
        },
        "invoiced": {
          "amount": "0.02967564",
          "currency": "BTC"
        }
      },
      "custom_fee": {
        "amount": "0.00050000",
        "currency": "BTC"
      },
      "min_confirmations": null,
      "notes": null,
      "passthrough": "{\"user_id\": 123}"
    },
    "amount": {
      "paid": {
        "amount": "0.02917564",
        "currency": "BTC",
        "quotes": {
          "USD": "100.00"
        }
      },
      "paid_total": {
        "amount": "0.02967564",
        "currency": "BTC",
        "quotes": {
          "USD": "101.71"
        }
      }
    },
    "currency_rates": {
      "BTC": {
        "USD": "3406.83001280968"
      }
    },
    "created_at": "2019-02-08T12:36:21.200127+00:00",
    "executed_at": null,
    "confirmed_at": null,
    "confirmations": 6,
    "status": "complete",
    "zero_conf_status": null,
    "network": "testnet",
    "risk_level": "low",
    "risk_data": {},
    "sub_kind": null
  }
}

Transaction Statuses

Status	Description
pending	Transaction is broadcast on the network (0 confirmations).
confirmed	Transaction is included in the first block (1 confirmation).
complete	Transaction has 6+ confirmations.
unconfirmed	Transaction hasn't been confirmed for more than 24 hours. If it get's confirmed later, status will be updated to "Confirmed".
failed	Transaction failed on network (might be that due to low fees, etc.)
quarantined	Transaction was quarantined by risk analysis or manually.
replaced	Transaction was replaced by another transaction and will not get confirmed.

Transaction Callbacks

Callbacks provide same exact response format as in Get Transaction API endpoint in result field plus three extra fields specified in Callbacks Documentation.

You can view history of callbacks (if any) in Uniwire in Transaction detail view.

Transaction Callback Statuses

Status	Description
transaction_pending	Transaction was found on mempool, but not yet confirmed (0 confirmations).
transaction_confirmed	Transaction was confirmed (at least 1 confirmation or based on minimum confirmation settings).
transaction_complete	Transaction has maximum confirmations needed to consider it completely final.
transaction_replaced	Special callback if transaction has been replaced by another transaction.
transaction_failed	Transaction has failed on blockchain.
transaction_quarantined	Transaction was quarantined by risk analysis or manually.
transaction_zero_conf_confirmed	Special callback if transaction has been confirmed even with 0 confirmations. In such case "zero_conf_status=confirmed" field will be present.

0-Confirmation Statuses

If zero confirmation feature for invoice is enabled, it is possible to verify its validity even with 0 confirmations, in such case zero_conf_status field will be present in response. Possible zero_conf_status values:

Status	Description
null	Transaction verification with 0 confirmations has not been done.
confirmed	Transaction with 0 confirmations is confirmed and can be safely treated as confirmed.
unconfirmed	Transaction with 0 confirmations is confirmed is not safe to be treated as confirmed therefore it should await blockchain confirmations.
unknown	Transaction verification with 0 confirmations has failed and status is unknown therefore it should await blockchain confirmations.

If transaction with 0 confirmations is confirmed using 0-conf verification special transaction_zero_conf_confirmed callback will be sent.

0-confirmation status can be enabled globally in Profiles in Dashboard UI or by specifying zero_conf_enabled=true while creating invoice in API.