Samsung Pay Payments

Samsung Pay is a mobile payment and digital wallet service by Samsung Electronics that allows payers to make payments with supported Samsung devices. Samsung Pay is a supported device payment in the MasterCard Payment Gateway.

This page describes integration details specific to Samsung Pay. It's recommended that you read the integration guidelines for device payments, before building your Samsung Pay integration.

Prerequisites

To accept Samsung Pay payments:

  • You must sign up with Samsung.
  • Your merchant profile on the gateway must be enabled for Device Payments by your payment service provider.

Adding Support for Samsung Pay to your Integration

You can integrate Samsung Pay into your mobile app using Direct Payment.

  1. On payment confirmation, submit the encrypted payment token returned by Samsung Pay to your server.
  2. Decrypt the payment token on your server using your private key. For decryption steps, please contact Samsung.
  3. Provide the keys from the decrypted token in the corresponding transaction fields on the Authorize/Pay request or the Update Session request.

    Samsung Pay JSON Key
    Corresponding API Request Field
    Description
    tokenPAN sourceOfFunds.provided.card.number The device-specific primary account number.
    tokenPanExpiration sourceOfFunds.provided.card.expiry.month
    sourceOfFunds.provided.card.expiry.year    		 The expiration date of the tokenPAN.
    method sourceOfFunds.provided.card.devicePayment.
    cryptogramFormat    		 The cryptogram format. Set this to 3DSECURE.
    cryptogram sourceOfFunds.provided.card.devicePayment.
    onlinePaymentCryptogram    		 Cryptogram in 3DSecure format.
    eci_indicator sourceOfFunds.provided.card.devicePayment.
    eciIndicator    		 ECI indicator per 3DSecure specification.
    currency_code order.currency The ISO 4217 currency code for the transaction.
    amount order.amount The order amount.

    sourceOfFunds.provided.card.devicePayment [REST][NVP]

  4. In addition to the above fields, include these in the Authorize/Pay request and submit it to the gateway.

    • transaction.source=INTERNET
    • order.walletProvider=SAMSUNG_PAY
    • device.mobilePhoneModel: (optional) The identifier of the mobile device used to initiate the payment.
    • posTerminal.location: You can specify PAYER_TERMINAL_OFF_PREMISES or PAYER_TERMINAL_ON_PREMISES. If you do not provide a value, PAYER_TERMINAL_OFF_PREMISES is used.
Example Request

Here's a sample Authorization Request in REST where payment token is decrypted by the gateway.

URL 'https://ap-gateway.mastercard.com/api/rest/version/71/merchant/MADA_DMS_AU/order/446974188/transaction/746444836'
HTTP Method PUT
Header 'Authorization: bWVyY2hhbnQuTUFEQV9ETVNfQVU6M2RjYTQ2YTU1ODYwNDlmMjhhM2FmZGJmZDEwMGNmNWQ=' 
 '{
     "apiOperation": "AUTHORIZE",
     "order": {
         "amount": "1500",
         "currency": "JPY",
         "walletProvider": "SAMSUNG_PAY"
     },
     "sourceOfFunds": {
         "provided": {
             "card": {
                 "number": "5123450000000008",
                 "expiry": {
                     "month": "01",
                     "year": "39"
                 },
                 "devicePayment": {
                     "cryptogramFormat": "3DSECURE",
                         "onlinePaymentCryptogram": "AAAAAAAALJI6DbfqRzUcwAC6gAAGhgEDoLABAAhAgAABAAAAMlkUxA==",
                         "eciIndicator": "20"
                 }
             }
         },
         "type": "CARD"
     },
     "device": {
         "ani": "12341234"
     },
     "transaction": {
         "source": "INTERNET"
     }
 }'
Example Response

 {
     "authorizationResponse": {
         "commercialCard": "123",
         "commercialCardIndicator": "1",
         "date": "0314",
         "financialNetworkCode": "MCC",
         "posData": "1025104006600",
         "posEntryMode": "812",
         "processingCode": "003000",
         "responseCode": "00",
         "stan": "47497",
         "time": "105733",
         "transactionIdentifier": "609405631",
         "transactionIntegrityClass": "A1"
     },
     "device": {
         "ani": "12341234"
     },
     "gatewayEntryPoint": "WEB_SERVICES_API",
     "merchant": "MADA_DMS_AU",
     "order": {
         "amount": 1500,
         "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
         "certainty": "FINAL",
         "chargeback": {
             "amount": 0,
             "currency": "JPY"
         },
         "creationTime": "2023-03-14T10:57:33.175Z",
         "currency": "JPY",
         "id": "446974188",
         "lastUpdatedTime": "2023-03-14T10:57:33.554Z",
         "merchantAmount": 1500,
         "merchantCategoryCode": "1234",
         "merchantCurrency": "JPY",
         "status": "AUTHORIZED",
         "totalAuthorizedAmount": 1500,
         "totalCapturedAmount": 0,
         "totalDisbursedAmount": 0,
         "totalRefundedAmount": 0,
         "walletProvider": "SAMSUNG_PAY"
     },
     "response": {
         "acquirerCode": "00",
         "acquirerMessage": "Approved",
         "gatewayCode": "APPROVED",
         "gatewayRecommendation": "NO_ACTION"
     },
     "result": "SUCCESS",
     "sourceOfFunds": {
         "provided": {
             "card": {
                 "brand": "MASTERCARD",
                 "devicePayment": {
                     "cryptogramFormat": "3DSECURE"
                 },
                 "deviceSpecificExpiry": {
                     "month": "1",
                     "year": "39"
                 },
                 "deviceSpecificNumber": "512345xxxxxx0008",
                 "fundingMethod": "UNKNOWN",
                 "number": "xxxxxxxxxxxxxxxx",
                 "scheme": "MASTERCARD",
                 "storedOnFile": "NOT_STORED"
             }
         },
         "type": "CARD"
     },
     "timeOfLastUpdate": "2023-03-14T10:57:33.554Z",
     "timeOfRecord": "2023-03-14T10:57:33.263Z",
     "transaction": {
         "acquirer": {
             "batch": 20230314,
             "date": "0314",
             "id": "SYSTEST_ACQ_S2I",
             "merchantId": "12345678",
             "transactionId": "609405631"
         },
         "amount": 1500,
         "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
         "authorizationCode": "112233",
         "currency": "JPY",
         "id": "746444836",
         "receipt": "307310047497",
         "source": "INTERNET",
         "stan": "47497",
         "terminal": "1111",
         "type": "AUTHORIZATION"
     },
     "version": "71"
 }

Testing Samsung Pay Integration

You can test your integration with the gateway in production using your test merchant profile and a supported DPAN or an FPAN.

If you are testing for a device or card payment, use a supported DPAN or FPAN from the following table.

Scheme
DPAN or FPAN
 Expiry Date
Mastercard 5123456789012346 01/2039
American Express 340353278080900 01/2039
Visa 4440000009900010 01/2039

Copyright © 2023 MasterCard