Mulai dengan komponen Connect yang disematkan
Pelajari cara menyematkan fungsionalitas dashboard ke situs web Anda.
Gunakan komponen tersemat Connect untuk menambahkan fungsionalitas dashboard akun terhubung ke situs web Anda. Pustaka ini dan API pendukungnya memungkinkan Anda memberikan akses ke produk Stripe secara langsung di dashboard.
Untuk versi imersif panduan ini, lihat mulai cepat integrasi komponen tersemat Connect. Anda juga dapat mengunduh sampel integrasi dari sana. Untuk menyesuaikan penampilan komponen tersemat Connect, gunakan opsi appearance
saat Anda melakukan inisialisasi StripeConnectInstance
. Lihat daftar lengkap parameter penampilan.
Lakukan inisialisasi Connect.jsSisi klienSisi server![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Stripe uses an AccountSession to express your intent to delegate API access to your connected account.
AccountSessions API mengembalikan client secret yang memungkinkan komponen tersemat di client web mengakses sumber daya akun terhubung seolah-olah Anda yang melakukan panggilan API untuk mereka.
Buat AccountSession Server![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Di aplikasi satu halaman, client Anda memprakarsai permintaan untuk memperoleh sesi akun ke server. Anda dapat membuat endpoint baru pada server yang mengembalikan client secret ke browser:
Create Account Session API![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
The Create Account Session API determines component and feature access for Connect embedded components. Stripe enforces these parameters for any components that correspond to the account session. If your site supports multiple user roles, make sure components and features that are enabled for that account session correspond to the current user’s role. For example, you can enable refund management only for administrators of your site, but not for other users. To ensure user role access are enforced, your backend must host the logic that maps your site’s user role to account session components.
Siapkan Connect.js Client![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Muat dan lakukan inisialisasi Connect.js Client![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Panggil loadConnectAndInitialize
dengan kunci yang dapat dipublikasikan dan fungsi yang mengambil client secret dengan memanggil endpoint baru yang Anda buat pada server. Gunakan StripeConnectInstance
yang dikembalikan untuk membuat komponen tersemat. Setelah melakukan inisialisasi Connect.js, Anda dapat memasang atau melepas komponen dari DOM kapan saja. Itu mencakup elemen yang ditampilkan di dalam portal React atau Vue.
Melakukan konfigurasi Connect.jsSisi klien![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Metode loadConnectAndInitialize
pada client mengambil beberapa opsi berbeda untuk melakukan konfigurasi Connect.js.
Opsi | Keterangan | |
---|---|---|
publishableKey | Kunci yang dapat dipublikasikan untuk integrasi Anda. | diperlukan |
fetchClientSecret | Fungsi yang mengambil client secret yang dikembalikan oleh/v1/account_ . Ini memberi tahu StripeConnectInstance akun mana yang akan didelegasikan aksesnya. Fungsi ini juga digunakan untuk mengambil fungsi client secret untuk memuat ulang sesi saat kedaluwarsa. | diperlukan |
appearance | Objek untuk menyesuaikan tampilan komponen tersemat Connect. | opsional |
locale | Parameter untuk menentukan lokal yang digunakan komponen tersemat Connect. Lokal tersebut default ke bahasa browser. Jika lokal yang ditentukan tidak secara langsung didukung, alternatif yang sewajarnya digunakan (misalnya fr-be mungkin kembali menjadi fr-fr ). Lihat pelokalan untuk daftar lokal yang didukung. | opsional |
fonts | Larik font custom yang tersedia untuk digunakan oleh komponen tersemat yang dibuat dari StripeConnectInstance . Font dapat ditentukan sebagai objek CssFontSource atau CustomFontSource. | opsional |
Sesuaikan tampilan komponen tersemat Connect![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Kami menawarkan serangkaian opsi untuk menyesuaikan tampilan dan cara kerja komponen tersemat Connect. Penyesuaian ini memengaruhi tombol, ikon, dan aksen lainnya di sistem desain kami.
Anda dapat mengatur opsi ini ketika melakukan inisialisasi StripeConnectInstance
dengan meneruskan nilai ke objek appearance
. Anda hanya dapat menggunakan opsi Connect.js untuk memodifikasi gaya di komponen tersemat Connect. Keluarga font dan warna latar belakang dari komponen tersemat Connect dapat dikesampingkan dengan pemilih CSS, tetapi Stripe tidak mendukung pengesampingan gaya lainnya.
const fetchClientSecret = async () => { const response = await fetch('/account_session'); const {client_secret: clientSecret} = await response.json(); return clientSecret; } const stripeConnectInstance = loadConnectAndInitialize({ publishableKey:
, fetchClientSecret: fetchClientSecret, fonts: [ { cssSrc: "https://myfonts.example.com/mycssfile.css", }, { src: `url(https://my-domain.com/assets/my-font-2.woff)`, family: 'My Font' } ], appearance: { // See all possible variables below overlays: "dialog", variables: { fontFamily: 'My Font', colorPrimary: "#FF0000", }, }, });"pk_test_TYooMQauvdEDq54NiTphI7jx"
Objek font![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Objek fonts
di stripeConnect.
mengambil larik dari objek CssFontSource atau CustomFontSource.
Jika Anda menggunakan font custom di halaman (yaitu, file .
atau .
), Anda harus menentukan file ini ketika melakukan inisialisasi komponen tersemat Connect. Melakukan hal ini memungkinkan komponen tersemat Connect menampilkan font ini dengan benar. Anda dapat menentukannya sebagai:
CssFontSource![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Gunakan objek ini untuk meneruskan URL lembar gaya yang menentukan font custom Anda ketika membuat StripeConnectInstance
. Dengan objek CssFontSource, konfigurasi CSP Anda harus memungkinkan pengambilan domain yang dikaitkan dengan URL file CSS yang ditentukan sebagai CssFontSource.
Nama | Tipe | Nilai contoh |
cssSrc | string required | https://fonts. |
URL relatif atau absolut yang mengarah ke file CSS dengan definisi @font-face. Penggunaan kebijakan keamanan konten (CSP) mungkin akan mengenakan arahan tambahan. |
CustomFontSource![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Gunakan objek ini untuk meneruskan font custom ketika membuat StripeConnectInstance
.
Nama | Tipe | Nilai contoh |
family | string required | Avenir |
Nama untuk diberikan ke font. | ||
src | string required | url(https://my-domain. |
Nilai src valid yang mengarah ke file font custom Anda. Ini biasanya (meski tidak selalu) berupa tautan ke file dengan akhiran . , . , atau . . | ||
display | string optional | auto |
Nilai tampilan-font yang valid. | ||
style | string optional | normal |
Salah satu dari normal , italic , atau oblique . | ||
unicodeRange | string optional | U+0-7F |
Nilai rentang-unicode yang valid. | ||
weight | string optional | 400 |
Bobot-font valid. Perhatikan bahwa ini merupakan string, bukan nomor. |
Objek penampilan![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Objek appearance
di loadConnectAndInitialize
mengambil properti opsional berikut:
Nama | Tipe | Nilai contoh |
overlays | ‘dialog’ (default) | ‘drawer’ | dialog |
Tipe overlay yang digunakan di seluruh sistem desain Connect.js. Atur ini menjadi Dialog atau Laci. | ||
variables | objek | {colorPrimary: "#0074D4"} |
Memperbarui komponen tersemat Connect setelah inisialisasi![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Metode update
mendukung pembaruan komponen tersemat Connect setelah inisialisasi. Ini berguna untuk beralih opsi penampilan pada runtime (tanpa memuat ulang halaman). Untuk melakukannya, gunakan objek stripeConnectInstance
sama yang Anda buat dengan initialize
dan panggil metode update
padanya:
stripeConnectInstance.update({ appearance: { variables: { colorPrimary: "#FF0000", }, }, locale: 'en-US', });
Catatan
Tidak semua opsi (mis. fonts
) dapat diperbarui. Opsi yang didukung untuk metode ini adalah subset dari opsi yang ditawarkan di initialize
. Ini mendukung pembaruan appearance
dan locale
.
Lebar dan tinggi![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Komponen tersemat Connect serupa dengan elemen HTML block
reguler, yang secara default mengambil 100% width
dari elemen HTML induknya, dan tumbuh tinggi sesuai dengan konten yang ditampilkan di dalamnya. Anda dapat mengontrol width
komponen tersemat Connect dengan menentukan width
induk HTML. Anda tidak dapat secara langsung mengontrol height
karena bergantung pada konten yang ditampilkan, namun demikian, Anda dapat membatasi tinggi dengan maxHeight
dan overflow: scroll
, sama seperti elemen block
HTML lainnya.
Autentikasi![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Kami menawarkan seperangkat API untuk mengelola sesi akun dan kredensial pengguna di komponen tersemat Connect.
Muat ulang client secret![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Pada sesi yang berjalan lama, sesi dari client secret yang semula diberikan mungkin kedaluwarsa. Bila kedaluwarsa, kami secara otomatis menggunakan fetchClientSecret
untuk mengambil client secret baru dan memuat ulang sesi. Anda tidak perlu meneruskan parameter tambahan.
import { loadConnectAndInitialize } from "@stripe/connect-js"; // Example method to retrieve the client secret from your server const fetchClientSecret = async () => { const response = await fetch('/account_session'); const {client_secret: clientSecret} = await response.json(); return clientSecret; } const stripeConnectInstance = loadConnectAndInitialize({ publishableKey: "{{PUBLISHABLE_KEY}}", fetchClientSecret: fetchClientSecret, });
Keluar![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Kami merekomendasikan Anda memanggil logout
pada stripeConnectInstance
untuk menghancurkan objek sesi akun terkait setelah pengguna keluar dari aplikasi Anda. Tindakan ini akan menonaktifkan semua komponen tersemat Connect yang bertaut dengan stripeConnectInstance
tersebut.
// Call this when your user logs out stripeConnectInstance.logout();
Persyaratan header CSP dan HTTP![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Jika situs web Anda menerapkan Kebijakan Keamanan Konten, Anda perlu memperbarui kebijakan dengan menambahkan aturan berikut:
frame-src
https://connect-js.
stripe. com https://js.
stripe. com img-src
https://*.
stripe. com script-src
https://connect-js.
stripe. com https://js.
stripe. com style-src
sha256-0hAheEzaMe6uXIKV4EehS9pu1am1lj/KnnzrOYqckXk=
(SHA dari elemen gaya kosong)
If you’re using a CSS file to load web fonts for use with Connect embedded components, its URL must be allowed by your connect-src CSP directive.
Mengatur header tanggapan HTTP tertentu memungkinkan fungsionalitas lengkap komponen tersemat Connect:
- Cross-Origin-Opener-Policy,
unsafe-none
. Catatan: (unsafe-none
) ini merupakan nilai default dari header, jadi tak mengatur header ini dapat berfungsi. Nilai lain sepertisame-origin
merusak autentikasi pengguna di komponen tersemat Connect.
Browser yang didukung![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Kami mendukung serangkaian browser yang sama yang saat ini didukung oleh Dashboard Stripe:
- Dua puluh versi utama terakhir Chrome dan Firefox
- Dua versi utama terakhir Safari dan Edge
- Dua versi utama terakhir Safari seluler di iOS
Komponen tersemat Connect tidak didukung di tampilan web, tetapi hanya didukung di browser mandiri.
Pelokalan![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Saat menginisialisasi Connect.js, Anda dapat melewatkan parameter locale
. Untuk mencocokkan lokal komponen tersemat dengan lokal situs web Anda, lewatkan parameter locale
dengan lokal UI yang dirender situs web Anda.
Nilai default dari parameter locale
ditentukan oleh lokasi yang dikonfigurasi browser. Jika lokal yang ditentukan tidak didukung secara langsung, alternatif yang masuk akal akan digunakan (misalnya fr-be
mungkin kembali ke fr-fr
).
Komponen tersemat Connect mendukung lokal berikut:
Bahasa | Kode lokal |
---|---|
Bahasa Bulgaria (Bulgaria) | bg-BG |
Bahasa Tionghoa (Disederhanakan) | zh-Hans |
Bahasa Tionghoa (Tradisional - Hong Kong) | zh-Hant-HK |
Bahasa Tionghoa (Tradisional - Taiwan) | zh-Hant-TW |
Bahasa Kroasia (Kroasia) | hr-HR |
Bahasa Ceko (Cheska) | cs-CZ |
Bahasa Denmark (Denmark) | da-DK |
Bahasa Belanda (Belanda) | nl-NL |
Bahasa Inggris (Australia) | en-AU |
Bahasa Inggris (India) | en-IN |
Bahasa Inggris (Irlandia) | en-IE |
Bahasa Inggris (Selandia Baru) | en-NZ |
Bahasa Inggris (Singapura) | en-SG |
Bahasa Inggris (Kerajaan Inggris) | en-GB |
Bahasa Inggris (Amerika Serikat) | en-US |
Bahasa Estonia (Estonia) | et-EE |
Bahasa Filipina (Filipina) | fil-PH |
Bahasa Finlandia (Finlandia) | fi-FI |
Bahasa Prancis (Kanada) | fr-CA |
Bahasa Prancis (Prancis) | fr-FR |
Bahasa Jerman (Jerman) | de-DE |
Bahasa Yunani (Yunani) | el-GR |
Bahasa Hungaria (Hungaria) | hu-HU |
Bahasa Indonesia (Indonesia) | id-ID |
Bahasa Italia (Italia) | it-IT |
Bahasa Jepang (Jepang) | ja-JP |
Bahasa Korea (Korea Selatan) | ko-KR |
Bahasa Latvia (Latvia) | lv-LV |
Bahasa Lituania (Lituania) | lt-LT |
Bahasa Melayu (Malaysia) | ms-MY |
Bahasa Malta (Malta) | mt-MT |
Bahasa Bokmål Norwegia (Norwegia) | nb-NO |
Bahasa Polandia (Polandia) | pl-PL |
Bahasa Portugis (Brasil) | pt-BR |
Bahasa Portugis (Portugal) | pt-PT |
Bahasa Rumania (Rumania) | ro-RO |
Bahasa Slowakia (Slowakia) | sk-SK |
Bahasa Slovenia (Slovenia) | sl-SI |
Bahasa Spanyol (Argentina) | es-AR |
Bahasa Spanyol (Brasil) | es-BR |
Bahasa Spanyol (Amerika Latin) | es-419 |
Bahasa Spanyol (Meksiko) | es-MX |
Bahasa Spanyol (Spanyol) | es-ES |
Bahasa Swedia (Swedia) | sv-SE |
Bahasa Thailand (Thailand) | th-TH |
Bahasa Turki (Türkiye) | tr-TR |
Bahasa Vietnam (Vietnam) | vi-VN |
Tangani kesalahan pemuatan![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Jika komponen gagal dimuat, Anda dapat bereaksi terhadap kegagalan dengan memberikan penangan kesalahan memuat untuk komponen tersemat. Tergantung pada penyebab kegagalan, penangan kesalahan memuat dapat dipanggil beberapa kali. Logika yang dipicu oleh penangan kesalahan memuat harus idempoten.
The load error
object![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Every time there’s a load failure, an error
object is passed to the load error handler with the following properties.
Name | Type | Example value |
type | authentication_ | |
The type of error | ||
message | string | undefined | Failed to fetch account session |
Further description about the error |
Types of load failures![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
When a component fails to load, we detect the type of failure and map it to one of the types below. If the load error type can’t be determined it is marked as an api_
.
Type | Description |
---|---|
api_ | Failure to connect to Stripe’s API |
authentication_ | Failure to perform the authentication flow within Connect embedded components |
account_ | Account session creation failed |
invalid_ | Request failed with an 4xx status code, typically caused by platform configuration issues |
rate_ | Request failed because an abnormal request rate was detected |
api_ | API errors covering any other type of problem, such as a temporary problem with Stripe’s servers |
Deteksi tampilan komponen tersemat![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Setelah komponen dibuat, tidak ada UI yang ditampilkan kepada pengguna hingga javascript untuk komponen tersebut dimuat dan diuraikan di browser. Hal ini dapat menyebabkan komponen muncul setelah selesai dimuat. Untuk menghindari hal ini, tampilkan UI pemuatan Anda sendiri sebelum komponen dibuat dan sembunyikan UI setelah komponen ditampilkan. Semua komponen tersemat dapat menerima fungsi pemanggilan balik yang dipanggil segera sebelum UI ditampilkan kepada pengguna.
Integrasikan tanpa paket npm frontend![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Kami merekomendasikan pengintegrasian dengan javascript dan pembungkus komponen React kami, yang memudahkan pemuatan komponen tersemat Connect dan menyediakan definisi TypeScript untuk antarmuka yang kami dukung. Jika sistem build Anda saat ini tidak mendukung pengambilan dependensi pada paket, Anda dapat melakukan integrasi tanpa paket ini.
Tambahkan tag skrip Connect.js secara manual ke <head>
dari setiap halaman pada situs Anda.
<!-- Somewhere in your site's <head> --> <script src="https://connect-js.stripe.com/v1.0/connect.js" async></script>
Menggunakan Connect.js tanpa NPM![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Setelah selesai dimuat, Connect.js melakukan inisialisasi StripeConnect
variabel jendela global dan memanggil StripeConnect.
jika Anda menentukannya. Anda dapat melakukan inisialisasi Connect.js secara aman dengan menyiapkan fungsi onload
dan memanggil StripeConnect.
dengan opsi Connect.js sebagai loadConnectAndInitialize
.
window.StripeConnect = window.StripeConnect || {}; StripeConnect.onLoad = () => { const stripeConnectInstance = StripeConnect.init({ // This is a placeholder - it should be replaced with your publishable API key. // Sign in to see your own test API key embedded in code samples. // Don’t submit any personally identifiable information in requests made with this key. publishableKey:
, fetchClientSecret: fetchClientSecret, }); const payments = stripeConnectInstance.create('payments'); document.body.appendChild(payments); };"pk_test_TYooMQauvdEDq54NiTphI7jx"
Autentikasi pengguna di komponen tersemat Connect![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Komponen tersemat Connect biasanya tidak memerlukan autentikasi pengguna. Dalam sejumlah skenario, komponen tersemat Connect mengharuskan akun terhubung masuk dengan akun Stripe untuk menyediakan fungsionalitas yang diperlukan (misalnya, menulis informasi ke badan hukum akun dalam kasus komponen onboarding akun).
Autentikasi mencakup popup ke jendela milik Stripe. Akun terhubung harus melakukan autentikasi sebelum dapat melanjutkan alur kerjanya.
Komponen onboarding akun dan manajemen akun memerlukan akun terhubung untuk melakukan autentikasi. Komponen lainnya mungkin memerlukan autentikasi dalam komponen setelah ditampilkan di awal. Autentikasi untuk komponen dan skenario ini diperlukan bagi semua akun terhubung kecuali jika platform telah menonaktifkan pengumpulan akun eksternal.