Server-side integration

To set up an optimal backend integration, you must authenticate to Stripe, learn API request best practices, and appropriately configure your webhooks.

Authenticate to Stripe

Stripe provides authentication through API key. It’s also possible to create restricted access keys to further control access to specific resources. You can use the secret and publishable API keys to create tokens, but need secret keys for any server-side authentication.

Here’s an example API call:

curl https://api.stripe.com/v1/balance \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

API request best practices

Stripe recommends adding an idempotency key to all POST requests. Make sure that the key is unique, such as a universally unique identifier (UUID) or a combination of customer ID and order ID. These keys allow you to safely retry requests if you encounter 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
:" \
  -d name="Jenny Rosen" \
  --data-urlencode email="jenny.rosen@stripe.com" \
  -d payment_method={PAYMENT_METHOD_ID}

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 takes 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
:" \
  -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
:" \
  -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.

Configure webhooks

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

See our recommended webhook for each type:

Use the following resources to set up your webhooks and validate that they’ve been configured correctly:

• Webhooks
• Check the webhook signatures
• Types of events
• Best practices for using webhooks
• Check your webhook configurations