# Extend checkout with custom components

Display custom text and collect additional information on Checkout Sessions.

# Hosted page

> This is a Hosted page for when platform is web and payment-ui is stripe-hosted. View the full page at https://docs.stripe.com/payments/checkout/custom-components?platform=web&payment-ui=stripe-hosted.

## Add custom fields 

You can add custom fields on the payment form to collect additional information from your customers. The information is available after the payment is complete and is useful for fulfilling the purchase.

Custom fields have the following limitations:

- Up to three fields allowed.
- Not available in `setup` mode.
- Support for up to 255 characters on text fields.
- Support for up to 255 digits on numeric fields.
- Support for up to 200 options on dropdown fields.

> Don’t use custom fields to collect personal, protected, or sensitive data, or information restricted by law.

### Create a Checkout Session 

Create a Checkout Session while specifying an array of [custom fields](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields). Each field must have a unique `key` that your integration uses to reconcile the field. Also provide a label for the field that you display to your customer. Labels for custom fields aren’t translated, but you can use the [locale](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) parameter to set the language of your Checkout Session to match the same language as your labels.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text"
```
![](https://d37ugbyn3rpeym.cloudfront.net/videos/checkout/custom_fields_embedded.mov)
### Retrieve custom fields 

When your customer completes the Checkout Session, we send a [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) with the completed fields.

Example `checkout.session.completed` payload:

```json
{
  "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0",
  "object": "event",
  "api_version": "2022-11-15",
  "created": 1664928000,
  "data": {
    "object": {
      "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k",
      "object": "checkout.session","custom_fields": [{
        "key": "engraving",
        "label": {
          "type": "custom",
          "custom": "Personalized engraving"
        },
        "optional": false,
        "type": "text",
        "text": {
          "value": "Jane"
        }
      }],
      "mode": "payment"
    }
  },
  "livemode": false,
  "pending_webhooks": 1,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "checkout.session.completed"
}
```

You can also look up and edit custom field values from the Dashboard, by clicking into a specific payment in the [Transactions](https://dashboard.stripe.com/payments) tab or including custom field values when exporting your payments from the [Dashboard](https://dashboard.stripe.com/payments).

### Use a custom field 

#### Mark a field as optional 

By default, customers must complete all fields before completing payment. To mark a field as optional, pass in `optional=true`.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][optional]=true"
```
![](https://b.stripecdn.com/docs-statics-srv/assets/optional.bf0c1564296ff02264bd5e8c066a6034.png)

#### Add a dropdown field 

A dropdown field presents your customers with a list of options to select from. To create a dropdown field, specify `type=dropdown` and a list of options, each with a `label` and a `value`. The `label` displays to the customer while your integration uses the `value` to reconcile which option the customer selected.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=sample" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Free sample" \
  -d "custom_fields[0][optional]=true" \
  -d "custom_fields[0][type]=dropdown" \
  -d "custom_fields[0][dropdown][options][0][label]=Balm sample" \
  -d "custom_fields[0][dropdown][options][0][value]=balm" \
  -d "custom_fields[0][dropdown][options][1][label]=BB cream sample" \
  -d "custom_fields[0][dropdown][options][1][value]=cream"
```
![A checkout page with a dropdown field](https://b.stripecdn.com/docs-statics-srv/assets/dropdown.4501d199ebe009030c2be6935cfdf2dd.png)

#### Add a numbers only field 

A numbers-only field provides your customers a text field that only accepts numerical values, up to 255 digits. To create a numbers-only field, specify `type=numeric`.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=invoice" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Invoice number" \
  -d "custom_fields[0][type]=numeric"
```

#### Retrieve custom fields for a subscription 

You can retrieve the custom fields associated with a subscription by querying for the Checkout Session that created it using the [subscription](https://docs.stripe.com/api/checkout/sessions/list.md#list_checkout_sessions-subscription) parameter.

```curl
curl -G https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "subscription={{SUBSCRIPTION_ID}}"
```

#### Add character length validations 

You can optionally specify a minimum and maximum character length [requirement](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-maximum_length) for `text` and `numeric` field types.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][text][minimum_length]=10" \
  -d "custom_fields[0][text][maximum_length]=20" \
  -d "custom_fields[0][optional]=true"
```
![A field with character limits](https://b.stripecdn.com/docs-statics-srv/assets/between-validation.20431cd8e0c03a028843945d1f1ea314.png)

#### Add default values 

You can optionally provide a default value for the [text](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-text-default_value), [numeric](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-default_value), and [dropdown](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-dropdown-default_value) field types. Default values are prefilled on the payment page.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][text][default_value]=Stella" \
  -d "custom_fields[1][key]=size" \
  -d "custom_fields[1][label][type]=custom" \
  -d "custom_fields[1][label][custom]=Size" \
  -d "custom_fields[1][type]=dropdown" \
  -d "custom_fields[1][dropdown][default_value]=small" \
  -d "custom_fields[1][dropdown][options][0][value]=small" \
  -d "custom_fields[1][dropdown][options][0][label]=Small" \
  -d "custom_fields[1][dropdown][options][1][value]=large" \
  -d "custom_fields[1][dropdown][options][1][label]=Large"
```

## Customize text and policies 

When customers pay with Stripe Checkout, you can present additional text, such as shipping and processing times.

> Anda dilarang menggunakan fitur ini untuk membuat teks custom yang melanggar atau menimbulkan ambiguitas dengan teks yang dihasilkan Stripe di Checkout, kewajiban berdasarkan perjanjian Stripe Anda, kebijakan Stripe, dan hukum yang berlaku.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "shipping_address_collection[allowed_countries][0]=US" \
  --data-urlencode "custom_text[shipping_address][message]=Please note that we can't guarantee 2-day delivery for PO boxes at this time." \
  --data-urlencode "custom_text[submit][message]=We'll email you instructions on how to get started." \
  --data-urlencode "custom_text[after_submit][message]=Learn more about **your purchase** on our [product page](https://www.stripe.com/)." \
  --data-urlencode "success_url=https://example.com/success"
```
![Teks custom di dekat pengumpulan alamat pengiriman](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

Teks custom di dekat bidang pengumpulan alamat pengiriman
![Teks custom di atas tombol bayar](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Teks custom di atas tombol **Bayar**
![Teks custom di bawah tombol bayar](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

Teks custom setelah tombol **Bayar**

Teks custom Anda dapat berisi hingga 1200 karakter. Namun, Stripe Checkout dioptimalkan untuk konversi, dan menambahkan informasi tambahan dapat memengaruhi tingkat konversi Anda. Anda dapat menebalkan teks atau menyisipkan tautan menggunakan [sintaks Markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Untuk menyesuaikan Checkout dengan model bisnis Anda, atur teks yang ditampilkan pada tombol kirim Checkout untuk pembelian satu kali.

Define a `submit_type` on your session. In this example (for a 5 USD donation), your customized Checkout submit button displays **Donate \5.00 USD**. See the [API reference](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-submit_type) for a complete list of `submit_type` options.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d submit_type=donate \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success"
```

## Pelokalan dan bahasa yang didukung

Secara default, Checkout mendeteksi lokal browser pelanggan dan menampilkan versi terjemahan halaman dalam bahasanya, jika Stripe [mendukungnya](https://support.stripe.com/questions/supported-languages-for-stripe-checkout). Anda dapat mengesampingkan lokal browser untuk Checkout dengan meneruskan `locale` [parameter](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) bila Anda membuat Sesi Checkout.

Checkout juga menggunakan lokal untuk memformat angka dan mata uang. Misalnya, ketika menjual produk yang harganya diatur dalam EUR dengan lokal yang diatur ke `auto`, browser yang dikonfigurasikan untuk menggunakan bahasa Inggris (`en`) akan menampilkan €25,00 sedangkan browser yang dikonfigurasikan untuk bahasa Jerman (`de`) akan menampilkan 25,00 €.

### Customize policies and contact information 

Anda dapat menampilkan informasi pengembalian barang, pengembalian dana, dan kebijakan legal, serta kontak dukungan Anda kepada pelanggan di Checkout. Buka [Pengaturan Checkout](https://dashboard.stripe.com/settings/checkout) untuk mengonfigurasi informasi yang ingin Anda tampilkan, termasuk:

- Detail tentang kebijakan pengembalian dana dan pengembalian barang Anda
- Nomor telepon, email, dan situs web dukungan Anda
- Tautan ke ketentuan layanan dan kebijakan privasi Anda

Menampilkan informasi ini dapat meningkatkan kepercayaan diri pembeli dan meminimalkan pengabaian keranjang.

### Lakukan konfigurasi kebijakan legal dan dukungan

Dari [Pengaturan Checkout](https://dashboard.stripe.com/settings/checkout), tambahkan informasi kontak dukungan ke sesi Anda dengan mengaktifkan **Informasi kontak**. Demikian pula, tambahkan tautan ke **Ketentuan layanan** dan **Kebijakan privasi** ke sesi Anda dengan mengaktifkan **Kebijakan hukum**. Jika Anda mengharuskan pelanggan menyetujui kebijakan legal Anda secara implisit saat menyelesaikan checkout, pilih kotak centang **Tampilkan perjanjian untuk ketentuan legal**.

Anda harus menambahkan informasi kontak dukungan dan tautan kebijakan legal di [Pengaturan Detail Publik](https://dashboard.stripe.com/settings/public).

Pratinjau berikut memperlihatkan cara Checkout menampilkan dialog dengan informasi kontak dukungan, tautan ke kebijakan legal toko, dan informasi tentang ketentuan pembayaran.
![Halaman checkout dengan informasi kontak.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Pratinjau informasi kontak pada Checkout.
![Halaman checkout dengan kebijakan legal.](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Pratinjau kebijakan legal pada Checkout.

### Lakukan konfigurasi kebijakan pengembalian dana dan pengembalian barang

Tampilkan kebijakan pengembalian barang, pengembalian dana, atau penukaran Anda, dengan mengaktifkan **Kebijakan Pengembalian Dana dan Pengembalian barang**. Meski bisnis yang menjual barang fisik menggunakan kebijakan pengembalian barang, bisnis yang menjual barang digital atau barang fisik yang disesuaikan biasanya menggunakan kebijakan pengembalian dana. Karena keduanya tidak saling menggantikan, Anda dapat memilih kedua opsi jika bisnis Anda menjual kedua kategori barang tersebut. Anda dapat mengedit detail pengembalian dana dan pengembalian barang, termasuk:

- Jika Anda menerima pengembalian barang, pengembalian dana, atau penukaran
- Jika pengembalian barang, pengembalian dana, atau penukaran itu gratis atau jika dikenakan biaya
- Berapa hari setelah pembelian Anda akan menerima pengembalian barang, pengembalian dana, atau penukaran
- Cara pelanggan dapat mengembalikan barang yang dikirim kepadanya
- Jika Anda menerima pengembalian barang di toko
- Tautan ke kebijakan lengkap pengembalian dana dan pengembalian barang
- Pesan custom

Jika Anda menerima pengembalian barang, pengembalian dana, atau penukaran secara gratis, Checkout menyoroti kebijakan tersebut untuk pelanggan.

Pratinjau berikut memperlihatkan cara Checkout menampilkan kebijakan pengembalian barang. Contoh ini untuk pembelian yang dapat dikembalikan dengan melakukan pengiriman atau di toko untuk pengembalian dana (atau penukaran) penuh hingga 60 hari. Anda dapat menampilkan informasi serupa untuk pengembalian dana.
![Pratinjau kebijakan pengembalian pada Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Pratinjau kebijakan pengembalian barang pada Checkout.
![Pratinjau sorotan kebijakan pada Checkout](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Pratinjau sorotan kebijakan pada Checkout.

#### Kumpulkan perjanjian ketentuan layanan

Bisnis sering meminta pelanggannya untuk menyetujui ketentuan layanannya sebelum mereka dapat membayar. Hal ini mungkin tergantung pada tipe produk atau langganan. Checkout membantu Anda mengumpulkan perjanjian yang diperlukan dengan mengharuskan pelanggan untuk menerima ketentuan Anda sebelum membayar.
![Kumpulkan perjanjian ketentuan layanan](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

Kumpulkan perjanjian ketentuan layanan

Anda dapat mengumpulkan perjanjian ketentuan layanan dengan Stripe Checkout saat membuat Sesi:

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=2" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "consent_collection[terms_of_service]=required" \
  --data-urlencode "custom_text[terms_of_service_acceptance][message]=I agree to the [Terms of Service](https://example.com/terms)"
```

Bila `consent_collection.terms_of_service='required'`, Checkout secara dinamis menampilkan kotak centang untuk mengumpulkan perjanjian ketentuan layanan pelanggan. Jika `consent_collection.terms_of_service='none'`, Checkout tidak akan menampilkan kotak centang dan tidak akan mengharuskan pelanggan untuk menerima ketentuan layanan. Sebelum mewajibkan persetujuan terhadap ketentuan Anda, atur URL ketentuan layanan di [detail publik](https://dashboard.stripe.com/settings/public) bisnis Anda. Mengatur URL kebijakan privasi bersifat opsional—Checkout juga menautkan ke kebijakan privasi bila URL ke Kebijakan privasi Anda diatur di [Detail publik](https://dashboard.stripe.com/settings/public).

Setelah pelanggan menyelesaikan checkout, Anda dapat memverifikasi bahwa pelanggan menerima ketentuan layanan Anda dengan melihat objek Sesi di webhook `checkout.session.completed`, atau dengan mengambil Sesi menggunakan API. Bila ketentuan diterima, bidang [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) Sesi diatur ke `accepted`.

Anda dapat menyesuaikan teks yang muncul di sebelah kotak centang dengan menggunakan `custom_text.terms_of_service_acceptance`. Anda perlu mengatur `consent_collection.terms_of_service='required'`. Untuk menggunakan ketentuan Anda sendiri, masukkan tautan Markdown. Misalnya: `I agree to the [Terms of Service](https://example.com/terms)`

> Konsultasikan dengan penasihat hukum dan kepatuhan Anda sebelum melakukan perubahan pada teks ini. Anda tidak dapat menggunakan fitur ini untuk menampilkan teks custom yang melanggar atau menimbulkan ambiguitas dengan teks yang dihasilkan Stripe di Checkout, kewajiban berdasarkan perjanjian Stripe Anda, kebijakan Stripe, dan hukum yang berlaku.

#### Collect consent for promotional emails

Anda dapat mengirim email promosi untuk memberi tahu pelanggan tentang produk baru serta untuk membagikan kupon dan diskon. Sebelum melakukannya, Anda harus [mengumpulkan persetujuan](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md) mereka untuk menerima email promosi.

## Sesuaikan perjanjian penggunaan kembali metode pembayaran dan ketentuan langganan

Bila sesi dalam mode `setup` ataupun `subscription`, atau dalam mode `payment` dengan `setup_future_usage` yang diatur, Checkout menampilkan pesan tentang penggunaan kembali metode pembayaran pelanggan. Pesan dapat menyertakan informasi khusus untuk metode pembayaran yang dipilih. Anda dapat menyembunyikan atau menyesuaikan teks default, tetapi tidak menyembunyikan teks khusus metode pembayaran.

Untuk langganan, teks custom dapat menyertakan informasi seperti berikut ini:

- Tautan ke ketentuan langganan Anda
- Tautan ke portal pelanggan Anda
- Mekanisme dan kebijakan pembatalan
![Tampilan perjanjian penggunaan kembali metode pembayaran default dalam mode langganan](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

Perjanjian penggunaan kembali metode pembayaran default dalam mode langganan

> Dengan menyesuaikan teks ini, Anda bertanggung jawab untuk mempertahankan kepatuhan, termasuk memperbarui teks ini saat aturan jaringan kartu dan regulasi setempat berubah. Jangan menggunakan fitur ini tanpa berkonsultasi dengan tim legal Anda atau mengatur teks custom yang menyertakan informasi mengenai penggunaan kembali metode pembayaran. Pastikan teks yang disesuaikan mencakup semua mode yang Anda rencanakan untuk didukung.

Untuk menyembunyikan teks perjanjian penggunaan kembali metode pembayaran, atur `consent_collection.payment_method_reuse_agreement.position='hidden'`. Checkout tidak akan menampilkan bahasa default-nya yang mengatur penggunaan kembali metode pembayaran. Untuk mengatur teks Anda sendiri sebagai pengganti bahasa default Stripe, atur `custom_text.after_submit.message`. Anda juga dapat menggunakan `custom_text.submit` atau `custom_text.terms_of_service_acceptance` untuk menampilkan versi Anda sendiri dari bahasa ini.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=subscription \
  --data-urlencode "success_url=https://example.com/success" \
  -d "consent_collection[payment_method_reuse_agreement][position]=hidden" \
  --data-urlencode "custom_text[after_submit][message]=You can cancel your subscription at any time by [logging into your account](https://www.example.com/)"
```


# Embedded page

> This is a Embedded page for when platform is web and payment-ui is embedded-form. View the full page at https://docs.stripe.com/payments/checkout/custom-components?platform=web&payment-ui=embedded-form.

You can add custom fields on the payment form to collect additional information from your customers. You can also customize the text that your customers see, and the policies Checkout displays.

## Add custom fields 

You can add custom fields on the payment form to collect additional information from your customers. The information is available after the payment is complete and is useful for fulfilling the purchase.

Custom fields have the following limitations:

- Up to three fields allowed.
- Not available in `setup` mode.
- Support for up to 255 characters on text fields.
- Support for up to 255 digits on numeric fields.
- Support for up to 200 options on dropdown fields.

> Don’t use custom fields to collect personal, protected, or sensitive data, or information restricted by law.

### Create a Checkout Session 

Create a Checkout Session while specifying an array of [custom fields](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields). Each field must have a unique `key` that your integration uses to reconcile the field. Also provide a label for the field that you display to your customer. Labels for custom fields aren’t translated, but you can use the [locale](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) parameter to set the language of your Checkout Session to match the same language as your labels.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text"
```
![](https://d37ugbyn3rpeym.cloudfront.net/videos/checkout/custom_fields_embedded.mov)
### Retrieve custom fields 

When your customer completes the Checkout Session, we send a [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) with the completed fields.

Example `checkout.session.completed` payload:

```json
{
  "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0",
  "object": "event",
  "api_version": "2022-11-15",
  "created": 1664928000,
  "data": {
    "object": {
      "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k",
      "object": "checkout.session","custom_fields": [{
        "key": "engraving",
        "label": {
          "type": "custom",
          "custom": "Personalized engraving"
        },
        "optional": false,
        "type": "text",
        "text": {
          "value": "Jane"
        }
      }],
      "mode": "payment"
    }
  },
  "livemode": false,
  "pending_webhooks": 1,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "checkout.session.completed"
}
```

You can also look up and edit custom field values from the Dashboard, by clicking into a specific payment in the [Transactions](https://dashboard.stripe.com/payments) tab or including custom field values when exporting your payments from the [Dashboard](https://dashboard.stripe.com/payments).

### Use a custom field 

#### Mark a field as optional 

By default, customers must complete all fields before completing payment. To mark a field as optional, pass in `optional=true`.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][optional]=true"
```
![](https://b.stripecdn.com/docs-statics-srv/assets/optional.bf0c1564296ff02264bd5e8c066a6034.png)

#### Add a dropdown field 

A dropdown field presents your customers with a list of options to select from. To create a dropdown field, specify `type=dropdown` and a list of options, each with a `label` and a `value`. The `label` displays to the customer while your integration uses the `value` to reconcile which option the customer selected.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=sample" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Free sample" \
  -d "custom_fields[0][optional]=true" \
  -d "custom_fields[0][type]=dropdown" \
  -d "custom_fields[0][dropdown][options][0][label]=Balm sample" \
  -d "custom_fields[0][dropdown][options][0][value]=balm" \
  -d "custom_fields[0][dropdown][options][1][label]=BB cream sample" \
  -d "custom_fields[0][dropdown][options][1][value]=cream"
```
![A checkout page with a dropdown field](https://b.stripecdn.com/docs-statics-srv/assets/dropdown.4501d199ebe009030c2be6935cfdf2dd.png)

#### Add a numbers only field 

A numbers-only field provides your customers a text field that only accepts numerical values, up to 255 digits. To create a numbers-only field, specify `type=numeric`.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=invoice" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Invoice number" \
  -d "custom_fields[0][type]=numeric"
```

#### Retrieve custom fields for a subscription 

You can retrieve the custom fields associated with a subscription by querying for the Checkout Session that created it using the [subscription](https://docs.stripe.com/api/checkout/sessions/list.md#list_checkout_sessions-subscription) parameter.

```curl
curl -G https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "subscription={{SUBSCRIPTION_ID}}"
```

#### Add character length validations 

You can optionally specify a minimum and maximum character length [requirement](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-maximum_length) for `text` and `numeric` field types.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][text][minimum_length]=10" \
  -d "custom_fields[0][text][maximum_length]=20" \
  -d "custom_fields[0][optional]=true"
```
![A field with character limits](https://b.stripecdn.com/docs-statics-srv/assets/between-validation.20431cd8e0c03a028843945d1f1ea314.png)

#### Add default values 

You can optionally provide a default value for the [text](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-text-default_value), [numeric](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-default_value), and [dropdown](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-dropdown-default_value) field types. Default values are prefilled on the payment page.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][text][default_value]=Stella" \
  -d "custom_fields[1][key]=size" \
  -d "custom_fields[1][label][type]=custom" \
  -d "custom_fields[1][label][custom]=Size" \
  -d "custom_fields[1][type]=dropdown" \
  -d "custom_fields[1][dropdown][default_value]=small" \
  -d "custom_fields[1][dropdown][options][0][value]=small" \
  -d "custom_fields[1][dropdown][options][0][label]=Small" \
  -d "custom_fields[1][dropdown][options][1][value]=large" \
  -d "custom_fields[1][dropdown][options][1][label]=Large"
```

## Customize text and policies 

When customers pay with Stripe Checkout, you can present additional text, such as shipping and processing times.

> Anda dilarang menggunakan fitur ini untuk membuat teks custom yang melanggar atau menimbulkan ambiguitas dengan teks yang dihasilkan Stripe di Checkout, kewajiban berdasarkan perjanjian Stripe Anda, kebijakan Stripe, dan hukum yang berlaku.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "shipping_address_collection[allowed_countries][0]=US" \
  --data-urlencode "custom_text[shipping_address][message]=Please note that we can't guarantee 2-day delivery for PO boxes at this time." \
  --data-urlencode "custom_text[submit][message]=We'll email you instructions on how to get started." \
  --data-urlencode "custom_text[after_submit][message]=Learn more about **your purchase** on our [product page](https://www.stripe.com/)." \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return"
```
![Teks custom di dekat pengumpulan alamat pengiriman](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

Teks custom di dekat bidang pengumpulan alamat pengiriman
![Teks custom di atas tombol bayar](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Teks custom di atas tombol **Bayar**
![Teks custom di bawah tombol bayar](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

Teks custom setelah tombol **Bayar**

Teks custom Anda dapat berisi hingga 1200 karakter. Namun, Stripe Checkout dioptimalkan untuk konversi, dan menambahkan informasi tambahan dapat memengaruhi tingkat konversi Anda. Anda dapat menebalkan teks atau menyisipkan tautan menggunakan [sintaks Markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Untuk menyesuaikan Checkout dengan model bisnis Anda, atur teks yang ditampilkan pada tombol kirim Checkout untuk pembelian satu kali.

Define a `submit_type` on your session. In this example (for a 5 USD donation), your customized Checkout submit button displays **Donate \5.00 USD**. See the [API reference](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-submit_type) for a complete list of `submit_type` options.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d submit_type=donate \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return"
```

## Pelokalan dan bahasa yang didukung

Secara default, Checkout mendeteksi lokal browser pelanggan dan menampilkan versi terjemahan halaman dalam bahasanya, jika Stripe [mendukungnya](https://support.stripe.com/questions/supported-languages-for-stripe-checkout). Anda dapat mengesampingkan lokal browser untuk Checkout dengan meneruskan `locale` [parameter](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) bila Anda membuat Sesi Checkout.

Checkout juga menggunakan lokal untuk memformat angka dan mata uang. Misalnya, ketika menjual produk yang harganya diatur dalam EUR dengan lokal yang diatur ke `auto`, browser yang dikonfigurasikan untuk menggunakan bahasa Inggris (`en`) akan menampilkan €25,00 sedangkan browser yang dikonfigurasikan untuk bahasa Jerman (`de`) akan menampilkan 25,00 €.

### Customize policies and contact information 

Anda dapat menampilkan informasi pengembalian barang, pengembalian dana, dan kebijakan legal, serta kontak dukungan Anda kepada pelanggan di Checkout. Buka [Pengaturan Checkout](https://dashboard.stripe.com/settings/checkout) untuk mengonfigurasi informasi yang ingin Anda tampilkan, termasuk:

- Detail tentang kebijakan pengembalian dana dan pengembalian barang Anda
- Nomor telepon, email, dan situs web dukungan Anda
- Tautan ke ketentuan layanan dan kebijakan privasi Anda

Menampilkan informasi ini dapat meningkatkan kepercayaan diri pembeli dan meminimalkan pengabaian keranjang.

### Lakukan konfigurasi kebijakan legal dan dukungan

Dari [Pengaturan Checkout](https://dashboard.stripe.com/settings/checkout), tambahkan informasi kontak dukungan ke sesi Anda dengan mengaktifkan **Informasi kontak**. Demikian pula, tambahkan tautan ke **Ketentuan layanan** dan **Kebijakan privasi** ke sesi Anda dengan mengaktifkan **Kebijakan hukum**. Jika Anda mengharuskan pelanggan menyetujui kebijakan legal Anda secara implisit saat menyelesaikan checkout, pilih kotak centang **Tampilkan perjanjian untuk ketentuan legal**.

Anda harus menambahkan informasi kontak dukungan dan tautan kebijakan legal di [Pengaturan Detail Publik](https://dashboard.stripe.com/settings/public).

Pratinjau berikut memperlihatkan cara Checkout menampilkan dialog dengan informasi kontak dukungan, tautan ke kebijakan legal toko, dan informasi tentang ketentuan pembayaran.
![Halaman checkout dengan informasi kontak.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Pratinjau informasi kontak pada Checkout.
![Halaman checkout dengan kebijakan legal.](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Pratinjau kebijakan legal pada Checkout.

### Lakukan konfigurasi kebijakan pengembalian dana dan pengembalian barang

Tampilkan kebijakan pengembalian barang, pengembalian dana, atau penukaran Anda, dengan mengaktifkan **Kebijakan Pengembalian Dana dan Pengembalian barang**. Meski bisnis yang menjual barang fisik menggunakan kebijakan pengembalian barang, bisnis yang menjual barang digital atau barang fisik yang disesuaikan biasanya menggunakan kebijakan pengembalian dana. Karena keduanya tidak saling menggantikan, Anda dapat memilih kedua opsi jika bisnis Anda menjual kedua kategori barang tersebut. Anda dapat mengedit detail pengembalian dana dan pengembalian barang, termasuk:

- Jika Anda menerima pengembalian barang, pengembalian dana, atau penukaran
- Jika pengembalian barang, pengembalian dana, atau penukaran itu gratis atau jika dikenakan biaya
- Berapa hari setelah pembelian Anda akan menerima pengembalian barang, pengembalian dana, atau penukaran
- Cara pelanggan dapat mengembalikan barang yang dikirim kepadanya
- Jika Anda menerima pengembalian barang di toko
- Tautan ke kebijakan lengkap pengembalian dana dan pengembalian barang
- Pesan custom

Jika Anda menerima pengembalian barang, pengembalian dana, atau penukaran secara gratis, Checkout menyoroti kebijakan tersebut untuk pelanggan.

Pratinjau berikut memperlihatkan cara Checkout menampilkan kebijakan pengembalian barang. Contoh ini untuk pembelian yang dapat dikembalikan dengan melakukan pengiriman atau di toko untuk pengembalian dana (atau penukaran) penuh hingga 60 hari. Anda dapat menampilkan informasi serupa untuk pengembalian dana.
![Pratinjau kebijakan pengembalian pada Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Pratinjau kebijakan pengembalian barang pada Checkout.
![Pratinjau sorotan kebijakan pada Checkout](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Pratinjau sorotan kebijakan pada Checkout.

#### Kumpulkan perjanjian ketentuan layanan

Bisnis sering meminta pelanggannya untuk menyetujui ketentuan layanannya sebelum mereka dapat membayar. Hal ini mungkin tergantung pada tipe produk atau langganan. Checkout membantu Anda mengumpulkan perjanjian yang diperlukan dengan mengharuskan pelanggan untuk menerima ketentuan Anda sebelum membayar.
![Kumpulkan perjanjian ketentuan layanan](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

Kumpulkan perjanjian ketentuan layanan

Anda dapat mengumpulkan perjanjian ketentuan layanan dengan Stripe Checkout saat membuat Sesi:

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=2" \
  -d mode=payment \
  -d "consent_collection[terms_of_service]=required" \
  --data-urlencode "custom_text[terms_of_service_acceptance][message]=I agree to the [Terms of Service](https://example.com/terms)" \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return"
```

Bila `consent_collection.terms_of_service='required'`, Checkout secara dinamis menampilkan kotak centang untuk mengumpulkan perjanjian ketentuan layanan pelanggan. Jika `consent_collection.terms_of_service='none'`, Checkout tidak akan menampilkan kotak centang dan tidak akan mengharuskan pelanggan untuk menerima ketentuan layanan. Sebelum mewajibkan persetujuan terhadap ketentuan Anda, atur URL ketentuan layanan di [detail publik](https://dashboard.stripe.com/settings/public) bisnis Anda. Mengatur URL kebijakan privasi bersifat opsional—Checkout juga menautkan ke kebijakan privasi bila URL ke Kebijakan privasi Anda diatur di [Detail publik](https://dashboard.stripe.com/settings/public).

Setelah pelanggan menyelesaikan checkout, Anda dapat memverifikasi bahwa pelanggan menerima ketentuan layanan Anda dengan melihat objek Sesi di webhook `checkout.session.completed`, atau dengan mengambil Sesi menggunakan API. Bila ketentuan diterima, bidang [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) Sesi diatur ke `accepted`.

Anda dapat menyesuaikan teks yang muncul di sebelah kotak centang dengan menggunakan `custom_text.terms_of_service_acceptance`. Anda perlu mengatur `consent_collection.terms_of_service='required'`. Untuk menggunakan ketentuan Anda sendiri, masukkan tautan Markdown. Misalnya: `I agree to the [Terms of Service](https://example.com/terms)`

> Konsultasikan dengan penasihat hukum dan kepatuhan Anda sebelum melakukan perubahan pada teks ini. Anda tidak dapat menggunakan fitur ini untuk menampilkan teks custom yang melanggar atau menimbulkan ambiguitas dengan teks yang dihasilkan Stripe di Checkout, kewajiban berdasarkan perjanjian Stripe Anda, kebijakan Stripe, dan hukum yang berlaku.

#### Collect consent for promotional emails

Anda dapat mengirim email promosi untuk memberi tahu pelanggan tentang produk baru serta untuk membagikan kupon dan diskon. Sebelum melakukannya, Anda harus [mengumpulkan persetujuan](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md) mereka untuk menerima email promosi.

## Sesuaikan perjanjian penggunaan kembali metode pembayaran dan ketentuan langganan

Bila sesi dalam mode `setup` ataupun `subscription`, atau dalam mode `payment` dengan `setup_future_usage` yang diatur, Checkout menampilkan pesan tentang penggunaan kembali metode pembayaran pelanggan. Pesan dapat menyertakan informasi khusus untuk metode pembayaran yang dipilih. Anda dapat menyembunyikan atau menyesuaikan teks default, tetapi tidak menyembunyikan teks khusus metode pembayaran.

Untuk langganan, teks custom dapat menyertakan informasi seperti berikut ini:

- Tautan ke ketentuan langganan Anda
- Tautan ke portal pelanggan Anda
- Mekanisme dan kebijakan pembatalan
![Tampilan perjanjian penggunaan kembali metode pembayaran default dalam mode langganan](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

Perjanjian penggunaan kembali metode pembayaran default dalam mode langganan

> Dengan menyesuaikan teks ini, Anda bertanggung jawab untuk mempertahankan kepatuhan, termasuk memperbarui teks ini saat aturan jaringan kartu dan regulasi setempat berubah. Jangan menggunakan fitur ini tanpa berkonsultasi dengan tim legal Anda atau mengatur teks custom yang menyertakan informasi mengenai penggunaan kembali metode pembayaran. Pastikan teks yang disesuaikan mencakup semua mode yang Anda rencanakan untuk didukung.

Untuk menyembunyikan teks perjanjian penggunaan kembali metode pembayaran, atur `consent_collection.payment_method_reuse_agreement.position='hidden'`. Checkout tidak akan menampilkan bahasa default-nya yang mengatur penggunaan kembali metode pembayaran. Untuk mengatur teks Anda sendiri sebagai pengganti bahasa default Stripe, atur `custom_text.after_submit.message`. Anda juga dapat menggunakan `custom_text.submit` atau `custom_text.terms_of_service_acceptance` untuk menampilkan versi Anda sendiri dari bahasa ini.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=subscription \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "consent_collection[payment_method_reuse_agreement][position]=hidden" \
  --data-urlencode "custom_text[after_submit][message]=You can cancel your subscription at any time by [logging into your account](https://www.example.com/)"
```


# Checkout elements

> This is a Checkout elements for when platform is web and payment-ui is elements. View the full page at https://docs.stripe.com/payments/checkout/custom-components?platform=web&payment-ui=elements.

Custom components aren’t necessary when using Checkout elements. You can compose the elements in your own interface and insert your own custom components in between them as needed.