Payment Methods
List and save payment methods for the authenticated customer
Payment Methods
The payment-method endpoints let a customer list and remove saved cards and direct-debit methods, 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-methodscurl "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
}
]
}| Field | Type | Description |
|---|---|---|
id | string | Stripe payment-method ID or Tiquo saved-card identity |
kind | string or omitted | card or direct_debit |
label | string or omitted | Display-safe payment-method label |
brand | string or omitted | Card brand |
last4 | string or omitted | Last four card or account digits |
expMonth | integer or omitted | Card expiry month |
expYear | integer or omitted | Card expiry year |
bankName | string or omitted | Bank name for supported direct-debit methods |
cardUseType | string or omitted | business or personal for cards |
isDefault | boolean | Whether this is the customer's default payment method |
Start a Setup
POST /payment-methods/setupThe 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_..."
}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.
Finish a Setup
After Stripe reports that the SetupIntent succeeded, send its ID to:
POST /payment-methods/confirm| Field | Type | Required | Description |
|---|---|---|---|
setupIntentId | string | Yes | SetupIntent created by /payment-methods/setup |
cardUseType | string | No | business or personal; cards default to personal |
setAsDefaultPaymentMethod | boolean | No | Make this method the default. The first saved method becomes the default automatically. |
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.
Remove a Payment Method
DELETE /payment-methodsSend the ID of the saved method in the JSON body.
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
| Status | Description |
|---|---|
400 | The payment operation could not be completed or setupIntentId is missing or invalid |
401 | Missing, invalid, or expired access token |
403 | No customer profile is linked to the authenticated account |
409 | The method could not be removed safely, is not owned by the customer, or is not supported by this endpoint |
500 | Internal server error |