Samsung Pay
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 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.
- On payment confirmation, submit the encrypted payment token returned by Samsung Pay to your server.
- Decrypt the payment token on your server using your private key. For decryption steps, please contact Samsung.
- 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 KeyCorresponding API Request FieldDescriptiontokenPAN sourceOfFunds.provided.card.number The device-specific primary account number. tokenPanExpiration sourceOfFunds.provided.card.expiry.month
sourceOfFunds.provided.card.expiry.yearThe expiration date of the tokenPAN. method sourceOfFunds.provided.card.devicePayment.
cryptogramFormatThe cryptogram format. Set this to 3DSECURE. cryptogram sourceOfFunds.provided.card.devicePayment.
onlinePaymentCryptogramCryptogram in 3DSecure format. eci_indicator sourceOfFunds.provided.card.devicePayment.
eciIndicatorECI indicator per 3DSecure specification. currency_code order.currency The ISO 4217 currency code for the transaction. amount order.amount The order amount. - 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_PREMISESorPAYER_TERMINAL_ON_PREMISES. If you do not provide a value,PAYER_TERMINAL_OFF_PREMISESis used.
Example Request
Here's a sample Authorization Request in REST where payment token is decrypted by the gateway.
| URL | 'https://test-nbkpayment.mtf.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 |