Introducing the Payment Method API

Released in v1.0.5

Calmony Pay v1.0.5 ships the Payment Method API — the foundation for storing and reusing card details across one-off charges and recurring subscriptions. Cards are tokenised via Cardstream so raw PAN data never touches your servers.

---

How It Works

1. Tokenise a card — Send raw card details to POST /v1/payment_methods. Cardstream processes the card and returns a secure token. Calmony Pay stores only the safe metadata alongside the token.
2. Attach to a customer — Associate the payment method with a customer record using POST /v1/payment_methods/:id/attach.
3. Set as default — A customer's defaultPaymentMethodId determines which card is charged automatically for subscription renewals.
4. Detach when needed — Remove a card from a customer at any time via POST /v1/payment_methods/:id/detach.

---

Key Details

• ID prefix: All payment method IDs use the pm_ prefix (e.g. pm_abc123), making them easy to identify in logs and API responses.
• Stored card metadata: cardLast4, cardBrand, cardExpMonth, cardExpYear, cardstreamTokenId.
• No raw card storage: Calmony Pay never stores full card numbers or CVV values. Cardstream holds the underlying token.

---

Endpoints at a Glance

Method	Path	Description
POST	/v1/payment_methods	Tokenise and create a payment method
GET	/v1/payment_methods/:id	Retrieve a payment method
GET	/v1/payment_methods	List payment methods
POST	/v1/payment_methods/:id/attach	Attach to a customer
POST	/v1/payment_methods/:id/detach	Detach from a customer

---

Quick Start

1. Tokenise a Card

POST /v1/payment_methods
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "type": "card",
  "card": {
    "number": "4111111111111111",
    "exp_month": 12,
    "exp_year": 2027,
    "cvc": "123"
  }
}

Response

{
  "id": "pm_abc123",
  "object": "payment_method",
  "type": "card",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "exp_month": 12,
    "exp_year": 2027
  },
  "customer": null,
  "created": 1719000000
}

2. Attach to a Customer

POST /v1/payment_methods/pm_abc123/attach
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "customer": "cus_xyz789"
}

3. Set as Default for Subscriptions

Update the customer record to point defaultPaymentMethodId at the newly attached method so it is used for all future subscription charges:

POST /v1/customers/cus_xyz789
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "default_payment_method": "pm_abc123"
}

4. Detach a Card

POST /v1/payment_methods/pm_abc123/detach
Authorization: Bearer <api_key>

---

Stripe Compatibility Note

The Payment Method API follows Stripe's naming conventions and object shapes wherever possible, making it straightforward to adapt existing Stripe integrations to Calmony Pay with minimal changes.