JavaScript objects

The following objects define the input and output structures used by the Web Checkout SDK:

• PaymentMethods
• TransactionDetail
• ModalOptions
• PaymentCredential
• PaymentResult

PaymentMethods

The PaymentMethods object defines the payment methods supported by the merchant.

Field	Type	Required/Optional	Description
version	String	Required	Samsung Pay API version to use. The supported value is 2.
serviceId	String	Required	Unique service ID created during onboarding with Samsung.
protocol	String	Required	Payment protocol used for processing payments. The supported value is PROTOCOL_3DS.
allowedBrands	Array<string>	Required	Array of supported card brands. The possible values are: visa mastercard amex discover elo mada cb jaywan
isRecurring	Boolean	Optional	Whether the payment is a recurring transaction. The default value is false.
isBillingAddressRequired	Boolean	Optional	Whether the billing address must be included in the payment credentials. The default value is false.
isCardholderNameRequired	Boolean	Optional	Whether the cardholder name must be included in the payment credentials. The default value is false.
isCpfCardRequired	Boolean	Optional	Whether the cardholder’s CPF (Brazilian taxpayer ID) must be included in the payment credentials. The default value is false.
merchantChoiceBrands	Object	Optional	Configuration that defines how the payment sheet displays co-badged cards.
merchantChoiceBrands.type	String	Required	Selection behavior for co-badged brands on the payment sheet. The possible values are: MANDATORY: Only the brands defined in merchantChoiceBrands.brands can be used. PREFERENCE: The brands defined in merchantChoiceBrands.brands are pre-selected, but the customer can change the selection.
merchantChoiceBrands.brands	Array<string>	Required	Array of supported brands for co-badged cards. The possible values are: mada cb
extraPaymentInfo	Array<object>	Optional	Additional features supported by the merchant.
extraPaymentInfo.id	String	Required	Additional feature ID. The possible values are: COMBOCARD: Combo Card DSRP: Digital Secure Remote Payment
extraPaymentInfo.type	String	Optional	Feature type when extraPaymentInfo.id is set to DSRP. The possible values are: UCAF: Universal Cardholder Authentication Field ICC: Integrated Circuit Card The default value is UCAF.

TransactionDetail

The TransactionDetail object contains the transaction information for the customer's purchase.

Field	Type	Required/Optional	Description
orderNumber	String	Required	Order number for the transaction. The allowed characters are: [A-Z][a-z][0-9,-].
merchant	Object	Required	Merchant information for the transaction.
merchant.name	String	Required	Merchant name.
merchant.url	String	Required	Merchant website domain URL. The maximum length is 100 characters.
merchant.id	String	Conditional	Unique ID, known as the merchant ID, that is assigned by the payment gateway (PG) during partner onboarding. The ID is required: If the merchant has been onboarded with Samsung by their PG. When the payment token's brand is mada or when mada is included in merchantChoiceBrands.brands. The maximum length is 15 characters for mada token brands and 45 characters for all other cases.
merchant.countryCode	String	Required	Merchant country code in the ISO 3166-1 alpha-2 format.
amount	Object	Required	Payment amount and related display settings.
amount.option	String	Required	Display format for the total amount on the payment sheet. The possible values are: FORMAT_TOTAL_ESTIMATED_AMOUNT: Displays "Total (Estimated amount)" followed by the amount. FORMAT_TOTAL_PRICE_ONLY: Displays only the total amount.
amount.currency	String	Required	Currency code for the transaction in the ISO 4217 alphabetic code standard format; for example, USD or KRW.
amount.total	String	Required	Total amount to charge, expressed in the currency specified by amount.currency. The amount must be an integer (for example, 300) or a valid decimal format appropriate for the currency (for example, 300.50).
type	String	Optional	Transaction type. Supported only for mada token transactions and ignored for other token types. The possible values are: PURCHASE PREAUTHORIZATION The default value is PURCHASE.
paymentTabs	Array<string>	Optional	Array of payment tabs to display; for example, CREDIT_CARD or DEBIT_CARD.

ModalOptions

The ModalOptions object contains modal layout settings for displaying the payment sheet on the desktop. If omitted, default values are used.

Field	Type	Required/Optional	Description
margin	Object	Optional	Margins for the modal window.
margin.top	String	Optional	Top margin for the modal window. The default value is "5%".
margin.left	String	Optional	Left margin for the modal window. The default value is "auto".
margin.bottom	String	Optional	Bottom margin for the modal window. The default value is "5%".
margin.right	String	Optional	Right margin for the modal window. The default value is "auto".

PaymentCredential

The PaymentCredential object contains the payment credential details generated on the customer's mobile device through Samsung Wallet.

Field	Type	Required/Optional	Description
card_brand	String	Required	Brand of the payment card used for the transaction.
card_last4digits	String	Required	Last 4 digits of the card number.
3DS	Object	Required	3D Secure (3DS) authentication data generated for the transaction.
3DS.type	String	Optional	3DS type. The value is S for Samsung Pay.
3DS.version	String	Required	3DS version. The supported value is 100.
3DS.data	String	Required	Encrypted payment credential data in JWE format.
recurring_payment	Boolean	Optional	Whether the payment credential can be used for recurring payments. The default value is false.
encryptedMessage	String	Conditional	Encrypted string (in JWE format) that contains the billing address, cardholder name, and CPF (Brazilian taxpayer ID) information (when required). The value can be decrypted using the same method as for the 3DS.data value.
encryptedMessage.billingAddress	Object	Conditional	Billing address details.
encryptedMessage.billingAddress.addressLine1	String	Required	First line of the billing address.
encryptedMessage.billingAddress.addressLine2	String	Optional	Second line of the billing address.
encryptedMessage.billingAddress.city	String	Required	City of the billing address.
encryptedMessage.billingAddress.state	String	Conditional	State or province of the billing address. This field is required only when billingAddress.countryCode is USA or CAN.
encryptedMessage.billingAddress.countryCode	String	Required	Country code of the billing address in the ISO 3166-1 alpha-3 format.
encryptedMessage.billingAddress.postalCode	String	Required	Postal code of the billing address.
encryptedMessage.cardholderName	String	Conditional	Cardholder name.
encryptedMessage.cpf	Object	Conditional	Brazilian CPF information.
encryptedMessage.cpf.name	String	Required	Full name of the individual associated with the CPF.
encryptedMessage.cpf.number	String	Required	Brazilian CPF number. The value contains 11 digits with no hyphens or dots.

PaymentResult

The PaymentResult object contains the result of the payment after the payment gateway has processed it.

Field	Type	Required/Optional	Description
status	String	Required	Payment status. The possible values are: CHARGED: Payment was successfully completed. CANCELLED: Payment was cancelled by the customer, merchant, or acquirer. REJECTED: Payment was rejected by the acquirer. ERRED: Error occurred during payment processing.
provider	String	Optional	Name of the payment gateway that processed the payment.