WooshPay OpenAPI
Product DocumentAPI ReferenceJS SDK ReferenceSaaS Platform Integration
Product DocumentAPI ReferenceJS SDK ReferenceSaaS Platform Integration
Back to WooshPay Website
  1. Checkout
  • API Introduction
  • Error Code
  • Payment Intents
    • Create a PaymentIntent
      POST
    • Update a PaymentIntent
      POST
    • Cancel a PaymentIntent
      POST
    • Capture a PaymentIntent
      POST
    • Confirm a PaymentIntent
      POST
    • Retrieve a PaymentIntent
      GET
    • List all PaymentIntents
      GET
    • Search PaymentIntents
      GET
  • Charges
    • Retrieve a charge
      GET
    • List all charges
      GET
  • Payment Methods
    • Create a PaymentMethod
      POST
    • Retrieve a PaymentMethod
      GET
    • Retrieve a Customer's PaymentMethod
      GET
    • Update a PaymentMethod
      POST
    • List PaymentMethods
      GET
    • List a Customer's PaymentMethods
      GET
    • Attach a PaymentMethod to a Customer
      POST
    • Detach a PaymentMethod from a Customer
      POST
  • Refunds
    • Create a refund
      POST
    • Retrieve a refund
      GET
  • Webhooks
    • Create a Webhook
    • List All Webhooks
    • Retrieve a Webhook
    • Delete a Webhook
    • Update a Webhook
  • Events
    • Types of events
    • Retrieve an event
  • Files
    • Files
    • Create a file
    • Retrieve a file
  • Disputes
    • Retrieve a dispute
    • Update a dispute
    • Close a dispute
    • List all disputes
  • Payouts
    • Beneficiary
      • Create a beneficiary
      • Retrieve a beneficiary
      • List all beneficiaries
      • Update a beneficiary
      • Delete a beneficiary
    • Payouts
      • Create a payout
      • Retrieve a Payout
      • Update a Payout
      • List All Payouts
  • Balance
    • Get balance
  • Products
    • Create a Product
    • Retrieve a product
    • Update a product
    • List all products
  • Prices
    • Create a price
    • Retrieve a price
    • Update a price
  • Payment Links
    • Create a payment link
    • Update a payment link
    • Retrieve payment link
    • List all payment links
    • Retrieve a payment link's line items
  • Checkout
    • Create a Session
      POST
    • Expire a Session
      POST
    • Retreive a Session
      GET
    • List All Checkout Sessions
      GET
    • Retrieve a Checkout Session's line items
      GET
  • Customers
    • Create a customer
    • Retrieve a customer
    • Update a customer
  • Invoices
    • Setup Intents
      • Create a SetupIntent
      • Retrieve a SetupIntent
      • Cancel a SetupIntent
      • List all SetupIntents
      • List all SetupAttempts
      • Update a SetupIntent
      • Confirm a SetupIntent
    • Create an invoice
    • Retrieve an invoice
    • Finalize an invoice
    • Send an invoice for manual payment
    • Delete a draft invoice
    • Void an invoice
    • List all invoices
    • Pay an invoice
  • Invoice Items
    • Create an invoice item
    • Retrieve an invoice item
  • Invoice Line Item
    • Bulk add invoice line items
  • Subscriptions
    • Create a subscription
    • Retrieve a subscription
    • Update a subscription
    • Cancel a subscription
    • List subscriptions
  • Subscription Items
    • Create a subscription item
    • Retrieve a subscription item
    • Delete a subscription item
  • Issuing
    • Authorizations
      • Retrieve an authorization
      • List all authorization
    • Cardholders
      • Create a cardholder
      • Update a cardholder
      • Retrieve a cardholder
      • List all cardholders
    • Cards
      • Create a card
      • Update a card
      • Retrieve a card
      • List all cards
      • Retrieve card remaining limits
    • Transactions
      • Update a transaction
      • Retrieve a transaction
      • List all transactions
  • Coupons
    • Create a Coupon
    • Retrieve a coupon
    • Delete a coupon
  • Promotion Code
    • Create a promotion code
    • Update a promotion code
  • Accounts
    • Retrieve account's paymentmethods
  • Fx Quote
    • Create an FX Quote
  1. Checkout

Create a Session

POST
/v1/checkout/sessions
Creates a Session object.

Request

Authorization
Send your HTTP requests with an
Authorization
header that contains the word Basic followed by a space and a base64-encoded string username:password
Example:
Authorization: Basic *****************
Header Params
Accept
string 
required
Default:
application/json
Content-Type
string 
required
Default:
application/json
Body Params application/json
billing_address_collection
enum<string> 
optional
Describes whether Checkout should collect the customer’s billing address.
Allowed values:
requiredauto
cancel_url
string 
optional
The URL the customer will be directed to if they decide to cancel payment and return to your website.
client_reference_id
string 
optional
A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the Session with your internal systems.
customer
string 
optional
The ID of the customer for this Session.
customer_email
string 
optional
If provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once the payment flow is complete, use the customer attribute.
expires_at
integer 
optional
The timestamp at which the Checkout Session will expire. The Epoch time in seconds at which the Checkout Session will expire. It can be anywhere from 1 to 24 hours after Checkout Session creation. By default, this value is 24 hours from creation.
metadata
object 
optional
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
mode
enum<string> 
required
The mode of the Checkout Session. Only payment is supported now.
Allowed values:
paymentsubscription
payment_method_options
object (Payment Method Options) 
optional
Payment-method-specific configuration for the PaymentIntent or SetupIntent of this CheckoutSession.
card
object 
optional
alipayplus
object 
optional
alipay_hk
object 
optional
alipay
object 
optional
wechat_pay
object 
optional
sepa_debit
object 
optional
akulaku
object 
optional
truemoney
object 
optional
kakaopay
object 
optional
shopeepay
object 
optional
dana
object 
optional
pix
object 
optional
payment_method_types
array[string]
optional
A list of the types of payment methods (e.g. card) this Checkout Session is allowed to accept.
phone_number_collection
object 
optional
Details on the state of phone number collection for the session. phone_number_collection.enabled boolean Indicates whether phone number collection is enabled for the session
enabled
boolean 
optional
Indicates whether phone number collection is enabled for the session.
shipping_address_collection
object 
optional
When set, provides configuration for Checkout to collect a shipping address from a customer.
allowed_countries
array[string]
optional
An array of two-letter ISO country codes representing which countries Checkout should provide as options for shipping locations.
success_url
string 
required
The URL the customer will be directed to after the payment or subscription creation is successful.
allow_promotion_codes
boolean 
optional
Enables user redeemable promotion codes.
customer_creation
enum<string> 
optional
Configure whether a Checkout Session creates a Customer when the Checkout Session completes. Can only be set in payment and setup mode.
Allowed values:
alwaysif_required
payment_intent_data
object 
optional
A subset of parameters to be passed to PaymentIntent creation for Checkout Sessions in payment mode.
capture_method
string 
optional
Controls when the funds will be captured from the customer’s account. Possible enum values：automatic(default) and manual
description
string 
optional
An arbitrary string attached to the object. Often useful for displaying to users.
shipping
object (Shipping) 
optional
billing_details
object (Billing Details) 
optional
merchant_order_id
string 
optional
The order ID created in the merchant's order system that corresponds to this PaymentIntent
merchant_user_id
string 
optional
The user ID created in merchant's order system that corresponds to this PaymentIntent
metadata
object 
optional
A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
line_items
array [object {3}] 
optional
A list of items the customer is purchasing. Use this parameter to pass one-time or recurring Prices.
price
string 
optional
Required conditionally. The ID of the Price object. One of price or price_data is required.
price_data
object 
optional
Required conditionally.Data used to generate a new Price object inline. One of price or price_data is required. For more details of price_data, please refer to the endpoint of 'create a price'.
quantity
string 
required
Required unless metered billing. The quantity of the line item being purchased.
discounts
array [object {2}] 
optional
The coupon or promotion code to apply to this Session. Currently, only up to one may be specified.
coupon
string 
optional
The ID of the coupon to apply to this Session.
iterations
integer 
optional
This parameter indicates how many billing cycles the discount applies to in the subscription. The default value is 1.
subscription_data
object 
optional
trial_period_days
integer 
optional
Integer representing the number of trial period days before the customer is charged for the first time. Has to be at least 1.
metadata
object 
optional
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
Example
{
    "cancel_url": "https://yourwebsite.com",
    "mode": "payment",
    "success_url": "https://yourwebsite.com",
    "line_items": [
        {
            "price_data": {
                "currency": "GBP",
                "unit_amount": 2000,
                "product_data": {
                    "name": "apple"
                }
            },
            "quantity": 1
        }
    ]
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://apitest.wooshpay.com/v1/checkout/sessions' \
--header 'Accept;' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Og==' \
--data-raw '{
    "cancel_url": "https://yourwebsite.com",
    "mode": "payment",
    "success_url": "https://yourwebsite.com",
    "line_items": [
        {
            "price_data": {
                "currency": "GBP",
                "unit_amount": 2000,
                "product_data": {
                    "name": "apple"
                }
            },
            "quantity": 1
        }
    ]
}'

Responses

🟢200OK
application/json
Body
id
string 
optional
Unique identifier for the object, like "cs_xxx" in live environment and "cs_test_xxx" in test environment.
object
string 
optional
value is "checkout.session"
amount_subtotal
integer 
optional
Total of all items before discounts or taxes are applied.
amount_total
integer 
optional
Total of all items after discounts and taxes are applied.
billing_address_collection
enum<string> 
optional
Describes whether Checkout should collect the customer’s billing address.
Allowed values:
requiredauto
cancel_url
string 
optional
The URL the customer will be directed to if they decide to cancel payment and return to your website.
client_reference_id
string 
optional
A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the Session with your internal systems.
created
integer 
optional
Time at which the object was created. Measured in seconds since the Unix epoch.
currency
string 
optional
Three-letter ISO currency code
customer
string 
optional
The ID of the customer for this Session.
customer_email
string 
optional
If provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once the payment flow is complete, use the customer attribute.
expires_at
integer 
optional
The timestamp at which the Checkout Session will expire. The Epoch time in seconds at which the Checkout Session will expire. It can be anywhere from 1 to 24 hours after Checkout Session creation. By default, this value is 24 hours from creation.
livemode
boolean 
optional
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadata
object 
optional
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
mode
string 
optional
The mode of the Checkout Session. Only payment is supported now.
payment_intent
string 
optional
The ID of the PaymentIntent for Checkout Sessions in payment mode.
payment_link
string 
optional
The ID of the Payment Link that created this Session.
payment_method_options
object (Payment Method Options) 
optional
Payment-method-specific configuration for the PaymentIntent or SetupIntent of this CheckoutSession.
card
object 
optional
alipayplus
object 
optional
alipay_hk
object 
optional
alipay
object 
optional
wechat_pay
object 
optional
sepa_debit
object 
optional
akulaku
object 
optional
truemoney
object 
optional
kakaopay
object 
optional
shopeepay
object 
optional
dana
object 
optional
pix
object 
optional
payment_method_types
array[string]
optional
A list of the types of payment methods (e.g. card) this Checkout Session is allowed to accept.
payment_status
string 
optional
The payment status of the Checkout Session, one of paid, unpaid, or no_payment_required. You can use this value to decide when to fulfill your customer’s order.
phone_number_collection
object 
optional
Details on the state of phone number collection for the session. phone_number_collection.enabled boolean Indicates whether phone number collection is enabled for the session
enabled
boolean 
optional
Indicates whether phone number collection is enabled for the session.
shipping_address_collection
object 
optional
When set, provides configuration for Checkout to collect a shipping address from a customer.
allowed_countries
array[string]
optional
An array of two-letter ISO country codes representing which countries Checkout should provide as options for shipping locations.
shipping
object 
optional
Shipping information for this Checkout Session.
address
object (Address) 
optional
carrier
string 
optional
The delivery service that shipped a physical product, such as FedEx, UPS, USPS, etc.
name
string 
optional
Recipient name.
phone
string 
optional
Recipient phone (including extension).
tracking_number
string 
optional
The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.
status
enum<string> 
optional
The status of the Checkout Session, one of open, complete, or expired.
Allowed values:
opencompleteexpired
success_url
string 
optional
The URL the customer will be directed to after the payment or subscription creation is successful.
url
string 
optional
The URL to the Checkout Session. Redirect customers to this URL to take them to Checkout.
line_items
object 
optional
The line items purchased by the customer. This field is not included by default. To include it in the response, expand the line_items field.
object
string 
optional
Default:
"list"
url
string 
optional
has_more
boolean 
optional
data
array [object {10}] 
optional
subscription
string  | null 
optional
The ID of the subscription for Checkout Sessions in subscription mode.
customer_creation
enum<string> 
optional
Configure whether a Checkout Session creates a Customer when the Checkout Session completes. Can only be set in payment and setup mode.
Allowed values:
alwaysif_required
customer_details
object 
optional
address
object 
optional
The customer’s address after a completed Checkout Session.
email
string  | null 
optional
The email associated with the Customer, if one exists, on the Checkout Session after a completed Checkout Session or at time of session expiry.
name
string  | null 
optional
The customer’s name after a completed Checkout Session.
phone
string  | null 
optional
The customer’s phone number after a completed Checkout Session.
Example
{
    "id": "string",
    "object": "string",
    "amount_subtotal": 0,
    "amount_total": 0,
    "billing_address_collection": "required",
    "cancel_url": "string",
    "client_reference_id": "string",
    "created": 0,
    "currency": "string",
    "customer": "string",
    "customer_email": "string",
    "expires_at": 0,
    "livemode": true,
    "metadata": {},
    "mode": "string",
    "payment_intent": "string",
    "payment_link": "string",
    "payment_method_options": {
        "card": {
            "request_three_d_secure": "any",
            "setup_future_usage": "on_session",
            "capture_method": "string",
            "tax_id": "string"
        },
        "alipayplus": {
            "terminal_type": "APP",
            "os_type": "IOS"
        },
        "alipay_hk": {
            "terminal_type": "APP",
            "os_type": "IOS"
        },
        "alipay": {
            "terminal_type": "APP",
            "os_type": "IOS"
        },
        "wechat_pay": {
            "terminal_type": "WEB",
            "client_ip": "string",
            "os_type": "IOS",
            "openid": "string"
        },
        "sepa_debit": {},
        "akulaku": {
            "terminal_type": "WEB",
            "os_type": "IOS"
        },
        "truemoney": {
            "terminal_type": "WEB",
            "os_type": "IOS"
        },
        "kakaopay": {
            "terminal_type": "WEB",
            "os_type": "IOS"
        },
        "shopeepay": {
            "terminal_type": "string",
            "os_type": "string"
        },
        "dana": {
            "terminal_type": "string",
            "os_type": "string"
        },
        "pix": {
            "tax_id": "string"
        }
    },
    "payment_method_types": [
        "string"
    ],
    "payment_status": "string",
    "phone_number_collection": {
        "enabled": true
    },
    "shipping_address_collection": {
        "allowed_countries": [
            "string"
        ]
    },
    "shipping": {
        "address": {
            "city": "string",
            "country": "string",
            "line1": "string",
            "line2": "string",
            "postal_code": "string",
            "state": "string"
        },
        "carrier": "string",
        "name": "string",
        "phone": "string",
        "tracking_number": "string"
    },
    "status": "open",
    "success_url": "string",
    "url": "string",
    "line_items": {
        "object": "\"list\"",
        "url": "string",
        "has_more": true,
        "data": [
            {
                "id": "string",
                "object": "string",
                "amount_subtotal": "string",
                "amount_total": "string",
                "currency": "string",
                "description": "string",
                "price": {
                    "id": "string",
                    "object": "string",
                    "active": true,
                    "billing_scheme": "per_unit",
                    "created": 0,
                    "currency": "string",
                    "livemode": true,
                    "lookup_key": "string",
                    "metadata": {},
                    "nickname": "string",
                    "product": "string",
                    "type": "one_time",
                    "unit_amount": 0,
                    "recurring": {
                        "interval": "day",
                        "interval_count": 0,
                        "usage_type": "licensed"
                    },
                    "tiers": [
                        {
                            "up_to": "string",
                            "flat_amount": "string",
                            "unit_amount": "string"
                        }
                    ]
                },
                "quantity": "string",
                "discounts": [
                    {
                        "id": "string",
                        "object": "string",
                        "checkout_session": "string",
                        "coupon": {
                            "id": "string",
                            "amount_off": 0,
                            "currency": "string",
                            "duration_in_days": "string",
                            "object": "string",
                            "created": 0,
                            "livemode": true,
                            "metadata": {},
                            "name": "string",
                            "percent_off": 0,
                            "max_redemptions": 0,
                            "redeem_by": 0,
                            "times_redeemed": 0,
                            "valid": true,
                            "currency_options": {
                                "<currency>.amount_off": 0
                            }
                        },
                        "customer": "string",
                        "start": 0,
                        "end": null,
                        "promotion_code": null,
                        "subscription": null
                    }
                ],
                "amount_discount": 0
            }
        ]
    },
    "subscription": "string",
    "customer_creation": "always",
    "customer_details": {
        "address": {
            "city": "string",
            "country": "string",
            "line1": "string",
            "line2": "string",
            "postal_code": "string",
            "state": "string"
        },
        "email": "string",
        "name": "string",
        "phone": "string"
    }
}
Previous
Retrieve a payment link's line items
Next
Expire a Session
Built with