Skip to main content
Recurring payments auto-release a fixed amount at a fixed interval (DAILY, WEEKLY, BIWEEKLY, MONTHLY, YEARLY). Funding is computed as up to 12 periods upfront (or fewer if the configured endDate occurs sooner), and the recipient claims each period as it becomes due.

​
List Payments

GET /api/payments?sender={address}
GET /api/payments?recipient={address}
GET /api/payments?sender={address}&recipient={address}

​
Get Payment

GET /api/payments/:id
Returns the payment record plus its execution history from payment_executions.

​
Create Payment

POST /api/payments/create
Deploys the RecurringPaymentCovenant on-chain. Stores status: PENDING until funded. Body 
{
  "sender": "bchtest:qr...",
  "recipient": "bchtest:qs...",
  "recipientName": "Alice",
  "tokenType": "BCH",
  "amountPerPeriod": 0.1,
  "interval": "MONTHLY",
  "startDate": 1700000000,
  "endDate": 1762000000,
  "cancelable": true,
  "pausable": true,
  "vaultId": "optional-uuid"
}
Valid values for interval: DAILY, WEEKLY, BIWEEKLY, MONTHLY, YEARLY. Response 
{
  "success": true,
  "payment": { "id": "...", "status": "PENDING", "payment_id": "#FG-PAY-001", ... },
  "deployment": {
    "contractAddress": "bchtest:p...",
    "paymentId": "#FG-PAY-001",
    "fundingRequired": true,
    "cancelable": true
  }
}

​
Get Funding Info

GET /api/payments/:id/funding-info
Returns the unsigned wcTransaction to fund 12 intervals upfront.

​
Confirm Funding

POST /api/payments/:id/confirm-funding

{ "txHash": "hex64" }
Verifies on-chain and activates the payment contract.

​
Claim

POST /api/payments/:id/claim

{ "recipientAddress": "bchtest:qs..." }
Builds the claim wcTransaction. Computes how many intervals are claimable since nextPaymentDate. Only the registered recipient can claim. Response 
{
  "success": true,
  "claimableAmount": 0.3,
  "intervalsClaimable": 3,
  "wcTransaction": { ... }
}

​
Confirm Claim

POST /api/payments/:id/confirm-claim

{
  "claimedAmount": 0.3,
  "txHash": "hex64",
  "intervalsClaimed": 3
}
Updates total_paid, payment_count, and next_payment_date. Records execution in payment_executions.

​
Pause

POST /api/payments/:id/pause
x-user-address: bchtest:q...
Sender-only. Returns wcTransaction to pause. Confirm with POST /api/payments/:id/confirm-pause.

​
Resume

POST /api/payments/:id/resume
x-user-address: bchtest:q...
Sender-only. Resumes from PAUSED. Confirm with POST /api/payments/:id/confirm-resume. Updates next_payment_date to now + intervalSeconds.

​
Cancel

POST /api/payments/:id/cancel
x-user-address: bchtest:q...
Sender-only. Returns wcTransaction to cancel — unfunded periods are returned to sender. Confirm with POST /api/payments/:id/confirm-cancel.