# 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](https://docs.stripe.com/keys-best-practices.md#limit-access) to further control access to specific resources. You can use the [secret and publishable API keys](https://docs.stripe.com/keys.md#obtain-api-keys) to create tokens, but need secret keys for any server-side authentication.

Here’s an example API call:

```curl
curl https://api.stripe.com/v1/balance \
  -u "<<YOUR_SECRET_KEY>>:"
```

## API request best practices

Stripe recommends adding an [idempotency key](https://docs.stripe.com/api/idempotent_requests.md) 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 re-use *PaymentMethods* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs), you must attach them to [Customer objects](https://docs.stripe.com/payments/save-and-reuse.md).

After attaching the PaymentMethod to a Customer, store the [Customer ID](https://docs.stripe.com/api/customers/object.md#customer_object-id) and [PaymentMethod ID](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-id) in your system to use it for payments in the future. Because one Customer object can have a [list of multiple payment methods](https://docs.stripe.com/api/payment_methods/list.md), 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
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d name="Jenny Rosen" \
  --data-urlencode email="jenny.rosen@stripe.com" \
  -d payment_method={PAYMENT_METHOD_ID}
```

### Refunds

Refunds are managed using the [Refunds](https://docs.stripe.com/api/refunds.md) 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](https://docs.stripe.com/api.md) or the [Dashboard](https://dashboard.stripe.com/test/dashboard). You can’t cancel a refund after you issue it. It takes [5-10 business days](https://support.stripe.com/questions/customer-refund-processing-time) 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](https://support.stripe.com/questions/acquirer-reference-number-\(arn\)-for-refunds) so that they can enquire about the refund with their bank.

Here’s an example refund for a PaymentIntent:

```curl
curl https://api.stripe.com/v1/refunds \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d payment_intent={PAYMENT_INTENT_ID}
```

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

```curl
curl https://api.stripe.com/v1/refunds \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d payment_intent={PAYMENT_INTENT_ID} \
  -d amount=1000
```

### Disputes and chargebacks

Your business is responsible for managing [disputes (also known as chargebacks)](https://docs.stripe.com/disputes.md). 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](https://dashboard.stripe.com/settings/user) settings.
- You can fully automate the dispute response and evidence submission through the [Disputes](https://docs.stripe.com/api/disputes.md) API.

## Configure webhooks

You can use *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/api/events.md) that occur asynchronously, or for those that you want to trigger additional actions for.
![](https://b.stripecdn.com/docs-statics-srv/assets/webhooks-endpoints.871d5a30be8e59762e191fa45b0421a2.png)

See our recommended webhook for each type:

| **Webhook type**    | **Recommended 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](https://docs.stripe.com/webhooks.md)
- [Check the webhook signatures](https://docs.stripe.com/webhooks.md#verify-events)
- [Types of events](https://docs.stripe.com/api/events/types.md)
- [Best practices for using webhooks](https://docs.stripe.com/webhooks.md#best-practices)
- [Check your webhook configurations](https://dashboard.stripe.com/account/webhooks)