Skip to content

Public API — v4.5.0

Type: Minor Release  ·  Previous version: v4.4.0

✏️ 1 Modified

✏️ Modified Endpoints

POST /onchain-preauth/{invoiceId}/settle

Tag: Onchain Preauthorization
Summary: Settle preauthorization

Executes a settlement against an existing preauthorization by transferring tokens from the sender to the receiver.

  The settlement amount:
    Can be partial or full
    Finalizes the preauthorization upon success

  Key Notes
    Only AUTHORIZED preauthorizations can be settled
    Settlement triggers an on-chain transaction
    Once settled, the preauthorization status becomes COMPLETED

Updated Response Codes

409

- Settlement conflicts:  - Pre-authorization expired - Invalid settlement state: REJECTED - Settlement exceeds authorized amount with allowed tip - Amount must be greater than zero

Settlement conflicts:

  • Pre-authorization expired
  • Invalid settlement state: FAILED
  • Settlement exceeds authorized amount with allowed tip
  • Amount must be greater than zero

Current Request Example

{
  "amount": "120.50"
}

Response Examples

Code Description
200 Settlement successful
400 Bad Request errors:
401 Authentication errors:
403 Authorization errors:
409 Settlement conflicts:
500 Internal errors:

200 — Settlement successful

{
  "transactionId": "b3f9c2a1-8d4e-4a5b-9c12-123456789abc",
  "invoiceId": "INV-2026-0001",
  "authorizedAmount": "150.75",
  "settledAmount": "120.50",
  "contractAddress": "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2",
  "status": "COMPLETED",
  "transactionHash": "0xabc123def456..."
}

400 — Bad Request errors:

  • Errors occurred while initializing transaction on chain
{
  "errors": [
    {
      "type": "onchain",
      "message": "Errors occurred while initializing transaction on chain"
    }
  ]
}

401 — Authentication errors:

  • Access Denied → Missing or invalid authentication
{
  "errors": [
    {
      "type": "Access Denied",
      "message": "Access Denied"
    }
  ]
}

403 — Authorization errors:

  • Access Denied → Access denied for tenant/user
{
  "errors": [
    {
      "type": "Access Denied",
      "message": "Access Denied"
    }
  ]
}

409 — Settlement conflicts:

  • Pre-authorization expired
  • Invalid settlement state: FAILED
  • Settlement exceeds authorized amount with allowed tip
  • Amount must be greater than zero
{
  "errors": [
    {
      "type": "onchain",
      "message": "Amount must be greater than zero"
    }
  ]
}

500 — Internal errors:

  • Settlement failed
{
  "errors": [
    {
      "type": "onchain",
      "message": "Settlement failed"
    }
  ]
}