Item | Notes |
---|---|
Secret key | Use your server-side key to create the session. |
Customer ID | Reuse an existing customer or create one with POST /v1/customers (email recommended). |
{
"cancel_url": "https://example.com/billing/cancel",
"success_url": "https://example.com/billing/success",
"payment_method_types": ["card"],
"customer": "cus_1953770230215868416",
"metadata": {
"order_id":"order123",
"merchant_user_id":"123"
}
}
Field | Required | Description |
---|---|---|
cancel_url | ✔ | Where to bring the shopper if they abort the flow. |
success_url | ✔ | Where to bring the shopper after the card is saved. |
payment_method_types | ✔ | Must be ["card"] for save-card. |
customer | ✔ | Attach the new PaymentMethod to this customer. (If omitted, Wooshpay will create a customer and return its ID.) |
metadata | – | Arbitrary key/value pairs copied to webhooks |
{
"id": "cs_1953770262348431360",
"object": "checkout.session",
"created": 1754650104000,
"livemode": false,
"customer": "cus_1953770230215868416",
"metadata": {
"merchant_user_id": "123",
"orderID": "order123"
},
"mode": "setup",
"status": "open",
"url": "https://checkout.XXXXXX",
"customer_details": {
"id": "cus_1953770230215868416",
"object": "customer",
"created": 1754650097000,
"livemode": true,
"address": {
"country": "CN"
},
"email": "test_prod@gmail.com",
"name": "test_prod"
},
"expires_at": 1754736504499,
"live_mode": true,
"payment_method_types": [
"card"
],
"setup_intent": "seti_1953770262453288960",
"success_url": "http://yourwebsite.com",
"cancel_url": "http://yourwebsite.com"
}
success_url
.cancel_url
; no card is saved.Event | Purpose | Typical action |
---|---|---|
setup_intent.created | Session starts | Optional logging / analytics |
setup_intent.succeeded | Saved successfully. | Persist (customer_id, payment_method_id) mapping |
setup_intent.succeeded
Payload demo:{
"id": "evt_1953045921369423872",
"object": "event",
"created": 1754477408000,
"livemode": false,
"data": {
"object": {
"id": "seti_1953034584329289728",
"object": "setup_intent",
"created": 1754474705000,
"livemode": false,
"status": "succeeded",
"metadata": {
"a": "1",
"b": "2"
},
"customer": "cus_1952983283688013824",
"client_secret": "seti_1953034584329289728_secret_QNWoBNDOZpW4bomjsAgC8DF1",
"payment_method_types": [
"card"
],
"payment_method_options": {
"card": {
"request_three_d_secure": "auto",
"setup_future_usage": "off_session"
}
},
"return_url": "https://checkouttest.wooshpay.com/setup/cs_test_1953034583884693504?key=cGtfdGVzdF9OVEUyTWpZeE1ETTNOekExT1RVek16SXdPVFl4T25SRWFEUjRhbWxhVUcxM1RFeG1aMXBGUVdwd2RGVlRaakUyTnpZMU1qZ3pNamswT1RN",
"payment_method": "pm_1953045864444329984"
}
},
"type": "setup_intent.succeeded"
}
(customer_id, payment_method_id)
mapping for charge the card later{
"amount": 2500,
"currency": "USD",
"confirm": true,
"off_session": true, // true if no user present
"customer": "cus_1953770230215868416",
"payment_method": "pm_123123123",
"return_url": "https://example.com/pay/complete"
}
Key point | Value |
---|---|
customer | ID from Step 1. |
payment_method | Saved card’s ID from webhook or listing API. |
off_session | true to attempt an off-session charge (recurring / unsupervised). |
Action | Test card number | Notes |
---|---|---|
Successful save + charge | 4111 4111 41111 4111 | Any future date, any CVC |
3-D Secure required | 4462030000000000 | Checkout will prompt for 3DS challenge |
Task | API |
---|---|
Create session | POST /v1/checkout/sessions/setup |
Listen to events | setup_intent.created setup_intent.succeeded |
List cards | GET /v1/customers/{id}/payment_methods |
Charge card | POST /v1/payment_intents |