Skip to content
Developer API

Integrate and customize

Launch Payment for Stripe from your own app or website with URL schemes, and control which products appear in the app right from your Stripe Dashboard.
Integrate with URL schemesTrigger charges from your app or website, pass customer data, and handle callbacks.Hide products with metadataKeep online-only products out of the app with a single metadata key.
Integrate with URL schemes

How it works

  1. 1Your app opens a payment:// URL with parameters
  2. 2Payment for Stripe launches and processes the transaction
  3. 3On completion, the app redirects to your callback URL with the result

Endpoints

Create a Charge

payment://new?Process a one-time payment with amount, currency, and description.

Parameters

  • amountintegerRequiredAmount in cents (e.g., 1000 = $10.00)
  • currencystringThree-letter ISO currency code (default: the app's current currency)
  • descriptionstringURL-encoded charge description
  • customerstringAlias: customer_idExisting Stripe customer ID
  • emailstringCustomer email for receipt
  • namestringURL-encoded customer name
  • metadatastringCustom key-value pairs (URL-encoded JSON)
  • callbackstringURL to return to after completion
  • autoprocessbooleanAlias: autoSkip home screen and start charge immediately
  • auto_returnbooleanFire callback when result loads instead of waiting for the merchant to dismiss the result dialog. Default false.

Sell Items from Your Catalog

payment://cart?Fill the cart with prices from your Stripe catalog for an in-person charge. The sale is saved as a paid Stripe invoice. Nothing is sent to the customer.

Parameters

  • pricesstringRequiredAlias: line_itemsComma-separated price IDs with quantities (e.g., price_abc:2,price_xyz:1)
  • couponstringStripe coupon ID to apply to the cart
  • customerstringAlias: customer_idExisting Stripe customer ID
  • emailstringCustomer email for receipt
  • namestringURL-encoded customer name
  • metadatastringCustom key-value pairs (URL-encoded JSON)
  • callbackstringURL to return to after completion
  • autoprocessbooleanAlias: autoSkip home screen and start charge immediately
  • auto_returnbooleanFire callback when result loads instead of waiting for the merchant to dismiss the result dialog. Default false.

Pay an Existing Invoice

payment://invoice?Collect an in-person payment against an existing Stripe invoice. Amount, currency, customer, and tax come from the invoice. Overriding any of those is rejected. The merchant taps a card via reader / Tap to Pay / manual entry; on success the invoice is marked paid out-of-band and linked via charge_id and payment_intent_id metadata. Invoices with subscriptions, default_payment_method, or a paid, void, or uncollectible status are rejected with an actionable error. Draft invoices: iOS finalizes them first, Android rejects them with invoice_state_changed.

Parameters

  • idstringRequiredStripe invoice ID (must start with in_)
  • callbackstringURL to return to after completion. Receives invoice_id and payment_intent_id on success.
  • metadatastringCustom key-value pairs (URL-encoded JSON) merged into the PaymentIntent metadata
  • autoprocessbooleanAlias: autoSkip home screen and start charge immediately
  • auto_returnbooleanFire callback when result loads instead of waiting for the merchant to dismiss the result dialog. Default false.

Handling callbacks

When the transaction completes, Payment for Stripe redirects to your callback URL with query parameters indicating the result. By default the redirect fires after the merchant dismisses the result dialog so they can take post-charge actions (email a receipt, refund). Pass auto_return=true to fire as soon as the result is known. Supported on iOS and Android.

Callback Parameters

  • statussuccess | error | cancelledResult of the transaction
  • charge_idstringStripe charge ID (on success). iOS sends the charge ID (ch_). Android sends the PaymentIntent ID (pi_) and puts the charge ID in stripe_charge_id.
  • stripe_charge_idstringStripe charge ID (ch_) on success. Android only.
  • invoice_idstringStripe invoice ID (on success, payment://invoice flow only)
  • payment_intent_idstringStripe PaymentIntent ID (on success). iOS: payment://invoice flow only. Android: every card sale.
  • errorstringError message (on error)
Charge captured but the invoice could not be marked paid: iOS returns status=error with charge_id, invoice_id, and payment_intent_id. Android returns status=success with invoice_reconciliation_failed=true.Legacy fields, kept for older integrations: success, amount, currency, chargeId, cancelled, error[message]. New integrations should read the fields above.

Examples

  • Simple charge

    Charge $10.00 with just an amountpayment://new?amount=1000

  • Charge with description

    Charge €25.00 with a descriptionpayment://new?amount=2500&currency=eur&description=Coffee%20and%20pastry

  • Charge with new customer

    Charge $50.00 and create a customer recordpayment://new?amount=5000&name=John%20Smith&email=john@example.com

  • Charge existing customer

    Charge $75.00 to an existing Stripe customerpayment://new?amount=7500&customer=cus_ABC123xyz

  • Charge with metadata

    Charge $100.00 with custom metadata for your recordspayment://new?amount=10000&description=Invoice%20%231234&metadata=%7B%22order_id%22%3A%221234%22%2C%22location%22%3A%22Store%20A%22%7D

  • Auto-process with callback

    Skip the home screen and return to your app when donepayment://new?amount=3500&autoprocess=true&callback=myapp://payment-complete

  • Auto-return on result

    Fire the callback as soon as the result is known, instead of waiting for the merchant to dismiss the result dialogpayment://new?amount=3500&autoprocess=true&auto_return=true&callback=myapp://payment-complete

  • Cart with line items

    Charge for products from your Stripe catalogpayment://cart?prices=price_coffee:2,price_muffin:1&email=customer@example.com

  • Pay an existing invoice

    Collect in-person payment for an existing Stripe invoice. Returns invoice_id and payment_intent_id on success.payment://invoice?id=in_1ABC123xyz&autoprocess=true&callback=myapp://invoice-paid

  • Complete example

    All parameters combined for a fully integrated flowpayment://new?amount=15000&currency=usd&description=Service%20Fee&customer=cus_ABC123xyz&metadata=%7B%22invoice%22%3A%22INV-2024-001%22%7D&autoprocess=true&callback=myapp://payment-result
URL EncodingRemember to URL-encode special characters in parameter values. Spaces become %20, curly braces become %7B and %7D.
Hide products with metadata

Hiding products from the app

The app lists the products and prices from your Stripe account. To keep one out of the app (for example, items sold only through your online store), add this metadata key to the product or price in the Stripe Dashboard:payment_hidden = true
  • On a product: hides the product and all of its prices.
  • On a price: hides only that price.
  • Remove the key, or set it to false, to show it again. Changes apply the next time the app loads your product list.
Cart links keep workingHiding only affects the product list inside the app. payment://cart URLs that reference a hidden price still work, and existing subscriptions are unaffected.

Ready to integrate?

Download the app and start testing your integration today.
Download free (iOS)Contact support