# Samsung Pay
source: https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/samsung-pay/index.md

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 on the Mastercard Gateway.

This page describes integration details specific to Samsung Pay. It is recommended that you read the [integration guidelines for device payments](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/integrate-mobile-payments/index.md), before building your Samsung Pay integration.

## Prerequisites {#prerequisites}

To accept Samsung Pay payments:

Sign up with [Samsung](https://pay.samsung.com/developers).
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 {#adding-support-for-samsung-pay-to-your-integration}

You can integrate Samsung Pay into your mobile app using [Direct Payment](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/direct-payment/index.md).

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, 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<br>sourceOfFunds.provided.card.expiry.year` | The expiration date of the tokenPAN.               |
| method               | `sourceOfFunds.provided.card.devicePayment.cryptogramFormat`                          | The cryptogram format. Set this to EMV 3-D Secure. |
| Cryptogram           | `sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram`                   | Cryptogram in EMV 3-D Secure format.               |
| eci_indicator        | `sourceOfFunds.provided.card.devicePayment.eciIndicator`                              | ECI indicator per EMV 3-D Secure specification.    |
| currency_code        | `order.currency`                                                                      | The ISO 4217 currency code for the transaction.    |
| amount               | `order.amount`                                                                        | The order amount.                                  |

**sourceOfFunds.provided.card.devicePayment** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction)

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 {#example-request}

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

| HTTP Method |                                                  URL                                                  |                                         Header                                          |
|-------------|-------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| PUT         | {{host}}/api/rest/version//merchant/\<merchant_ID\>/order/\<order_ID\>/transaction/\<transaction_ID\> | Authorization: bWVyY2hhbnQuTUFEQV9ETVNfQVU6M2RjYTQ2YTU1ODYwNDlmMjhhM2FmZGJmZDEwMGNmNWQ= |

```json
{
    "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"
    }
} 
```

```json
{
    "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": "100"
} 
```

## Testing Samsung Pay Integration {#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   | Expiration date |
|------------------|------------------|-----------------|
| Mastercard       | 5123456789012346 | 01/2039         |
| American Express | 340353278080900  | 01/2039         |
| Visa             | 4440000009900010 | 01/2039         |