Users - Saved Payment Methods
Base path: /api/v1/users/payment-methods
Used by: customer-booki-web-app · Role: customer
organizationId: From JWT token
Customers can save payment methods (via Stripe) for faster checkout on future bookings. All endpoints require customer authentication.
POST /api/v1/users/payment-methods/setup — Setup Payment Method
Auth: Protected (Authorization: Bearer <accessToken>) · customer
Description: Create a Stripe SetupIntent so the customer can add a new payment method via Stripe.js without being charged immediately. Returns a clientSecret for the frontend to complete the setup.
Request
POST /api/v1/users/payment-methods/setup
No request body required.
Response (201 Created)
{
"clientSecret": "seti_1NxABC2eZvKYlo2C1ABC1234_secret_...",
"setupIntentId": "seti_1NxABC2eZvKYlo2C1ABC1234"
}
The frontend uses clientSecret with stripe.confirmCardSetup() to securely save the card details.
Error Responses
401 Unauthorized — No valid token:
{
"statusCode": 401,
"message": "Access token is required to proceed."
}
cURL Example
curl -X POST http://localhost:4001/api/v1/users/payment-methods/setup \
-H "Content-Type: application/json" \
-H "Authorization: Bearer CUSTOMER_TOKEN"
GET /api/v1/users/payment-methods — List Payment Methods
Auth: Protected (Authorization: Bearer <accessToken>) · customer
Description: Retrieve all saved payment methods for the authenticated customer.
Request
GET /api/v1/users/payment-methods
Response (200 OK)
{
"items": [
{
"paymentMethodId": "pm_1NxABC2eZvKYlo2C1ABC1234",
"brand": "visa",
"last4": "4242",
"expMonth": 12,
"expYear": 2028,
"isDefault": true
},
{
"paymentMethodId": "pm_1NxDEF2eZvKYlo2C1DEF5678",
"brand": "mastercard",
"last4": "5100",
"expMonth": 8,
"expYear": 2027,
"isDefault": false
}
]
}
cURL Example
curl -X GET http://localhost:4001/api/v1/users/payment-methods \
-H "Authorization: Bearer CUSTOMER_TOKEN"
DELETE /api/v1/users/payment-methods/:paymentMethodId — Delete Payment Method
Auth: Protected (Authorization: Bearer <accessToken>) · customer
Description: Remove a saved payment method from the customer's account. This detaches it from Stripe.
Request
DELETE /api/v1/users/payment-methods/pm_1NxABC2eZvKYlo2C1ABC1234
Path Parameters:
paymentMethodId(string, required): Stripe payment method ID (pm_...)
Response (200 OK)
{
"message": "Payment method removed successfully."
}
Error Responses
404 Not Found — Payment method not found or does not belong to the user:
{
"statusCode": 404,
"message": "Payment method not found."
}
cURL Example
curl -X DELETE "http://localhost:4001/api/v1/users/payment-methods/pm_1NxABC2eZvKYlo2C1ABC1234" \
-H "Authorization: Bearer CUSTOMER_TOKEN"