Bind transaction to contract request
Associates a payment transaction with an existing contract request,
linking the contract signing event to the corresponding financial
transaction; also re-evaluates whether the request can now advance past a
payment gate. Returns 404 if the request or transaction is not found.
Returns 400 if the request has already reached a terminal status
(completed/canceled/declined/expired), or if the request or the
transaction is already bound to a different counterpart.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Links an existing payment transaction to a contract request, associating the contract signing event with the financial transaction that backs it. The binding is recorded on both records, and the request is advanced if the binding unblocks the next stage. Returns the updated contract request.
Authentication & access
- Requires a client API token:
Authorization: Bearer <token>. - API credentials need the
contracts.requests.bind_transactionpermission. Dashboard users need the OWNER or OPERATIONS role, or a custom role that includes this permission. - Contract signing must be enabled for the client. If it is disabled the request returns
403.
Path parameters
| Parameter | Description |
|---|---|
request_id | ID of the contract request to bind the transaction to. Must belong to your client. |
Request body
| Field | Type | Description |
|---|---|---|
transaction_id | string (required) | ID of the payment transaction to link to this request. Must belong to your client. |
Binding rules
- The contract request must not be in a terminal state. Requests that are completed, canceled, declined, or expired are rejected (
400). - If the request is already bound to a different transaction, the request is rejected (
400). Re-binding the request to the same transaction it already holds is allowed and is idempotent. - One payment funds one live contract. If the transaction is already associated with a different contract request, it is rejected (
400) unless that request endedcanceled,declinedorexpired; such a released payment can be bound to this request instead. - On success, the transaction is pointed at this contract request, the request is stamped with the transaction ID, and the request is advanced.
- If the request is waiting at a payment gate, binding moves it from
awaiting_transaction_bindingtoawaiting_transactionuntil the payment succeeds, or straight on to the next signers if the payment has already succeeded.
Response
200 - Returns the updated ContractRequestResponse, including the now-populated transaction_id and the request's current status, stage, and participant state.
Error responses
| Status | When |
|---|---|
400 | Contract request is in a terminal state; request is already bound to a different transaction; transaction is already associated with a different contract request that is still live or completed |
403 | Contract signing is disabled for the client |
404 | Contract request not found under this client; transaction not found under this client |
422 | Request body failed validation (e.g. missing transaction_id) |
502 | Advancing the request needed the signing service (for example to auto-sign the next signer) and it returned an error |
503 | The signing service is temporarily unavailable or not configured |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.