First payment - Primer

You’ve installed the SDK. You’re ready to accept payments.

The default payment flow

When a customer reaches your checkout, here’s what happens:

Your server creates a client session and returns a clientToken
The SDK initializes and loads available payment methods
Customer selects a method and enters their details
Customer submits and the SDK processes the payment
Your app receives the result via events

Create a Client Session (Server-Side)

Create a client session on your server using the Client Session API. This returns a clientToken that you pass to your client.

curl -X POST https://api.primer.io/client-session \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-123",
    "currencyCode": "USD",
    "amount": 1000,
    "order": {
      "lineItems": [{
        "itemId": "item-1",
        "description": "Widget",
        "amount": 1000,
        "quantity": 1
      }]
    }
  }'

Initialize and Show Checkout

Web
Android
iOS

<primer-checkout client-token="your-client-token"></primer-checkout>

Listen for payment results:

const checkout = document.querySelector('primer-checkout');

checkout.addEventListener('primer:ready', (event) => {
  const primer = event.detail;

  primer.onPaymentSuccess = ({ payment }) => {
    window.location.href = `/confirmation?order=${payment.orderId}`;
  };

  primer.onPaymentFailure = ({ error }) => {
    console.error('Payment failed:', error.diagnosticsId);
  };
});

PrimerCheckoutSheet(
    checkout = rememberPrimerCheckoutController(
        clientToken = clientToken,
    )
)

import SwiftUI
import PrimerSDK

struct CheckoutView: View {
  let clientToken: String

  var body: some View {
    PrimerCheckout(
      clientToken: clientToken,
      onCompletion: { state in
        switch state {
        case .success(let result):
          // Navigate to confirmation
          print("Payment succeeded: \(result.paymentId)")
        case .failure(let error):
          print("Payment failed: \(error.localizedDescription)")
        case .dismissed:
          print("Checkout was dismissed")
        default:
          break
        }
      }
    )
  }
}

What Primer handles for you

Out of the box, Primer Checkout manages:

Concern	What Primer Does
Validation	Real-time input validation with inline error messages
Error display	Payment failures shown automatically in the UI
Redirects	3DS challenges, bank redirects, and wallet flows
Loading states	Visual feedback during processing
Payment method logic	Each method’s specific requirements and flows

You don’t need to write code for any of these behaviors.

Listening for results

To react to payment outcomes, listen for payment events:

Web
Android
iOS

const checkout = document.querySelector('primer-checkout');

checkout.addEventListener('primer:payment-success', (event) => {
  const { payment } = event.detail;
  window.location.href = `/confirmation?order=${payment.orderId}`;
});

checkout.addEventListener('primer:payment-failure', (event) => {
  const { error } = event.detail;
  // Error is already displayed in the checkout UI
  console.error('Payment failed:', error.diagnosticsId);
});

val state by checkout.state.collectAsStateWithLifecycle()

LaunchedEffect(state) {
    when (val s = state) {
        is PrimerCheckoutState.Success -> {
            val payment = s.checkoutData.payment
            navController.navigate("confirmation/${payment.id}")
        }
        is PrimerCheckoutState.Failure -> {
            Log.e("Checkout", "Failed: ${s.error.diagnosticsId}")
        }
        else -> Unit
    }
}

PrimerCheckoutSheet(checkout = checkout)

PrimerCheckout(
  clientToken: clientToken,
  onCompletion: { state in
    switch state {
    case .success(let result):
      // Navigate to confirmation screen
      print("Payment succeeded: \(result.paymentId)")
    case .failure(let error):
      // Error is already displayed in the checkout UI
      print("Payment failed: \(error.localizedDescription)")
    case .dismissed:
      print("Checkout was dismissed")
    default:
      break
    }
  }
)

State	When it fires
`.success(PaymentResult)`	Payment completed successfully
`.failure(PrimerError)`	Payment failed or error occurred
`.dismissed`	User dismissed the checkout

Testing in sandbox

Use these test cards to verify your integration:

Card Number	Result
`4111 1111 1111 1111`	Success
`4000 0000 0000 0002`	Declined

Use any future expiry date and any 3-digit CVV. Try the Web SDK example in your browser:

Styling

Match the checkout to your brand

Layout

Control the structure of checkout components

Core Concepts

Understand the architecture

Track in Analytics

Send events to your analytics platform

​The default payment flow

​Create a Client Session (Server-Side)

​Initialize and Show Checkout

​What Primer handles for you

​Listening for results

​Testing in sandbox

​See also