Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management

Server-side integration

Set up your Stripe back-end 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 an API key. You can also 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:

Command Line
cURL
curl https://api.stripe.com/v1/balance \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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:

Command Line
cURL
curl https://api.stripe.com/v1/customers \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -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:

Command Line
cURL
curl https://api.stripe.com/v1/refunds \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d payment_intent={PAYMENT_INTENT_ID}

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

Command Line
cURL
curl https://api.stripe.com/v1/refunds \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -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 Personal details settings.
  • 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:

WEBHOOK TYPERECOMMENDED WEBHOOKS
CHARGES
  • charge.succeeded
  • charge.failed
  • charge.refunded
REFUNDS
  • refund.created
  • refund.failed
PAYOUTS
  • payout.created
  • payout.paid
  • payout.failed
PAYMENT INTENTS
  • payment_intent.succeeded
  • payment_intent.payment_failed
  • payment_intent.canceled
DISPUTES
  • radar.early_fraud_warning.created
  • charge.dispute.created
  • charge.dispute.closed

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
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc