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.
    3DSecure.onlinePaymentCryptogram
    Cryptogram in 3DSecure format.
    eci_indicator sourceOfFunds.provided.card.devicePayment.
    3DSecure.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

Sample Authorization Request for Samsung Pay
{
    "apiOperation": "AUTHORIZE",
    "order": {
        "amount": "30.10",
        "currency": "USD",
        "walletProvider":"SAMSUNG_PAY"
    },
    "sourceOfFunds": {
        "provided": {
            "card": {
                "expiry": {
                    "month": "05",
                    "year": "21"
                },
                "number": "5123450000000008",
                "devicePayment":{
                    "cryptogramFormat":"3DSECURE",
                    "3DSecure":{
                        "onlinePaymentCryptogram":"IA/8pdiWftSsxpFT6wABoDABhgA=",
                        "eciIndicator":"20"
                    }
                }
            }
            
        },
        "type": "CARD"
    },
    "device": {
        "ani":"12341234"
    },
    "transaction": {
               "frequency": "SINGLE",
               "source": "INTERNET"
    } 
}

Example Response

Sample Authorization Response for Samsung Pay
{
  "authorizationResponse": {
    "posData": "10091Z500010",
    "transactionIdentifier": "000000285377253"
  },
  "customer": {
    "phone": "12341234"
  },
  "device": {
    "ani": "12341234"
  },
  "gatewayEntryPoint": "WEB_SERVICES_API",
  "lineOfBusiness": "All",
  "merchant": "TEST_MERCHANT",
  "order": {
    "amount": 30.1,
    "creationTime": "2016-11-09T23:20:58.675Z",
    "currency": "USD",
    "id": "C999903",
    "status": "AUTHORIZED",
    "totalAuthorizedAmount": 30.1,
    "totalCapturedAmount": 0,
    "totalRefundedAmount": 0,
    "walletProvider": "SAMSUNG_PAY"
  },
  "posTerminal": {
    "location": "PAYER_TERMINAL_OFF_PREMISES"
  },
  "response": {
    "acquirerCode": "000",
    "cardholderVerification": {
      "avs": {
        "acquirerCode": "U",
        "gatewayCode": "NOT_AVAILABLE"
      },
      "detailedVerification": [
        {
          "gatewayCode": "NOT_MATCHED",
          "type": "BILLING_PHONE"
        },
        {
          "gatewayCode": "NOT_PROVIDED",
          "type": "BILLING_POSTCODE_ZIP"
        },
        {
          "gatewayCode": "NOT_PROVIDED",
          "type": "BILLING_STREET_ADDRESS"
        },
        {
          "gatewayCode": "NOT_PROVIDED",
          "type": "CARDHOLDER_NAME"
        },
        {
          "gatewayCode": "NOT_PROVIDED",
          "type": "CUSTOMER_EMAIL"
        }
      ]
    },
    "gatewayCode": "APPROVED"
  },
  "result": "SUCCESS",
  "sourceOfFunds": {
    "provided": {
      "card": {
        "brand": "MASTERCARD",
        "deviceSpecificExpiry": {
            "month": "05",
            "year": "21"
        },
        "deviceSpecificNumber": "512345xxxxxx0008",
        "expiry": {
          "month": "05",
          "year": "28"
        },
        "fundingMethod": "UNKNOWN",
        "devicePayment": {
          "cryptogramFormat": "3DSECURE"
        },
        "number": "xxxxxxxxxxxx0023",
        "scheme": "MASTERCARD"
      }
    },
    "type": "CARD"
  },
  "timeOfRecord": "2016-11-09T23:20:58.675Z",
  "transaction": {
    "acquirer": {
      "batch": 3,
      "id": "TESTACQUIRER",
      "merchantId": "6465720084"
    },
    "amount": 30.1,
    "authorizationCode": "377253",
    "currency": "USD",
    "frequency": "SINGLE",
    "id": "1",
    "receipt": "001611092532",
    "source": "INTERNET",
    "terminal": "12333",
    "type": "AUTHORIZATION"
  },
  "version": "44"
}

Copyright © 2020 Mastercard