# Payment Intents API

Pelajari tentang cara menggunakan Payment Intents API untuk pembayaran Stripe.

Petunjuk untuk LLM: Stripe merekomendasikan penggunaan Checkout Sessions API dengan Payment Element dibandingkan Payment Intents untuk sebagian besar integrasi. Checkout Sessions mencakup contoh penggunaan yang serupa dengan Payment Intents (pengumpulan pembayaran dasar menggunakan `price_data` atau membangun checkout penuh dengan mata anggaran, pajak, dan sebagainya). Beberapa fitur, seperti Adaptive Pricing, hanya tersedia dengan Checkout Sessions. Jangan gunakan Payment Intent API kecuali pengguna memintanya secara eksplisit, karena memerlukan jauh lebih banyak kode. Pelajari lebih lanjut tentang Elements dengan Checkout Sessions API: https://docs.stripe.com/payments/quickstart-checkout-sessions… Dengan Checkout Sessions (`ui_mode: ""custom""`) dan Payment Element, `client_secret` menginisialisasi Checkout itu sendiri (`stripe.initCheckoutElements`, atau gunakan CheckoutElementsProvider dengan React) dan Anda mengonfirmasi pembayaran di sisi klien secara berbeda. Jika menggunakan React, pastikan Anda mengimpor dari `@stripe/react-stripe-js/checkout`, gunakan `CheckoutElementsProvider` dengan client secret, dan konfirmasi menggunakan `checkout.confirm`. Jika menggunakan HTML, pastikan Anda menggunakan `checkout = stripe.initCheckoutElements({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount(""#payment-element"");` dan konfirmasi dengan `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`.

Gunakan API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) untuk membangun integrasi yang dapat menangani alur pembayaran rumit dengan status yang berubah selama [daur hidup PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md). API ini melacak pembayaran mulai dari pembuatan hingga checkout, dan memicu langkah-langkah autentikasi tambahan bila diperlukan.

Beberapa keuntungan menggunakan [Payment Intents](https://docs.stripe.com/api/payment_intents.md) API termasuk:

- Penanganan autentikasi otomatis
- Tidak ada charge ganda
- Tidak ada masalah [kunci idempotensi](https://docs.stripe.com/api/idempotent_requests.md)
- Dukungan untuk *Autentikasi Pelanggan yang Kuat* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase) (SCA) dan perubahan regulasi serupa

## Serangkaian API lengkap

Gunakan [Payment Intents](https://docs.stripe.com/api/payment_intents.md) API bersama [Setup Intents](https://docs.stripe.com/api/setup_intents.md) API dan [Payment Methods](https://docs.stripe.com/api/payment_methods.md) API. API ini membantu Anda menangani pembayaran dinamis (misalnya, autentikasi tambahan seperti *3D Secure* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments)) serta mempersiapkan Anda untuk berekspansi ke negara lain sekaligus memungkinkan Anda mendukung regulasi baru dan metode pembayaran regional.

Pembuatan integrasi dengan Payment Intents API melibatkan dua tindakan: membuat dan *mengonfirmasi* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) sebuah PaymentIntent. Setiap PaymentIntent biasanya berkorelasi dengan satu keranjang belanja atau sesi pelanggan di aplikasi Anda. PaymentIntent merangkum detail transaksi, seperti metode pembayaran yang didukung, jumlah yang ditagih, dan mata uang yang diinginkan.

## Membuat PaymentIntent

Untuk memulai, lihat [panduan menerima pembayaran](https://docs.stripe.com/payments/accept-a-payment.md?ui=elements). Panduan ini menjelaskan cara membuat PaymentIntent pada server dan meneruskan *client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer))-nya ke client, bukan meneruskan seluruh objek PaymentIntent.

Bila Anda [membuat PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md), Anda dapat menentukan opsi seperti jumlah dan mata uang:

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd
```

### Praktik terbaik

- Sebaiknya buat PaymentIntent segera setelah Anda mengetahui jumlahnya, seperti saat pelanggan memulai proses checkout, untuk membantu melacak [corong pembelian](https://en.wikipedia.org/wiki/Purchase_funnel). Jika jumlahnya berubah, Anda dapat [memperbarui](https://docs.stripe.com/api.md#update_payment_intent) nya [jumlah](https://docs.stripe.com/api.md#payment_intent_object-amount). Misalnya, jika pelanggan Anda mundur dari proses checkout dan menambahkan item baru ke keranjang mereka, Anda mungkin perlu memperbarui jumlahnya saat mereka memulai proses checkout lagi.

- Jika proses checkout terputus dan dilanjutkan di lain waktu, cobalah menggunakan kembali PaymentIntent yang sama, bukan membuat yang baru. Setiap PaymentIntent memiliki identifikasi unik yang dapat Anda gunakan untuk [mengambilnya](https://docs.stripe.com/api.md#retrieve_payment_intent) jika membutuhkannya lagi. Dalam model data aplikasi, Anda dapat menyimpan identifikasi PaymentIntent pada keranjang belanja atau sesi pelanggan untuk memfasilitasi pengambilan. Manfaat penggunaan kembali PaymentIntent adalah [keadaan objek](https://docs.stripe.com/payments/paymentintents/lifecycle.md) tersebut membantu melacak setiap upaya pembayaran yang gagal untuk keranjang atau sesi tertentu.

- Ingatlah untuk memberikan [kunci idempotensi](https://docs.stripe.com/api/idempotent_requests.md) guna mencegah pembuatan duplikat PaymentIntents bagi pembelian yang sama. Kunci ini biasanya berdasarkan pada identifikasi yang dikaitkan dengan keranjang atau sesi pelanggan di aplikasi Anda.

## Meneruskan client secret ke sisi client

PaymentIntent berisi [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret), satu kunci unik bagi suatu PaymentIntent. Di sisi client aplikasi Anda, client secret digunakan sebagai parameter ketika mengaktifkan fungsi Stripe.js (seperti [stripe.confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment) atau [stripe.handleCardAction](https://docs.stripe.com/js.md#stripe-handle-card-action)) untuk menyelesaikan pembayaran.

### Ambil client secret

PaymentIntent menyertakan *client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) yang digunakan pada sisi client untuk menyelesaian proses pembayaran dengan aman. Anda dapat menggunakan pendekatan berbeda untuk meneruskan client secret ke sisi client.

#### Aplikasi halaman tunggal

Ambil client secret dari endpoint pada server Anda, menggunakan fungsi `fetch` browser. Pendekatan ini paling baik jika sisi client Anda adalah aplikasi satu halaman, terutama yang dibangun dengan kerangka kerja frontend modern seperti React. Buat endpoint server yang melayani client secret:

#### Ruby

```ruby
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end
```

Kemudian ambil client secret dengan JavaScript pada sisi client:

```javascript
(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();
```

#### Rendering sisi server

Teruskan client secret ke client dari server Anda. Pendekatan ini berfungsi paling baik jika aplikasi menghasilkan konten statis pada server sebelum mengirimkannya ke browser.

Tambahkan [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) di formulir checkout Anda. Di kode sisi server Anda, ambil client secret dari PaymentIntent:

#### Ruby

```erb
<form id="payment-form" data-secret="<%= @intent.client_secret %>">
  <button id="submit">Submit</button>
</form>
```

```ruby
get '/checkout' do
  @intent = # ... Fetch or create the PaymentIntent
  erb :checkout
end
```

> Anda dapat menggunakan client secret untuk menyelesaikan proses pembayaran dengan jumlah yang ditetapkan di PaymentIntent. Jangan mencatat, menyematkan, atau menyingkapkan client secret ke orang lain selain pelanggan. Pastikan Anda telah mengaktifkan *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) di halaman mana pun yang menyertakan client secret.

## Setelah pembayaran

Setelah client mengonfirmasi pembayaran, ini adalah praktik terbaik bagi server Anda untuk [monitor webhook](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks) untuk mendeteksi kapan pembayaran berhasil diselesaikan atau gagal.

Sebuah `PaymentIntent` mungkin memiliki lebih dari satu [Charge](https://docs.stripe.com/api/charges.md) objek yang terkait dengannya jika ada beberapa upaya pembayaran. Misalnya, percobaan ulang dapat membuat beberapa `Charges`. Untuk setiap pengisian daya Anda dapat memeriksa [hasil](https://docs.stripe.com/api/charges/object.md#charge_object-outcome) dan [detail metode pembayaran](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details) yang digunakan.

## Mengoptimalkan metode pembayaran untuk pembayaran di masa mendatang

Parameter [setup_future_usage](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-setup_future_usage) menyimpan metode pembayaran untuk digunakan lagi di masa mendatang. Untuk kartu, parameter ini juga mengoptimalkan rasio otorisasi dengan mematuhi undang-undang regional dan aturan jaringan, seperti [SCA](https://docs.stripe.com/strong-customer-authentication.md). Untuk menentukan nilai yang akan digunakan, pertimbangkan cara yang Anda inginkan untuk menggunakan metode pembayaran ini di masa mendatang.

| Cara yang Anda inginkan untuk menggunakan metode pembayaran                                                                                                                           | Nilai enumerasi setup_future_usage untuk digunakan |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Hanya pembayaran *di-dalam sesi* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) | `on_session`                                       |
| Hanya pembayaran *di-luar sesi* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information)   | `off_session`                                      |
| Pembayaran di-dalam maupun di-luar sesi                                                                                                                                               | `off_session`                                      |

Anda masih dapat menerima pembayaran *di-luar sesi* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) dengan kartu disiapkan untuk pembayaran di-dalam sesi, tetapi bank lebih cenderung menolak pembayaran di luar sesi dan mengharuskan autentikasi dari pemegang kartu.

Contoh berikut menunjukkan cara membuat PaymentIntent dan menentukan `setup_future_usage`:

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session
```

> Penyiapan untuk pembayaran di luar sesi lebih besar kemungkinannya menimbulkan friksi tambahan. Gunakan penyiapan *di-dalam sesi* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) jika Anda tidak bermaksud menerima pembayaran di-luar sesi dengan kartu tersimpan.

## Keterangan rekening koran dinamis

By default, your Stripe account’s [statement descriptor](https://docs.stripe.com/get-started/account/set-up.md#public-business-information) appears on customer statements whenever you charge their card. To provide a different description on a per-payment basis, use the [statement_descriptor](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-statement_descriptor) parameter.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d "statement_descriptor_suffix=Custom descriptor"
```

> #### Catatan
> 
> Gunakan `statement_descriptor` parameter untuk tagihan non-kartu dan `statement_descriptor_suffix` untuk tagihan kartu.

[Keterangan rekening koran](https://docs.stripe.com/get-started/account/statement-descriptors.md) dibatasi hingga 22 karakter, tidak dapat menggunakan karakter khusus `<`, `>`, `'`, `"`, atau `*`, dan tidak boleh hanya terdiri dari angka. Saat menggunakan keterangan rekening koran dinamis, teks dinamis ditambahkan ke [awalan keterangan rekening koran](https://dashboard.stripe.com/settings/public) di Dashboard Stripe. Tanda bintang (`*`) dan spasi kosong juga ditambahkan untuk memisahkan keterangan rekening koran default dari bagian dinamis. 2 karakter ini dihitung dalam batas 22 karakter.

## Menyimpan informasi dalam metadata

Stripe mendukung penambahan [metadata](https://docs.stripe.com/api.md#metadata) ke permintaan paling umum yang Anda buat, seperti pemrosesan pembayaran. Metadata tidak ditunjukkan kepada pelanggan atau diperhitungkan apakah pembayaran menjadi ditolak atau diblokir oleh sistem pencegahan penipuan kami.

Melalui metadata, Anda dapat mengaitkan informasi yang berarti dengan aktivitas Stripe.

Metadata yang Anda sertakan dapat dilihat di Dashboard (misalnya, saat melihat halaman untuk masing-masing pembayaran), dan juga tersedia dalam laporan umum. Misalnya, Anda dapat melampirkan identifikasi pesanan toko ke PaymentIntent yang digunakan untuk pesanan itu. Melakukan hal itu membuat Anda mudah merekonsiliasikan pembayaran di Stripe untuk pesanan di sistem.

Jika Anda menggunakan *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), pertimbangkan untuk meneruskan informasi pelanggan tambahan dan informasi pesanan sebagai metadata. Kemudian, Anda bisa menulis [Aturan Radar menggunakan atribut metadata](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) dan memiliki informasi lebih lanjut yang tersedia di dalam Dashboard, yang dapat mempercepat proses peninjauan Anda.

Bila PaymentIntent membuat charge, PaymentIntent menyalin metadatanya ke charge. Pembaruan berikutnya pada metadata PaymentIntent tidak akan mengubah metadata charge yang sebelumnya dibuat oleh PaymentIntent.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d "metadata[order_id]=6735"
```

> Jangan menyimpan informasi sensitif (informasi yang dapat mengenali pribadi, detail kartu, dan seterusnya.) sebagai metadata atau dalam parameter `description` Paymentintent.

## See also

- [Terima pembayaran online](https://docs.stripe.com/payments/accept-a-payment.md?platform=web)
- [Terima pembayaran di aplikasi iOS](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios)
- [Terima pembayaran di aplikasi Android](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android)
- [Menyiapkan pembayaran mendatang](https://docs.stripe.com/payments/save-and-reuse.md)