Create a Session
POST/v2/sessions
Creates a sessions object
Request
- application/json
Body
required
Array [
]
A custom code provided by a bank you want to use for online banking payment methods
branding
object
Details on branding elements to apply when rendering this Checkout Session.
A secure URL to an image icon
A secure URL to an image logo
Has the value of true if logo should be rendered in payment page or false if icon should be used.
A hex color code that will be used as background color of the payment page
A hex color code that will be used as background color of the submit or PAY button
Possible values: [auto, required]
Default value: auto
Describes whether Checkout should collect the customer's billing address.
Customers will be directed to this URL if they decide to cancel payment and return to your website.
A unique string to reference the Checkout Session. This can be a customer ID, a card ID, or similar, and can be used to reconcile the Session with your internal systems.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
The ID of an existing customer that will be associated with this Checkout Session. This is used to prefill the customer-related fields like email address, name and phone on the payment page.
Email address of customer. This is used to prefill the email field on the payment page.
Name of customer. This is used to prefill the name field on the payment page.
Describes whether Checkout should collect the customer's name.
Phone number of customer. This is used to prefill the phone field on the payment page.
If provided, Checkout will use this value as description of the charge.
line_items
object[]
required
A list of items the customer is purchasing. Each item is an object with the following properties.
Unit amount of the product in cents represented as a whole integer.
A description of the product
A secure URL to an image of the product
The name of the product
The quantity of the products being purchased
Possible values: [en]
The IETF language tag of the locale Checkout is displayed in. Defaults to en. As of current version, Checkout will not yet support other locales.
metadata
object
A set of key-value pairs that you can attach to a Checkout Session object. It can be useful for storing additional information about the session in a structured format.
Possible values: [payment, setup, subscription, save_card]
The mode of the Checkout Session. Required when creating a Checkout Session.
Possible values: [card, bpi, gcash, maya, alipay, unionpay, wechat]
A list of the types of payment methods (e.g., card) this Checkout Session can accept.
Describes whether Checkout should collect the customer's phone number.
shipping_address_collection
object
Describes whether Checkout should collect the customer's shipping address.
A list of two-letter ISO country codes. Checkout will only collect shipping address from customers in these countries.
Possible values: [pay, book, donate, send]
Describes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the submit button. submit_type can only be specified on Checkout Session in payment mode, but not on other modes.
Customers will be directed to this URL after a successful payment.
Responses
- 201
- 400
Created
- application/json
- Schema
- Example (from schema)
Schema
Array [
]
Unique identifier for the Session object.
String representing the object's type. Objects of the same type share the same value.
Total of all items before discounts or taxes are applied. Amount in cents represented as whole integer.
Total of all items after discounts and taxes are applied. Amount in cents represented as whole integer.
A custom code provided by a bank you want to use for online banking payment methods
branding
object
Details on branding elements to apply when rendering this Checkout Session.
A secure URL to an image icon
A secure URL to an image logo
Has the value of true if logo should be rendered in payment page or false if icon should be used.
A hex color code that will be used as background color of the payment page
A hex color code that will be used as background color of the submit or PAY button
billing
Address
nullable
Address information collected from the customer.
Customer name
Address line 1 (e.g., house number, street, or company name).
Address line 2 (e.g., apartment, suite, or building).
Suburb, town, village, or district.
City or municipality.
State, county, province, or region.
ZIP or postal code.
Two-letter ISO country code.
Possible values: [auto, required]
Default value: auto
Describes whether Checkout should collect the customer's billing address.
The URL the customer will be directed to if they decide to cancel payment and return to your website.
A unique string to reference the Checkout Session. This can be a customer ID, a card ID, or similar, and can be used to reconcile the Session with your internal systems.
The date and time the Checkout Session was created.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
The ID of an existing customer that will be associated with this Checkout Session.
Email address of customer.
Name of customer.
Describes whether Checkout should collect the customer's name.
Phone number of customer.
If provided, Checkout will use this value as description of the charge.
The date and time the Checkout Session will expire.
The date and time the Checkout Session was last updated.
line_items
object[]
The line items purchased by the customer.
Unit amount of the product in cents represented as a whole integer.
A description of the product
A secure URL to an image of the product
The name of the product
The quantity of the products being purchased
Has the value of true if the object exists in live mode or the value of false if the object exists in test mode.
Possible values: [en]
The IETF language tag of the locale Checkout is displayed in.
merchant
Merchant
Contains the merchant details that created this Checkout Session
Name of the merchant
Email address of the merchant's support team
Phone number of the merchant's support team
metadata
object
A set of key-value pairs that you can attach to a Checkout Session object.
Possible values: [payment]
Default value: payment
The mode of the Checkout Session.
The charge object details associated with the Checkout Session after successful payment.
Possible values: [card, bpi, gcash, maya, alipay, unionpay, wechat]
A list of the types of payment methods (e.g. card) this Checkout Session is allowed to accept.
The URL to the Checkout Session. Redirect customers to this URL to take them to Checkout.
Describes whether Checkout should collect the customer's phone number.
Indicates whether 3D Secure authentication shall be required for card payments. Always have a value true.
shipping
Address
nullable
Address information collected from the customer.
Customer name
Address line 1 (e.g., house number, street, or company name).
Address line 2 (e.g., apartment, suite, or building).
Suburb, town, village, or district.
City or municipality.
State, county, province, or region.
ZIP or postal code.
Two-letter ISO country code.
shipping_address_collection
object
Describes whether Checkout should collect the customer's shipping address.
A list of two-letter ISO country codes. Checkout will only collect shipping address from customers in these countries.
Possible values: [pay, book, donate, send]
Describes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the submit button.
The URL the customer will be directed to after a successful payment.
{
"id": "cs_ktDqQST3lm91sZ7y",
"object": "string",
"amount_subtotal": 5000,
"amount_total": 5000,
"bank_code": null,
"branding": {
"icon": "https://example.com/icon.png",
"logo": "https://example.com/logo.png",
"use_logo": true,
"primary_color": "#FFFFFF",
"secondary_color": "#4f99fe"
},
"billing": {
"name": "Gerry Isaac",
"line1": "#123 JP Rizal St.",
"line2": "string",
"barangay": "San Antonio",
"city": "Makati City",
"state": "Metro Manila",
"postal_code": 1200,
"country": "PH"
},
"billing_address_collection": "required",
"cancel_url": "https://example.com/cancel",
"client_reference_id": null,
"created_at": "2021-09-01T08:00:00Z",
"currency": "php",
"customer": "cus_ktDqQST3lm91sZ7y",
"customer_email": "[email protected]",
"customer_name": "Gerry Isaac",
"customer_name_collection": true,
"customer_phone": "+639123456789",
"description": "Purchase of Zip Tumbler",
"expires_at": "2021-09-02T08:00:00Z",
"last_updated": "2021-09-01T08:00:00Z",
"line_items": [
{
"name": "Zip Tumbler",
"quantity": 1,
"amount": 5000
}
],
"livemode": true,
"locale": "en",
"merchant": {
"name": "Zip Shop",
"support_email": "[email protected]",
"support_phone": null
},
"metadata": {
"PO Number": "123456"
},
"mode": "payment",
"payment_details": null,
"payment_method_types": [
"card",
"bpi",
"gcash",
"maya"
],
"payment_url": "https://pay.zip.ph/cs_ktDqQST3lm91sZ7y",
"phone_number_collection": true,
"require_auth": true,
"shipping": {
"name": "Gerry Isaac",
"line1": "#123 JP Rizal St.",
"line2": "string",
"barangay": "San Antonio",
"city": "Makati City",
"state": "Metro Manila",
"postal_code": 1200,
"country": "PH"
},
"shipping_address_collection": {
"allowed_countries": [
"PH",
"SG"
]
},
"submit_type": "pay",
"success_url": "https://example.com/success"
}
Validation error
- application/json
- Schema
- Example (from schema)
Schema
{
"message": [
"currency is required"
],
"error": "Bad Request",
"statusCode": 400
}