Samsung Pay

Client-Side Implementation

availability
Samsung Pay is currently available to US merchants.

important
The SSL certificates for all Braintree SDKs are set to expire by June 30, 2025. This will impact existing versions of the SDK in published versions of your app. To reduce the impact, upgrade the Android SDK to version 4.45.0+ or version 5.0.0+ for the new SSL certifications.
If you do not decommission your app versions that include the older SDK versions or force upgrade your app with the updated certificates by the expiration date, 100% of your customer traffic will fail.

Get the SDK

Add the following in your app-level build.gradle:

Groovy

dependencies {
  implementation 'com.braintreepayments.api:samsung-pay:4.39.0'
}

Samsung Pay is only available on Samsung devices with Android 6.0 (API level 23) and above.

Integration

Prepare Samsung Pay button assets

note
Click here to download Samsung's brand guidelines, and be sure to follow them when configuring the Samsung Pay button.

Add a Samsung Pay button to your app to let users select Samsung Pay as their payment method. Depending on your app's theme you can select the appropriate button assets. Click here to download Samsung's button assets.

Add the Samsung Pay assets you wish to use to your drawable resources.

Initialization

To get started with Samsung Pay:

Use a tokenization key or get a client token from your server
Initialize a BraintreeClient
Initialize a SamsungPayClient

Before showing the Samsung Pay button, use the SamsungPayClient#isReadyToPay method to check whether the user's current device is compatible.

Kotlin

class MyActivity: AppCompatActivity(), SamsungPayListener {

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    braintreeClient = BraintreeClient(this, ExampleClientTokenProvider())
    samsungPayClient = SamsungPayClient(braintreeClient)
  }

  private fun checkIfSamsungPayIsAvailable() {
    samsungPayClient.isReadyToPay() { isReadyToPay, error ->
      if (isReadyToPay) {
        // Samsung Pay is available 
      } else {
        // handle error 
      }
    }
  }
}

Java

public class MyActivity extends AppCompatActivity implements SamsungPayListener {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    braintreeClient = new BraintreeClient(this, new ExampleClientTokenProvider());
    samsungPayClient = new SamsungPayClient(braintreeClient);
  }

  private void checkIfSamsungPayIsAvailable() {
    samsungPayClient.isReadyToPay((isReadyToPay, error) -> {
      if (isReadyToPay) {
        // Samsung Pay is available 
      } else {
        // handle error 
      }
    });
  }
}

Build payment info

Samsung Pay lets you tailor both billing address and shipping address in the Samsung Pay UI. The following example demonstrates how to build a CustomSheet:

Kotlin

class MyActivity: AppCompatActivity(), SamsungPayListener {

  private fun getCustomSheet(): CustomSheet {
    val sheet = CustomSheet()

    val billingAddressControl = AddressControl("billingAddressId", SheetItemType.BILLING_ADDRESS)
    billingAddressControl.addressTitle = "Billing Address"
    billingAddressControl.sheetUpdatedListener = { controlId, customSheet ->
      samsungPayClient.updateCustomSheet(customSheet)
    }
    sheet.addControl(billingAddressControl)

    val shippingAddressControl = AddressControl("shippingAddressId", SheetItemType.SHIPPING_ADDRESS)
    shippingAddressControl.addressTitle = "Shipping Address"
    shippingAddressControl.sheetUpdatedListener = { controlId, customSheet ->
      samsungPayClient.updateCustomSheet(customSheet)
    }
    sheet.addControl(shippingAddressControl)

    val amountBoxControl = AmountBoxControl("amountID", "USD")
    amountBoxControl.amountTotal(1.0, AmountConstants.FORMAT_TOTAL_PRICE_ONLY)
    sheet.addControl(amountBoxControl)

    return sheet
  }
}

Java

public class MyActivity extends AppCompatActivity implements SamsungPayListener {

  private CustomSheet getCustomSheet() {
    CustomSheet sheet = new CustomSheet();

    final AddressControl billingAddressControl = new AddressControl("billingAddressId", SheetItemType.BILLING_ADDRESS);
    billingAddressControl.setAddressTitle("Billing Address");
    billingAddressControl.setSheetUpdatedListener((controlId, customSheet) -> {
      samsungPayClient.updateCustomSheet(customSheet);
    });
    sheet.addControl(billingAddressControl);

    final AddressControl shippingAddressControl = new AddressControl("shippingAddressId", SheetItemType.SHIPPING_ADDRESS);
    shippingAddressControl.setAddressTitle("Shipping Address");
    shippingAddressControl.setSheetUpdatedListener((controlId, customSheet) -> {
      samsungPayClient.updateCustomSheet(customSheet);
    });
    sheet.addControl(shippingAddressControl);

    AmountBoxControl amountBoxControl = new AmountBoxControl("amountID", "USD");
    amountBoxControl.setAmountTotal(1.0, AmountConstants.FORMAT_TOTAL_PRICE_ONLY);
    sheet.addControl(amountBoxControl);

    return sheet;
  }
}

Start Samsung Pay

Use SamsungPayClient#buildCustomSheetPaymentInfo to access the CustomSheetPaymentInfo.Builder instance to add your custom sheet with additional properties.

Once the PaymentInfo is built, start Samsung Pay with SamsungPayClient#startSamsungPay. Implement SamsungPayListener to receive results from the SDK.

Kotlin

class MyActivity: AppCompatActivity(), SamsungPayListener {

  private fun launchSamsungPay() {
    samsungPayClient.buildCustomSheetPaymentInfo() { builder, error ->
      builder?.let {
        val paymentInfo = builder
            .setAddressInPaymentSheet(CustomSheetPaymentInfo.AddressInPaymentSheet.NEED_BILLING_AND_SHIPPING)
            .setCustomSheet(getCustomSheet())
            .setOrderNumber("order-number")
            .build()
        samsungPayClient.startSamsungPay(paymentInfo, this@MyActivity)
      }

      error?.let {
        // handle error
      }
    }
  }

  override fun onSamsungPayStartError(error: Exception) {
    // handle samsung pay start error
  }

  override fun onSamsungPayStartSuccess(samsungPayNonce: SamsungPayNonce, customSheetPaymentInfo: CustomSheetPaymentInfo) {
    // send samsungPayNonce.string to server to create a transaction

    // access the payment info's custom sheet for information given by Samsung Pay
    val customSheet = paymentInfo.customSheet
  }

  override fun onSamsungPayCardInfoUpdated(cardInfo: CardInfo, customSheet: CustomSheet) {
    // called when the user selects a payment method; this method can be used to update pricing on the sheet
    samsungPayClient.updateCustomSheet(customSheet)
  }
}

Java

public class MyActivity extends AppCompatActivity implements SamsungPayListener {
  private void launchSamsungPay() {
    samsungPayClient.buildCustomSheetPaymentInfo((builder, error) -> {
      if (builder != null) {
        CustomSheetPaymentInfo paymentInfo = builder
            .setAddressInPaymentSheet(CustomSheetPaymentInfo.AddressInPaymentSheet.NEED_BILLING_AND_SHIPPING)
            .setCustomSheet(getCustomSheet())
            .setOrderNumber("order-number")
            .build();
        samsungPayClient.startSamsungPay(paymentInfo, MyActivity.this);
      } else {
        // handle error
      }
    });
  }

  @Override
  public void onSamsungPayStartError(@NonNull Exception error) {
    // handle samsung pay start error
  }

  @Override
  public void onSamsungPayStartSuccess(@NonNull SamsungPayNonce samsungPayNonce, @NonNull CustomSheetPaymentInfo paymentInfo) {
    // send samsungPayNonce.getString() to server to create a transaction

    // access the payment info's custom sheet for information given by Samsung Pay
    CustomSheet customSheet = paymentInfo.getCustomSheet();
  }

  @Override
  public void onSamsungPayCardInfoUpdated(@NonNull CardInfo cardInfo, @NonNull CustomSheet customSheet) {
    // called when the user selects a payment method; this method can be used to update pricing on the sheet
    samsungPayClient.updateCustomSheet(customSheet);
  }
}

Full example

A complete example of an integration between Braintree and Samsung Pay shows you how to get started and provides a handy reference for your integration project.

Kotlin

class MyActivity: AppCompatActivity(), SamsungPayListener {

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    braintreeClient = BraintreeClient(this, "<#CLIENT_AUTHORIZATION#>")
    samsungPayClient = SamsungPayClient(braintreeClient)
  }

  private fun getCustomSheet(): CustomSheet {
    val sheet = CustomSheet()

    val billingAddressControl = AddressControl("billingAddressId", SheetItemType.BILLING_ADDRESS)
    billingAddressControl.addressTitle = "Billing Address"
    billingAddressControl.sheetUpdatedListener = { controlId, customSheet ->
      samsungPayClient.updateCustomSheet(customSheet)
    }
    sheet.addControl(billingAddressControl)

    val shippingAddressControl = AddressControl("shippingAddressId", SheetItemType.SHIPPING_ADDRESS)
    shippingAddressControl.addressTitle = "Shipping Address"
    shippingAddressControl.sheetUpdatedListener = { controlId, customSheet ->
      samsungPayClient.updateCustomSheet(customSheet)
    }
    sheet.addControl(shippingAddressControl)

    val amountBoxControl = AmountBoxControl("amountID", "USD")
    amountBoxControl.amountTotal(1.0, AmountConstants.FORMAT_TOTAL_PRICE_ONLY)
    sheet.addControl(amountBoxControl)

    return sheet
  }

  private fun launchSamsungPay() {
    samsungPayClient.buildCustomSheetPaymentInfo() { builder, error ->
      builder?.let {
        val paymentInfo = builder
            .setAddressInPaymentSheet(CustomSheetPaymentInfo.AddressInPaymentSheet.NEED_BILLING_AND_SHIPPING)
            .setCustomSheet(getCustomSheet())
            .setOrderNumber("order-number")
            .build()
        samsungPayClient.startSamsungPay(paymentInfo, this@MyActivity)
      }

      error?.let {
        // handle error
      }
    }
  }

  override fun onSamsungPayStartError(error: Exception) {
    // handle samsung pay start error
  }

  override fun onSamsungPayStartSuccess(samsungPayNonce: SamsungPayNonce, customSheetPaymentInfo: CustomSheetPaymentInfo) {
    // send samsungPayNonce.string to server to create a transaction

    // access the payment info's custom sheet for information given by Samsung Pay
    val customSheet = paymentInfo.customSheet
  }

  override fun onSamsungPayCardInfoUpdated(cardInfo: CardInfo, customSheet: CustomSheet) {
    // called when the user selects a payment method; this method can be used to update pricing on the sheet
    samsungPayClient.updateCustomSheet(customSheet)
  }
}

Java

public class MyActivity extends AppCompatActivity implements SamsungPayListener {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    braintreeClient = new BraintreeClient(this, "<#CLIENT_AUTHORIZATION#>");
    samsungPayClient = new SamsungPayClient(braintreeClient);
  }

  private void checkIfSamsungPayIsAvailable() {
    samsungPayClient.isReadyToPay((isReadyToPay, error) -> {
      if (isReadyToPay) {
        // Samsung Pay is available 
      } else {
        // handle error 
      }
    });
  }

  private CustomSheet getCustomSheet() {
    CustomSheet sheet = new CustomSheet();

    final AddressControl billingAddressControl = new AddressControl("billingAddressId", SheetItemType.BILLING_ADDRESS);
    billingAddressControl.setAddressTitle("Billing Address");
    billingAddressControl.setSheetUpdatedListener((controlId, customSheet) -> {
      samsungPayClient.updateCustomSheet(customSheet);
    });
    sheet.addControl(billingAddressControl);

    final AddressControl shippingAddressControl = new AddressControl("shippingAddressId", SheetItemType.SHIPPING_ADDRESS);
    shippingAddressControl.setAddressTitle("Shipping Address");
    shippingAddressControl.setSheetUpdatedListener((controlId, customSheet) -> {
      samsungPayClient.updateCustomSheet(customSheet);
    });
    sheet.addControl(shippingAddressControl);

    AmountBoxControl amountBoxControl = new AmountBoxControl("amountID", "USD");
    amountBoxControl.setAmountTotal(1.0, AmountConstants.FORMAT_TOTAL_PRICE_ONLY);
    sheet.addControl(amountBoxControl);

    return sheet;
  }

  private void launchSamsungPay() {
    samsungPayClient.buildCustomSheetPaymentInfo((builder, error) -> {
      if (builder != null) {
        CustomSheetPaymentInfo paymentInfo = builder
            .setAddressInPaymentSheet(CustomSheetPaymentInfo.AddressInPaymentSheet.NEED_BILLING_AND_SHIPPING)
            .setCustomSheet(getCustomSheet())
            .setOrderNumber("order-number")
            .build();
        samsungPayClient.startSamsungPay(paymentInfo, MyActivity.this);
      } else {
        // handle error
      }
    });
  }

  @Override
  public void onSamsungPayStartError(@NonNull Exception error) {
    // handle samsung pay start error
  }

  @Override
  public void onSamsungPayStartSuccess(@NonNull SamsungPayNonce samsungPayNonce, @NonNull CustomSheetPaymentInfo paymentInfo) {
    // send samsungPayNonce.getString() to server to create a transaction

    // access the payment info's custom sheet for information given by Samsung Pay
    CustomSheet customSheet = paymentInfo.getCustomSheet();
  }

  @Override
  public void onSamsungPayCardInfoUpdated(@NonNull CardInfo cardInfo, @NonNull CustomSheet customSheet) {
    // called when the user selects a payment method; this method can be used to update pricing on the sheet
    samsungPayClient.updateCustomSheet(customSheet);
  }
}

Next Page: Server-side →