Recurring payments

Execute one recurring charge

Collect one billing period. Call it from your own renewal job - P2Flux schedules nothing.

Safe to retry. The contract allows one charge per period, so a repeat call after a timeout or a crash returns ALREADY_CHARGED rather than charging again. Treat that as success.

CONFIRMING is not a failure. The transaction is on chain and not yet settled: leave the period open, change nothing, and ask again in a few seconds about the same transaction. Its action is WAIT, and it is the one result that must never be shown to a customer as an error - they have paid.

Every other outcome carries an action telling you what to do; the retry SCHEDULE (an hour, a day, a dunning email) is your business policy, not ours.

post/v1/charges

Request

  • Base URL: https://api.p2flux.com
  • URL: https://api.p2flux.com/v1/charges
  • Auth: none required

Request body

subscriptionstring required

A signed P2Flux capability: payment intent (p2f1.), setup token (p2setup2.), subscription capability (p2s2.), cancel token (p2cancel1.) or refund token (p2refund1.). Opaque to the caller and unforgeable - the signature is what authorises the call. Treat it as a bearer secret: keep it server-side, never in a URL query or a log.

Response

The charge outcome.

status'CHARGED' | 'ALREADY_CHARGED' | 'CONFIRMING'
okboolean

True for CHARGED and ALREADY_CHARGED - both mean the period is paid.

already_paidboolean
action'SUCCESS' | 'WAIT' | 'RETRY_LATER' | 'CUSTOMER_ACTION_REQUIRED' | 'STOP_SUBSCRIPTION' | 'INVALID_REQUEST'

What to do about a result.

  • SUCCESS - done, nothing owed.
  • WAIT - the money may already have moved. The transaction exists and has not settled to the required depth. Ask again about the SAME transaction; never start another one. This is not a failure, and showing the customer an error here tells someone who has paid that they have not.
  • RETRY_LATER - nothing happened; the identical call is safe to repeat on your own schedule.
  • CUSTOMER_ACTION_REQUIRED - the customer must top up or re-approve.
  • STOP_SUBSCRIPTION - terminal; stop charging this subscription.
  • INVALID_REQUEST - permanent. Retrying returns the same answer forever; fix the request.
tx_hashstring

A 32-byte hex value, lowercase. Transaction hashes and references.

subscription_idstring

A 32-byte hex value, lowercase. Transaction hashes and references.

amountstring

A USDC amount as a decimal string, up to 6 decimal places. Never a JSON number: binary floating point cannot represent most decimal prices exactly, and this is money.

period_indexinteger
next_period_atstring

Example response

{
  "tx_hash": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
  "subscription_id": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
  "amount": "10.00"
}

Changes

No recorded changes to this operation across all 1 revision of this API.