WooshPay OpenAPI
Product DocumentAPI ReferenceJS SDK ReferenceSaaS Platform Integration
Product DocumentAPI ReferenceJS SDK ReferenceSaaS Platform Integration
Back to WooshPay Website
  1. More payment scenarios
  • Online payments
    • Quick Start
    • Integration overview
    • Wooshpay JS SDK
    • Wooshpay Checkout
    • Wooshpay Direct API
    • Payment Link
    • Authorize and capture
    • Build subscriptions integration
    • Testing cards
  • After the payment
    • Webhook
    • Check the webhook signatures
    • 校验webhook签名
  • Add more payment methods
    • Supported payment method
    • Cards
    • Wallets
      • Alipay
      • Alipay HK
      • Apple Pay
      • Google Pay
      • Wechat Pay
      • 微信支付
      • Kakao Pay
      • DANA
      • Boost
      • Grabpay
      • Mcash
      • Touch'n Go
      • ShopeePay
      • UnionPay
      • 9Pay
      • OVO
      • GCash
      • TrueMoney
    • Bank redirects
      • Bancontact
      • BPI
      • Trustly
      • EPS
      • Giropay
      • iDEAL
      • Przelewy24
      • FPX
    • Buy Now Pay Later
      • Klarna
    • Bank Debits
      • Sepa Direct Debit
    • Bank Transfer
      • Bank Transfer in Europe
      • Bank Transfer in United Kingdom
      • Bank Transfer in Indonesia
      • Bank Transfer in Nigeria
      • Bank Transfer in South Africa
    • QR Payments
      • QRIS
      • PromptPay
    • Real-time payments
      • PIX
      • PayNow
      • UPI
      • SPEI
    • Mobile Money
      • Mobile Money - Multi-Country Integration Guide
  • More payment scenarios
    • Set up future payments
    • Save payment method during payment
    • Save Card with Wooshpay Checkout
  • SaaS platform integration
    • Shopify Plugin
    • WooCommerce
    • Shoplazza 店匠
    • Shopastro 星盘
    • Shopline Plugin
    • Sage Connection
  • Payouts
    • Overview
    • Cameroon
    • Europe
    • Ghana
    • Kenya
    • Nigeria
    • Rwanda
    • South Africa
    • Tanzania
    • Uganda
    • United Kindom
    • United States of America
    • Monitor Your Payout Results
  • Resources
    • Supported currencies
  1. More payment scenarios

Save Card 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#

ItemNotes
Secret keyUse your server-side key to create the session.
Customer IDReuse 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
FieldRequiredDescription
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
下载.png

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:
EventPurposeTypical action
setup_intent.createdSession startsOptional logging / analytics
setup_intent.succeededSaved 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

6 . 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 pointValue
customerID from Step 1.
payment_methodSaved card’s ID from webhook or listing API.
off_sessiontrue to attempt an off-session charge (recurring / unsupervised).

7 . Test the flow#

ActionTest card numberNotes
Successful save + charge4111 4111 41111 4111Any future date, any CVC
3-D Secure required4462030000000000Checkout will prompt for 3DS challenge
Use your test secret key and point webhooks to your dev endpoint.
Quick reference
TaskAPI
Create sessionPOST /v1/checkout/sessions/setup
Listen to eventssetup_intent.created setup_intent.succeeded
List cardsGET /v1/customers/{id}/payment_methods
Charge cardPOST /v1/payment_intents
Modified at 2025-08-08 11:25:11
Previous
Save payment method during payment
Next
Shopify Plugin
Built with