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
  • elo(TBD)
  • mada(TBD)
  • cb(TBD)
isRecurring

 boolean

 Optional

 Value if payment is recurring
The default value is false.
isCpfCardRequired

 boolean

 Optional

 Value if payment must be including cpf
The default value is false.
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.
merchant.countryCode

 String

 Required

 Merchant country code
ISO-3166-1 alpha-2
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).
type

 String

 Optional

 Transaction type
This value is specifically supported for mada tokens and will not apply to other token types.
The possible values are:
  • PURCHASE
  • PREAUTHORIZATION
The default value is PURCHASE.

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
card_brand

 String

 Required

 Brand of the payment card
card_last4digit

 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
recurring_payment

 boolean

 Required

 Value if credential is enabled for recurring
The default value is false.
cpf

 String

 Optional

 Brazilian CPF
This value is JWE encrypted with registered CSR.
Encrypted value included below information. 
{
  "name": "Joao", 
  "number": "12345678900"
}

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