Payment Methods
Use the payment methods API to save, retrieve, and manage payment methods for your customers.
Create a Payment Method
POST /payment_methods
curl https://sandbox.perfectpay.ai/payment_methods \
-X POST \
-H "api-key: YOUR_SECRET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"payment_method": "card",
"payment_method_type": "credit",
"payment_method_data": {
"card": {
"card_number": "4242424242424242",
"card_exp_month": "10",
"card_exp_year": "25",
"card_cvc": "123",
"card_holder_name": "Jane Doe"
}
},
"customer_id": "cus_abc123"
}'
Response excerpt:
{
"payment_method_id": "pm_abc123",
"payment_method": "card",
"payment_method_type": "credit",
"customer_id": "cus_abc123"
}
Use raw card data in sandbox or controlled PCI environments only. For production browser flows, use the Web SDK and its
paymentMethodsManagementElements(...)method.
Retrieve a Payment Method
GET /payment_methods/{payment_method_id}
curl https://sandbox.perfectpay.ai/payment_methods/pm_abc123 \
-H "api-key: YOUR_SECRET_API_KEY"
Returns the full payment method object including masked card details and metadata.
Update a Payment Method
POST /payment_methods/{payment_method_id}/update
curl https://sandbox.perfectpay.ai/payment_methods/pm_abc123/update \
-X POST \
-H "api-key: YOUR_SECRET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"payment_method_data": {
"card": {
"card_exp_month": "12",
"card_exp_year": "27"
}
}
}'
Delete a Payment Method
DELETE /payment_methods/{payment_method_id}
curl https://sandbox.perfectpay.ai/payment_methods/pm_abc123 \
-X DELETE \
-H "api-key: YOUR_SECRET_API_KEY"
Permanently removes the payment method. This cannot be undone.
List Customer Payment Methods
GET /customers/{customer_id}/payment_methods
curl https://sandbox.perfectpay.ai/customers/cus_abc123/payment_methods \
-H "api-key: YOUR_SECRET_API_KEY"
Returns all saved payment methods for the given customer. Use this to build a saved-method picker in your checkout flow or account management page.
SDK Hook
The hosted Web SDK also exposes initPaymentSession(...) and paymentMethodsManagementElements(...) so you can manage saved methods without building this flow by hand.