Show custom success message

Display a personalized success message or modal to users after their payment completes.

Recipe

Web
Android
iOS

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

  primer.onPaymentSuccess = ({ payment, paymentMethodType }) => {
    const message = `Payment of ${payment.amount} completed via ${paymentMethodType}`;
    showSuccessModal(message);
  };
});

PrimerCheckoutSheet(
    checkout = checkout,
    onEvent = { event ->
        when (event) {
            is PrimerCheckoutEvent.Success -> {
                val payment = event.checkoutData.payment
                Log.d("Checkout", "Payment completed: ${payment.id}")

                navController.navigate("confirmation/${payment.id}") {
                    popUpTo("checkout") { inclusive = true }
                }
            }
            is PrimerCheckoutEvent.Failure -> {
                val error = event.error
                Log.e("Checkout", "Failed: ${error.description}")
                Log.e("Checkout", "Diagnostics: ${error.diagnosticsId}")
            }
        }
    },
)

struct CheckoutView: View {
  let clientToken: String
  @State private var showSuccess = false

  var body: some View {
    ZStack {
      PrimerCheckout(
        clientToken: clientToken,
        onCompletion: { state in
          if case .success = state {
            withAnimation { showSuccess = true }
          }
        }
      )

      if showSuccess {
        SuccessOverlay()
          .transition(.opacity)
      }
    }
  }
}

How it works

Web
Android
iOS

Listen for the primer:ready event to access the Primer SDK instance
Set the onPaymentSuccess callback
Access payment details and paymentMethodType from the callback parameters
Display your custom UI (modal, toast, inline message, etc.)

Use the onEvent callback on PrimerCheckoutSheet or PrimerCheckoutHost
Handle PrimerCheckoutEvent.Success to access PrimerCheckoutData with payment details
Navigate to a confirmation screen or update your order UI

Property	Type	Description
`payment.id`	`String`	The Primer payment ID
`payment.orderId`	`String?`	Your order ID

When using PrimerCheckoutSheet, the SDK shows a default success screen that auto-dismisses after 3 seconds. The Success event fires immediately — you do not need to wait for the dismiss. Navigate as soon as you receive the event.

Use the onCompletion callback on PrimerCheckout
Match on .success to detect payment completion
Access result.payment?.id for the payment ID
Update your SwiftUI state to show a custom success view

Variations

Custom success with payment details

Web
Android
iOS

primer.onPaymentSuccess = ({ payment }) => {
  document.getElementById('success-container').innerHTML = `
    <h2>Thank you for your order!</h2>
    <p>Order ID: ${payment.orderId}</p>
    <p>Amount: ${formatCurrency(payment.amount, payment.currencyCode)}</p>
  `;
};

Display payment details from the Success event:

PrimerCheckoutSheet(
    checkout = checkout,
    onEvent = { event ->
        when (event) {
            is PrimerCheckoutEvent.Success -> {
                val payment = event.checkoutData.payment
                showSuccessScreen(
                    orderId = payment.orderId,
                    paymentId = payment.id,
                )
            }
            is PrimerCheckoutEvent.Failure -> {
                Log.e("Checkout", "Failed: ${event.error.diagnosticsId}")
            }
        }
    },
)

Display payment details from the success result:

PrimerCheckout(
  clientToken: clientToken,
  onCompletion: { state in
    switch state {
    case .success(let result):
      showSuccessScreen(paymentId: result.payment?.id ?? "")
    case .failure(let error):
      print("Failed: \(error.errorId)")
    default:
      break
    }
  }
)

Handle checkout dismissal

Web
Android
iOS

primer.onPaymentSuccess = () => {
  const successEl = document.getElementById('success-message');
  successEl.classList.add('visible');

  // Hide checkout form
  document.querySelector('primer-checkout').style.display = 'none';
};

Use the onDismiss callback to detect when the checkout sheet is closed:

PrimerCheckoutSheet(
    checkout = checkout,
    onEvent = { event -> /* ... */ },
    onDismiss = {
        navController.popBackStack()
    },
)

onDismiss fires after the sheet closes. If you already navigated away in onEvent, guard against double navigation.

Handle the .dismissed case to detect when the user closes the checkout:

PrimerCheckout(
  clientToken: clientToken,
  onCompletion: { state in
    switch state {
    case .success:
      withAnimation { showSuccess = true }
    case .dismissed:
      // User closed the checkout
      break
    default:
      break
    }
  }
)

Redirect after payment

Navigate to a confirmation page after payment

Error handling

Handle payment failures and display error messages

Documentation Index

​Recipe

​How it works

​Variations

​Custom success with payment details

​Handle checkout dismissal

​See also

Redirect after payment

Error handling

Recipe

How it works

Variations

Custom success with payment details

Handle checkout dismissal

See also