Create a custom payment sheet for a transaction request

To manage the customer's payment through Samsung Pay, you must create a custom payment sheet that displays the payment details and allows the customer to select their card, define their shipping and billing address, and authorize the payment.

Custom payment sheet structure

The following code snippet shows the structure of the CustomSheetPaymentInfo class:

Samsung Pay SDK for Android:

class CustomSheetPaymentInfo : Parcelable {
    private val version: String? = null
    private val merchantId: String? = null
    private val merchantName: String? = null
    private val orderNumber: String? = null
    private val addressInPaymentSheet: AddressInPaymentSheet = AddressInPaymentSheet.DO_NOT_SHOW
    private val allowedCardBrand: List<SpaySdk.Brand>? = null
    private val cardInfo: CardInfo? = null
    private val isCardHolderNameRequired = false
    private val isRecurring = false
    private val merchantCountryCode: String? = null
    private val customSheet: CustomSheet? = null
    private val extraPaymentInfo: Bundle? = null
}

Samsung Pay SDK for Flutter:

String? merchantId;
String merchantName;
String? orderNumber;
AddressInPaymentSheet? addressInPaymentSheet;
List<Brand>? allowedCardBrand;
PaymentCardInfo? cardInfo;
bool? isCardHolderNameRequired;
bool? isRecurring;
String? merchantCountryCode;
CustomSheet customSheet;
Map<String,dynamic>? extraPaymentInfo;

The purpose of the CustomSheetPaymentInfo instance is both to display the payment details to the customer for their approval and to receive the final payment data from Samsung Pay after the customer has authorized the payment.

To initiate a payment transaction and display the payment details to the customer, populate the custom payment sheet fields, as defined in the following table.

Field/Data	Required/Optional	Description
merchantName	Required	Your name, as it will appear in Samsung Pay’s payment sheet as well as the customer's card account statement
merchantId	Optional	Your payment gateway (PG) ID as defined in the Samsung Pay Portal. If your PG uses direct network tokens, this field can be used for your designated purposes and you can define the value at your discretion. The merchant ID is mandatory for purchases with a MADA card.
orderNumber	Optional	Order number, required for refunds and chargebacks. For Visa cards, the value is mandatory. The value is usually created in interaction with a PG. The value has the allowed characters [A-Z][a-z][0-9,-] with the maximum length of 36 characters.
Address	Optional	Customer's billing and/or shipping address, defined with dynamic payment sheet controls.
allowedCardBrand	Optional	List of card brands you support. If none are specified, all brands are accepted by default. If at least one brand is specified, all non-specified card brands are set to "card not supported" on the payment sheet.

Custom payment sheet controls

In addition to the static fields, the custom payment sheet contains dynamic controls that you can use to modify the sheet details during the payment process. The details can be modified by your app, the customer, or Samsung Pay. The following details, for example, are provided as dynamic controls:

• Amount, containing the currency, item price, shipping price, tax, and total price that together make up the amount the customer is agreeing to pay you. The amount control is required.
• Address, containing the customer's billing and/or shipping address. The address control is optional.

The following code snippet is an example of using the amount control. For more information on using dynamic controls, see Samsung Pay SDK for Android sample app.

Samsung Pay SDK for Android:

fun makeAmountControl(): AmountBoxControl {
    val amountBoxControl = AmountBoxControl(AMOUNT_CONTROL_ID, "USD")
    amountBoxControl.addItem(PRODUCT_ITEM_ID, "Item", 1000.0, "")
    amountBoxControl.addItem(PRODUCT_TAX_ID, "Tax", 50.0, "")
    amountBoxControl.addItem(PRODUCT_SHIPPING_ID, "Shipping", 10.0, "")
    amountBoxControl.setAmountTotal(1060.0, AmountConstants.FORMAT_TOTAL_PRICE_ONLY)
    amountBoxControl.addItem(3, PRODUCT_FUEL_ID, "Fuel", 0.0, "Pending")
    return amountBoxControl
}

Samsung Pay SDK for Flutter:

    AmountBoxControl

Populate custom payment sheet

The following code snippet is an example of populating the CustomSheetPaymentInfo object.

Samsung Pay SDK for Android:

/*
 * Create the customer's transaction details.
 * Your app should send CustomSheetPaymentInfo to the Samsung Wallet app using
 * the applicable Samsung Pay SDK for Android method for the operation being invoked.
 */
private fun makeCustomSheetPaymentInfo(): CustomSheetPaymentInfo {
    val brandList = ArrayList<SpaySdk.Brand>()
    // If the supported brand is not specified, all card brands in the Samsung Wallet app are
    // listed in the Payment Sheet
    brandList.add(PaymentManager.Brand.VISA)
    brandList.add(PaymentManager.Brand.MASTERCARD)
    brandList.add(PaymentManager.Brand.AMERICANEXPRESS)
    /*
     * Create the SheetControls you want and add them to custom sheet.
     * Place each control in sequence, with AmountBoxControl listed last.
     */
    val customSheet = CustomSheet()
    customSheet.addControl(makeBillingAddressControl())
    customSheet.addControl(makeShippingAddressControl())
    customSheet.addControl(makePlainTextControl())
    customSheet.addControl(makeShippingMethodSpinnerControl())
    customSheet.addControl(makeAmountControl())
    val extraPaymentInfo = Bundle()
    /*
     * You can add TransactionType for the MADA card brand.
     * The supported values are PURCHASE and PREAUTHORIZATION.
     * If you do not set any value, the default value is PURCHASE.
     */
    extraPaymentInfo.putString(SpaySdk.EXTRA_ONLINE_TRANSACTION_TYPE,
        SpaySdk.TransactionType.PREAUTHORIZATION.toString())

    val customSheetPaymentInfo = CustomSheetPaymentInfo.Builder()
        .setMerchantId("123456")
        .setMerchantName("Sample Merchant")
        // Merchant requires billing address from the Samsung Wallet app and
        // sends the shipping address to the Samsung Wallet app.
        // Show both billing and shipping address on the payment sheet.
        .setAddressInPaymentSheet(CustomSheetPaymentInfo.AddressInPaymentSheet.NEED_BILLING_SEND_SHIPPING)
        .setAllowedCardBrands(brandList)
        .setCardHolderNameEnabled(true)
        .setRecurringEnabled(false)
        .setCustomSheet(customSheet)
        .setExtraPaymentInfo(extraPaymentInfo)
        .build()
    return customSheetPaymentInfo
}

Samsung Pay SDK for Flutter:

    List<Brand> brandList = [];
    brandList.add(Brand.VISA);
    brandList.add(Brand.MASTERCARD);
    brandList.add(Brand.AMERICANEXPRESS);

    CustomSheetPaymentInfo customSheetPaymentInfo= CustomSheetPaymentInfo(merchantName:"merchantName", customSheet: customSheet);
    customSheetPaymentInfo.setMerchantId("123456");
    customSheetPaymentInfo.setMerchantName("Sample Merchant");
    customSheetPaymentInfo.setAddressInPaymentSheet(AddressInPaymentSheet.NEED_BILLING_SEND_SHIPPING);
    customSheetPaymentInfo.setCardHolderNameEnabled(true);
    customSheetPaymentInfo.setRecrringEnabled(false);
    customSheetPaymentInfo.setCustomSheet(customSheet);
    customSheetPaymentInfo.allowedCardBrand = brandList;
  return customSheetPaymentInfo;