Accept payments in your iOS app, with the store already built.

1. 01

   Create the order on your backend

   POST /v1/orders

   The app sends variant ids and quantities. Flint prices the cart from your catalog and computes the total, so a price is never the app's to choose. Read the order back and send its payment_collection.stripe to the app.

   From your server, with your secret keyCopy

   curl -X POST https://api.withflintpay.com/v1/orders \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: ios-cart-7f3a" \
     -d '{
       "line_items": [
         {
           "type": "variant",
           "variant_id": "var_1kmn0aExample",
           "quantity": 1
         }
       ]
     }'

   Create the product once in the dashboard's catalog. The order is the record every later step settles against.

   GET /v1/orders/{order_id}Copy

   {
     "data": {
       "order_id": "ord_1kmn0aExample",
       "version": 1790760000,
       "settlement_amounts": {
         "outstanding_money": { "amount": 3500, "currency": "USD" }
       },
       "payment_collection": {
         "stripe": {
           "account_id": "acct_1AbcPlaceholder",
           "publishable_key": "pk_test_51AbcPlaceholder",
           "elements": {
             "next_step": "collect_payment_source",
             "amount_money": { "amount": 3500, "currency": "USD" },
             "payment_method_types": ["card"]
           }
         }
       }
     }
   }

   The publishable key and account are for Stripe's SDK and hold no secrets. Keep the balance and version on your server: they are what the buyer approves.

2. 02

   Collect the card in the app

   STPAPIClient.createPaymentMethod

   Stripe's card field takes the number, and one Stripe call turns it into a payment method on the account the order named. The app posts its id to your backend.

   Swift, with Stripe's iOS SDKCopy

   // payment_collection.stripe, as your backend read it
   // from the order. It holds no secrets.
   let stripe = STPAPIClient(publishableKey: collection.publishableKey)
   stripe.stripeAccount = collection.accountId
   
   // cardField is an STPPaymentCardTextField on your checkout screen
   let paymentMethod = try await stripe.createPaymentMethod(
     with: cardField.paymentMethodParams
   )
   
   // your backend pays the Flint order with it
   let result = try await backend.pay(paymentMethodId: paymentMethod.stripeId)

   Card details go from the app to Stripe. Your server and Flint only see the pm_ id.

   Checkout

   

   Single-origin sampler

   Cedar & Stone · qty 1

   $35.00

   Card

   4242 4242 4242 424212/30123

   Stripe’s card field

   Pay $35.00

3. 03

   Pay the order from your backend

   POST /v1/orders/{order_id}/pay

   Your backend sends the payment method as payment_source, with the balance and version the buyer approved. Flint charges it against the order and answers with the payment attempt, whatever the outcome.

   Nodecurl

   The route your app callsCopy

   // the app posts the payment method id it got from Stripe
   app.post("/checkout/pay", async (req, res) => {
     const { paymentMethodId } = req.body;
     // the order id, balance, and version the buyer approved
     const quote = await loadQuote(req.user);
   
     const response = await fetch(
       `https://api.withflintpay.com/v1/orders/${quote.orderId}/pay`,
       {
         method: "POST",
         headers: {
           Authorization: `Bearer ${process.env.FLINT_API_KEY}`,
           "Content-Type": "application/json",
           "Idempotency-Key": `pay-${quote.orderId}-${paymentMethodId}`,
         },
         body: JSON.stringify({
           action: "pay",
           payment_source: { credential_type: "token", token: paymentMethodId },
           expected_outstanding_money: quote.outstandingMoney,
           expected_version: quote.version,
           buyer_contact: { email: quote.buyerEmail },
         }),
       },
     );
     const body = await response.json();
     if (!response.ok) return res.status(response.status).json(body.error);
   
     const attempt = body.data.order_payment_attempt;
     res.json({
       status: attempt.status,
       clientAction: attempt.pending_actions[0]?.client_action?.stripe ?? null,
     });
   });

   Deriving the idempotency key from the order and the payment method makes a retried request safe.

   The app branches on

   • succeeded
   • requires_action
   • failed
   • processing

   A decline comes back as a 200 with a failed attempt and a message you can show the buyer.

   last_payment_error

   On success the order closes as paid and the buyer gets an emailed receipt.

   order.paid

   Declines and payment attempts covers every status and the retry after a decline.

4. 04

   Handle 3D Secure when the bank asks

   requires_action

   The attempt pauses with a pending action that carries a PaymentIntent client secret. The app hands it to Stripe's payment handler, then your backend resumes the same attempt with no new card.

   Swift, with Stripe's iOS SDKCopy

   // result.clientAction is pending_actions[0].client_action.stripe,
   // decoded with snake_case keys converted to camelCase
   let action = result.clientAction!
   let actionClient = STPAPIClient(publishableKey: action.publishableKey)
   actionClient.stripeAccount = action.accountId
   
   let handler = STPPaymentHandler.shared()
   handler.apiClient = actionClient
   _ = await handler.handleNextAction(
     paymentIntentClientSecret: action.paymentIntent.clientSecret,
     authenticationContext: self,
     returnURL: nil
   )
   
   // resume even after an error: Flint reads the outcome from Stripe
   let resumed = try await backend.resume()

   Pass the client secret only to handleNextAction. Resume from your backend and read the outcome there.

   PauseResume

   What the pay call returnsCopy

   {
     "order_payment_attempt": {
       "order_payment_attempt_id": "opat_1kmn0aExample",
       "status": "requires_action",
       "is_resumable": true,
       "pending_actions": [
         {
           "action_type": "payment_authentication",
           "client_action": {
             "stripe": {
               "account_id": "acct_1AbcPlaceholder",
               "publishable_key": "pk_test_51AbcPlaceholder",
               "payment_intent": {
                 "stripe_js_call": "handle_next_action",
                 "client_secret": "pi_3AbcPlaceholder_secret_XyzPlaceholder"
               }
             }
           }
         }
       ]
     }
   }

   Your backend sends client_action.stripe to the app.

Sales tax is calculated on the order when you turn it on, from the buyer’s location; sales tax covers locations and categories. Subscriptions suit goods and services delivered outside the app, such as a coffee club or a membership; see subscription billing.