Card payments on the Charges APILegacy

The Charges and Tokens APIs are legacy APIs used in older Stripe integrations to accept debit and credit card payments. Use PaymentIntents for new integrations.

The Charges API limits your ability to take advantage of Stripe features. To get the latest features, use Stripe Checkout or migrate to the Payment Intents API.

Payment flow

In most cases, the PaymentIntents API offers more flexibility and integration options.

Refunds

To refund a payment through the API, create a Refund and provide the ID of the charge to be refunded.

curl https://api.stripe.com/v1/refunds \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -d charge={{CHARGE_ID}}

To refund part of a payment, provide an amount parameter, as an integer in cents (or the charge currencys smallest currency unit).

curl https://api.stripe.com/v1/refunds \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -d charge={{CHARGE_ID}} \
  -d amount=1000

Apple Pay

When your customer approves the payment, your app receives a PKPayment instance containing their encrypted card details by implementing the PKPaymentAuthorizationViewControllerDelegate methods.

1. Use the createTokenWithPayment SDK method to turn the PKPayment into a Stripe Token
2. Use this Token to create a charge.

extension CheckoutViewController: PKPaymentAuthorizationViewControllerDelegate {

    func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, didAuthorizePayment payment: PKPayment, handler: @escaping (PKPaymentAuthorizationResult) -> Void) {
        // Convert the PKPayment into a Token
        STPAPIClient.shared.createToken(withPayment: payment) { token, error in
              guard let token = token else {
                  // Handle the error
                  return
              }
            let tokenID = token.tokenId
            // Send the token identifier to your server to create a Charge...
            // If the server responds successfully, set self.paymentSucceeded to YES
        }
    }

    func paymentAuthorizationViewControllerDidFinish(_ controller: PKPaymentAuthorizationViewController) {

Dynamic statement descriptor

By default, your Stripe accounts statement descriptor appears on customer statements whenever you charge their card. Additionally, you can set the statement descriptor dynamically on every charge request with the statement_descriptor argument on the Charge object.

curl https://api.stripe.com/v1/charges \
  -u sk_test_wU7nrJCZspk1NPDxiQgAF05q: \
  -d "amount"=999 \
  -d "currency"="usd" \
  -d "description"="Example charge" \
  -d "source"="tok_visa" \
  -d "statement_descriptor"="Custom descriptor"

Statement descriptors are limited to 22 characters, cant use the special characters <, >, ', ", or *, and must not consist solely of numbers.

When setting the statement descriptor dynamically on credit and debit card charges, the dynamic portion is appended to the settlement merchants statement descriptor (separated by an * and an empty space). For example, a statement descriptor for a business, named FreeCookies, that includes the kind of cookie purchased might look like FREECOOKIES* SUGAR.

The * and empty space count towards the 22 character limit and Stripe automatically allots 10 characters for the dynamic statement descriptor. This means that the settlement merchants descriptor might be truncated if its longer than 10 characters (assuming the dynamic statement descriptor is also greater than 10 characters). If the dynamic statement descriptor is also greater than 10 characters, both descriptors are truncated at 10 characters.

If youre having issues with the character limits, you can set a shortened descriptor in the Stripe Dashboard to shorten the settlement merchants descriptor. This allows more room for the dynamic statement descriptor. The shortened descriptor:

• Replaces the settlement merchants statement descriptor when using dynamic descriptors.
• Can be between 2 and 10 characters.

If youre not sure what the statement descriptors look like when theyre combined, you can check them in the Stripe Dashboard.

Storing information in metadata

Using Payment Intents

If using the Payment Intents API, only retrieve and update the metadata and description fields on the Payment Intent object. If using both the Payment Intent and Charge objects, youre not guaranteed to see consistent values for these fields.

Stripe supports adding metadata to the most common requests you make, such as processing charges. Metadata isnt shown to customers or factored into whether or not a charge is declined or blocked by our fraud prevention system.

Through metadata, you can associate other informationmeaningful to youwith Stripe activity. Any metadata you include is viewable in the Dashboard (for example, when looking at the page for an individual charge), and is also available in common reports and exports. As an example, your stores order ID can be attached to the charge used to pay for that order. Doing so allows you, your accountant, or your finance team to easily reconcile charges in Stripe to orders in your system.

If youre using Radar, consider passing any additional customer information and order information as metadata. By doing so, you can write Radar rules using metadata attributes and have more information about the payment available within the Dashboard which can expedite your review process.

curl https://api.stripe.com/v1/charges \
  -u sk_test_wU7nrJCZspk1NPDxiQgAF05q: \
  -d "amount"=999 \
  -d "currency"="usd" \
  -d "description"="Example charge" \
  -d "source"="tok_visa" \
  -d "metadata[order_id]"=6735

Declines

If you want your integration to respond to payment failures automatically, you can access a charges outcome in two ways.

• Handle the API error thats returned when a payment fails. For blocked and card issuer-declined payments, the error includes the charges ID, which you can then use to retrieve the charge.
• Use webhooks to monitor status updates. For example, the charge.failed event triggers when a payment is unsuccessful.