Payment Methods

The payment-method endpoints let a customer list and remove saved cards and direct-debit methods, change the checkout default, create a Stripe SetupIntent, and persist the method after Stripe confirms it. Every operation requires a linked customer profile.

These responses use top-level fields rather than the usual Customer API data envelope.

List payment methods

GET /payment-methods

curl "https://edge.tiquo.app/api/client/v1/payment-methods" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

{
  "success": true,
  "paymentMethods": [
    {
      "id": "pm_123",
      "kind": "card",
      "label": "Visa ending in 4242",
      "brand": "visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2029,
      "cardUseType": "personal",
      "isDefault": true
    }
  ]
}

Start a setup

POST /payment-methods/setup

The optional paymentMethodTypes array accepts card and direct_debit. When it is omitted or contains no supported value, the endpoint starts a card-only setup.

curl -X POST "https://edge.tiquo.app/api/client/v1/payment-methods/setup" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{"paymentMethodTypes":["card"]}'

{
  "success": true,
  "setupIntentId": "seti_123",
  "clientSecret": "seti_123_secret_...",
  "currency": "gbp"
}

Use the clientSecret with Stripe's client SDK to collect and confirm the payment details. Tiquo does not receive raw card or bank-account details.

currency is the organisation's lowercase currency code: its default currency, or else its default Stripe account's currency. Pass it to Stripe Elements in setup mode so Apple Pay and Google Pay show the right currency. It is omitted when neither is known.

On a website, the DOM Package and Hosted Package card form embeds run this setup for you inside a Tiquo iframe.

Finish a setup

After Stripe reports that the SetupIntent succeeded, send its ID to:

POST /payment-methods/confirm

curl -X POST "https://edge.tiquo.app/api/client/v1/payment-methods/confirm" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "setupIntentId": "seti_123",
    "cardUseType": "personal",
    "setAsDefaultPaymentMethod": true
  }'

{
  "success": true,
  "paymentMethod": {
    "id": "pm_123",
    "kind": "card",
    "label": "Visa ending in 4242",
    "brand": "visa",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "cardUseType": "personal",
    "isDefault": true
  }
}

The endpoint rejects a SetupIntent that is incomplete, belongs to another customer, or was not created by this customer payment-method flow.

Change the default payment method

PATCH /payment-methods

Send the Stripe ID of a supported saved payment method belonging to the customer. This changes the default used at checkout while preserving the payment methods used by active memberships.

curl -X PATCH "https://edge.tiquo.app/api/client/v1/payment-methods" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{"paymentMethodId":"pm_123"}'

{
  "success": true,
  "preservedMembershipCount": 2
}

preservedMembershipCount reports how many active memberships had their existing payment method explicitly preserved. An unsupported method, a method owned by another customer, or a change that cannot be completed returns 409.

To replace the card for a failed membership payment or let another person supply a membership payment method, use Membership Payments.

Remove a payment method

DELETE /payment-methods

Send the Stripe payment-method ID (pm_…) in the JSON body. PATCH and DELETE require paymentMethodId to match ^pm_[A-Za-z0-9]+$ and accept JSON bodies up to 8,192 bytes.

curl -X DELETE "https://edge.tiquo.app/api/client/v1/payment-methods" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{"paymentMethodId":"pm_123"}'

{
  "success": true,
  "replacementPaymentMethodId": "pm_456"
}

replacementPaymentMethodId is returned when another saved method replaces the removed method as the default for an active membership or the Stripe customer.

Tiquo will not remove the customer's last saved payment method. If the method is used by an active membership, another eligible method must be available first. The active membership is moved to that replacement before the original method is detached. A method that belongs to another customer cannot be removed.

Errors