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 schemes

Trigger charges from your app or website, pass customer data, and handle callbacks.

Hide products with metadata

Keep online-only products out of the app with a single metadata key.

Integrate with URL schemes

How it works

Your app opens a payment:// URL with parameters

Payment for Stripe launches and processes the transaction

On 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

Name	Type	Required	Description
`amount`	integer	Yes	Amount in cents (e.g., 1000 = $10.00)
`currency`	string	No	Three-letter ISO currency code (default: the app's current currency)
`description`	string	No	URL-encoded charge description
`customer`Alias: `customer_id`	string	No	Existing Stripe customer ID
`email`	string	No	Customer email for receipt
`name`	string	No	URL-encoded customer name
`metadata`	string	No	Custom key-value pairs (URL-encoded JSON)
`callback`	string	No	URL to return to after completion
`autoprocess`Alias: `auto`	boolean	No	Skip home screen and start charge immediately
`auto_return`	boolean	No	Fire 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

Name	Type	Required	Description
`prices`Alias: `line_items`	string	Yes	Comma-separated price IDs with quantities (e.g., price_abc:2,price_xyz:1)
`coupon`	string	No	Stripe coupon ID to apply to the cart
`customer`Alias: `customer_id`	string	No	Existing Stripe customer ID
`email`	string	No	Customer email for receipt
`name`	string	No	URL-encoded customer name
`metadata`	string	No	Custom key-value pairs (URL-encoded JSON)
`callback`	string	No	URL to return to after completion
`autoprocess`Alias: `auto`	boolean	No	Skip home screen and start charge immediately
`auto_return`	boolean	No	Fire 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

Name	Type	Required	Description
`id`	string	Yes	Stripe invoice ID (must start with in_)
`callback`	string	No	URL to return to after completion. Receives invoice_id and payment_intent_id on success.
`metadata`	string	No	Custom key-value pairs (URL-encoded JSON) merged into the PaymentIntent metadata
`autoprocess`Alias: `auto`	boolean	No	Skip home screen and start charge immediately
`auto_return`	boolean	No	Fire 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

Parameter	Values	Description
`status`	success \| error \| cancelled	Result of the transaction
`charge_id`	string	Stripe 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_id`	string	Stripe charge ID (ch_) on success. Android only.
`invoice_id`	string	Stripe invoice ID (on success, payment://invoice flow only)
`payment_intent_id`	string	Stripe PaymentIntent ID (on success). iOS: payment://invoice flow only. Android: every card sale.
`error`	string	Error 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 amount

payment://new?amount=1000

Charge with description

Charge €25.00 with a description

payment://new?amount=2500&currency=eur&description=Coffee%20and%20pastry

Charge with new customer

Charge $50.00 and create a customer record

payment://new?amount=5000&name=John%20Smith&[email protected]

Charge existing customer

Charge $75.00 to an existing Stripe customer

payment://new?amount=7500&customer=cus_ABC123xyz

Charge with metadata

Charge $100.00 with custom metadata for your records

payment://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 done

payment://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 dialog

payment://new?amount=3500&autoprocess=true&auto_return=true&callback=myapp://payment-complete

Cart with line items

Charge for products from your Stripe catalog

payment://cart?prices=price_coffee:2,price_muffin:1&[email protected]

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 flow

payment://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 Encoding

Remember 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 working

Hiding 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 for iOS Download for Android

Contact support