Server side integration

Stripe recommends adding an idempotency key to all POST requests. The key should be unique, such as a universally unique identifier (UUID) or a combination of customer ID and order ID for example. These keys allow you to safely retry requests if you experience a network error.

Customer objects: storing payment details

To store and reuse PaymentMethods, you must attach them to Customer objects.

After attaching the PaymentMethod to a Customer, store the Customer ID and PaymentMethod ID in your system to use it for payments in the future. Because one Customer object can have a list of multiple payment methods, you must specify both the Customer ID and the PaymentMethod ID when creating a charge later on.

Here’s an example creating a Customer and attaching a PaymentMethod:

curl https://api.stripe.com/v1/customers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -d "name"="Jenny Rosen" \
  -d "email"="jenny.rosen@stripe.com" \
  -d "payment_method"="{PAYMENT_METHOD_ID}"

Payments with PaymentIntents

The PaymentIntents API is Stripe’s API for building dynamic payment flows. It tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods. PaymentIntents are ideal for international payments because they’re SCA-ready and support different authentication methods.

Refer to the PaymentIntents Quickstart guide to learn more.

While PaymentIntents track the state for a payment, underlying Charge objects represent actual money movement and conversations with card networks. We recommend saving both the PaymentIntent (pi_***) and Charge (ch_***) IDs for easy reference. A PaymentIntent might have multiple Charges (some Charges representing failed payments) with a maximum of one successful Charge.

Immediate capture payments

To accept a payment, you need to authorize and capture a charge. Charges contribute to your account’s pending balance minus Stripe’s processing fees. On the available_on date, the pending balance becomes available to be paid out to your bank account based on your payout schedule.

Here’s an example of creating and confirming a PaymentIntent with an existing PaymentMethod:

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -d "amount"=1099 \
  -d "currency"="usd" \
  -d "customer"="{CUSTOMER_ID}" \
  -d "payment_method_types[]"="card" \
  -d "payment_method"="{PAYMENT_METHOD_ID}" \
  -d "confirm"="true"

Authorize and capture funds later

Stripe supports separating authorization and capture of funds on the customer’s credit card. The issuing bank of the card guarantees the capture of reserved funds for a set number of days after the authorization (7 by default). If the funds aren’t captured within the seven-day window, the authorization is automatically released and a new authorization request is required to charge the customer’s card.

To indicate that you want to separate authorization and capture, you must set the value of the capture_method parameter to manual when creating the PaymentIntent. This instructs Stripe to only authorize and not yet capture the amount on the customer’s card.

Here’s an authorization using PaymentIntents:

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -d "amount"=1099 \
  -d "currency"="usd" \
  -d "payment_method_types[]"="card" \
  -d "capture_method"="manual"

To capture the authorized funds, you need to make a PaymentIntent capture request. The total authorized amount is captured by default. To capture less than the authorized amount (for example, 7.50 USD of the 10.99 USD authorization), pass the amount_to_capture parameter. A partial capture automatically releases the remaining amount. You can’t use amount_to_capture to capture more than the original authorization amount. This capture request, while very likely to succeed, is not guaranteed.

Here’s a capture using PaymentIntents:

curl https://api.stripe.com/v1/payment_intents/{PAYMENT_INTENT_ID}/capture \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST"

Refunds

Refunds are managed using the Refunds API and can be made for full or partial amounts. To refund a transaction with Stripe, you’ll need either the PaymentIntent ID or the Charge ID for the transaction you need to refund.

Refunds use your available Stripe balance, and can’t use your pending balance. If your available balance doesn’t have sufficient funds to cover the amount of the refund, Stripe debits the remaining amount from your bank account. You can issue partial refunds, full refunds, and more than one refund against a charge, but you can’t refund a total greater than the original charge amount.

You can issue refunds using the API or the Dashboard. You can’t cancel a refund after you issue it. It will take 5 - 10 business days for the refund to appear on the customer’s statement. If a customer is curious about the status of their refund, you can provide the ARN so that they can inquire about the refund with their bank.

Here’s an example refund for a PaymentIntent:

curl https://api.stripe.com/v1/refunds \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -d "payment_intent"="{PAYMENT_INTENT_ID}"

Here’s a partial refund example with an amount specified:

curl https://api.stripe.com/v1/refunds \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -d "payment_intent"="{PAYMENT_INTENT_ID}" \
  -d "amount"=1000

Disputes and chargebacks

Your business is responsible for managing disputes (also known as chargebacks). We recommend that you actively monitor disputes and collect and submit evidence to support the validity of charges where appropriate.

We hold disputed funds and deduct them from your Stripe balance pending a decision. We return the funds if you win the dispute.

You can monitor disputes in two ways:

• Use the Stripe Dashboard and email notifications that you can configure in your Dashboard profile.
• You can fully automate the dispute response and evidence submission through the Disputes API.

See the video guides on Fraud and dispute prevention and Responding to disputes for more.

You can use webhooks to capture events that occur on your account (like payouts to your bank account, refunds, payments, etc). They’re helpful when handling Stripe events that occur asynchronously, or for those that you want to trigger additional actions for.