API Reference

This page describes the data structures used in the Samsung Pay Web Checkout API integration.

PaymentMethods

The PaymentMethods object defines the payment methods that the merchant supports.

Key
 Type Required Description
version

 String Required Samsung Pay API version
The supported value is 2.
serviceId

 String Required Merchant ID that is assigned after onboarding
protocol

 String Required Payment protocol type
The supported value is PROTOCOL_3DS.
allowedBrands

 List<String> Required List of supported card brands
The possible values are:
  • visa
  • mastercard
  • amex
  • discover
  • mada
  • cb
merchantChoiceBrands

 Object Optional Data structure containing configuration information for a co-badged card
merchantChoiceBrands.type

 String Required Co-badged card display option for the payment sheet
The possible values are:
  • MANDATORY = Only the brand defined in merchantChoiceBrands.brands is enabled
  • PREFERENCE = The brand defined in merchantChoiceBrands.brands is selected by default but the user can change it
merchantChoiceBrands.brands

 List<String> Required List of supported brands for the co-badged card
The possible values are:
  • mada
  • cb
extraPaymentInfo

 Object Optional Data structure containing additional supported features
extraPaymentInfo.id

 String Required Feature ID for the additional feature
The possible values are:
  • COMBOCARD = Combo Card
  • DSRP = Digital Secure Remote Payment
extraPaymentInfo.type

 String Optional Feature type, if the value of extraPaymentInfo.id is DSRP
The possible values are:
  • UCAF = Universal Cardholder Authentication Field
  • ICC = Integrated Circuit Card
The default value is UCAF.

Table 1: "PaymentMethods" data structure elements

TransactionDetail

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

Key
 Type Required Description
orderNumber

 String Required Order number of the transaction
The following characters are allowed: [A-Z][a-z][0-9,-]
merchant

 Object Required Data structure containing merchant information
merchant.name

 String Required Merchant name
merchant.url

 String Required Merchant domain URL
The maximum length is 100 characters.
merchant.id

 String Optional Merchant reference
This is the id value registered with your PG (required for gateway token mode)
The maximum length is 45 characters.
It should be set in the request parameter for mada token.
If a merchant request mada token, this field is mandatory as this field should be included in the payload.
For mada token, there is a 15-character length limit.
amount

 Object Required Data structure containing the payment amount
amount.option

 String Required Display format for the total amount on the payment sheet
The possible values are:
  • FORMAT_TOTAL_ESTIMATED_AMOUNT = Display "Total (Estimated amount)" and total amount
  • FORMAT_TOTAL_PRICE_ONLY = Display the total amount only
amount.currency

 String Required Currency code
The maximum length is 3 characters.
amount.total

 String Required Total payment amount in the currency specified by amount.currency
The amount must be an integer (for example, 300) or in a format valid for the currency (such as 2 decimal places after a separator, for example, 300.50).

Table 2: "TransactionDetail" data structure elements

PaymentCredential

The PaymentCredential object contains the payment credential information generated by the Samsung Wallet application on the user's mobile device.

Key Type Required Description
cardBrand

 String Required Brand of the payment card
cardLast4digit

 Object Required Last 4 digits of the card number
3DS

 Object Required Data structure containing the generated 3DS data
3DS.type

 String Optional 3DS type
The value is S for Samsung Pay.
3DS.version

 String Required 3DS version
The value for the current version is 100.
3DS.data

 String Required Encrypted payment credential data

Table 3: "PaymentCredential" data structure elements

PaymentResult

The PaymentResult object contains the payment result information during transaction processing, and after the payment is processed with PG network.

Key Type Required Description
status

 String Required Payment status
The possible values are:
  • CHARGED = payment was charge successfully
  • CANCELED = payment was canceled by either user, merchant, or acquirer
  • REJECTED = payment was rejected by acquirer
  • ERRED = an error occurred during the payment process
provider

 String Optional Payment provider (PG) name

Table 4: "PaymentResult data structure elements