Save a payment method with Wooshpay Checkout

This guide shows how to let Wooshpay’s hosted Checkout page collect and store a customer’s card so you can charge it later—no custom UI required.

1 . Prerequisites

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).

2 . Create a Checkout Session (setup mode)

POST： /v1/checkout/sessions/setup

{
  "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"
  }
}

Request parameters

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

response:

{
    "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"
}

Redirect the Customer

3 . Customer completes Checkout

Success: Wooshpay attaches the card to the customer and redirects to your success_url.

Cancel: Customer lands on cancel_url; no card is saved.

4 . Handle webhooks

Enable these events in the Dashboard and point them to your webhook endpoint:

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"
}

Persist (customer_id, payment_method_id) mapping for charge the card later

5 . Charge the card later

Create a PaymentIntent

POST /v1/payment_intents

{
  "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).

6 . Test the flow

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

Use your test secret key and point webhooks to your dev endpoint.

Quick reference

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`

Save a payment method with Wooshpay Checkout

1 . Prerequisites#

2 . Create a Checkout Session (setup mode)#

3 . Customer completes Checkout#

4 . Handle webhooks#