Introducing the Payment Intent API

Version 1.0.6 ships the Payment Intent API — the core building block for collecting one-off card payments through Calmony Pay. It follows a Stripe-compatible flow: create an intent, then confirm it to trigger the charge via Cardstream.

Overview

A payment intent represents a single attempt to collect a card payment. It tracks the full lifecycle of that attempt — from the moment the payment is initiated through to a final succeeded or failed outcome.

Endpoints

Create a Payment Intent

POST /v1/payment_intents

Creates a new payment intent in the requires_confirmation state (after a payment method has been associated).

Request body

Field	Type	Required	Description
`amount`	integer	✓	Amount to charge, in pence (e.g. `1999` = £19.99)
`currency`	string	✓	Must be `GBP`
`customerId`	string	✓	ID of the customer being charged
`paymentMethodId`	string	✓	ID of the stored payment method (card token) to use

Example request

{
  "amount": 2500,
  "currency": "GBP",
  "customerId": "cus_abc123",
  "paymentMethodId": "pm_xyz789"
}

Example response

{
  "id": "pi_a1b2c3d4",
  "object": "payment_intent",
  "amount": 2500,
  "currency": "GBP",
  "customerId": "cus_abc123",
  "paymentMethodId": "pm_xyz789",
  "status": "requires_confirmation"
}

Confirm a Payment Intent

POST /v1/payment_intents/:id/confirm

Confirms the payment intent and triggers the card charge via the Cardstream Direct API using the stored payment method token. The intent status transitions through processing before settling at succeeded or failed.

On success, the cardstreamTransactionId is stored against the record for reconciliation.

Example response (succeeded)

{
  "id": "pi_a1b2c3d4",
  "object": "payment_intent",
  "amount": 2500,
  "currency": "GBP",
  "status": "succeeded",
  "cardstreamTransactionId": "cs_txn_00112233"
}

Retrieve a Payment Intent

GET /v1/payment_intents/:id

Returns a single payment intent by its pi_-prefixed ID.

List Payment Intents

GET /v1/payment_intents

Returns a list of all payment intents.

Payment Intent Status Lifecycle

Every payment intent moves through the following statuses in order:

requires_payment_method
        ↓
requires_confirmation
        ↓
    processing
        ↓
 succeeded  /  failed

Status	Description
`requires_payment_method`	Intent created; no payment method attached yet.
`requires_confirmation`	Payment method is attached; waiting to be confirmed.
`processing`	Confirmation received; charge is in-flight with Cardstream.
`succeeded`	Cardstream accepted the charge. Funds will settle to the Calmony Griffin account.
`failed`	Cardstream declined or errored. The `cardstreamTransactionId` may still be stored for reference.

ID Format

All payment intent IDs are prefixed with pi_, for example: pi_a1b2c3d4e5f6.

Notes

Amounts are always in pence. There is no decimal — pass 500 for £5.00.
Only GBP is supported in this release.
The cardstreamTransactionId is populated after a confirm call completes (whether succeeded or failed) and can be used to cross-reference transactions in the Cardstream dashboard.