Samsung Pay

Everything you need to take Samsung Pay payments via an app:

How it works

../resources/images/samsungpayflow_thumb_350_0.png

  1. Your app initiates the Samsung Pay wallet

  2. Samsung Pay returns the encrypted payload following shopper authentication

  3. You send the encrypted payload to your server

  4. You send an XML Direct request to Worldpay containing the encrypted Samsung Pay data

  5. We send you the payment response

  6. You inform the shopper of the outcome

Setup

Prerequisites

You need:

  • ADirectintegration to Worldpay

  • A Samsung Pay Developer account

  • Worldpay to enable Samsung Pay on your account

Set up Samsung Pay

Configure your IDE project before integrating Samsung Pay into your app.

To use Samsung Pay within your app you will need to create a Samsung Pay developer account through theSamsung Pay Developersand download theSamsung pay SDK.

Configure your IDE to integrate to Samsung Pay SDK.

Best practice: Samsung Pay recommend using theAndroid StudioIDE.

The Samsung Pay SDK explains how to integrate Samsung Pay in to your app.

Integrate to Samsung Pay

Configuring your app to use Samsung Pay requires a Certificate Sign Request (CSR) and a Service ID.

Generate a CSR

Contact Worldpay Corporate Support with your WorldpayMerchant Codeto have Samsung Pay enabled. You can then generate your own CSR using theMAI.

Note: It is possible to request a CSR from Samsung Pay, however this will not be compatible with your Worldpay configuration.

Generate the Service ID property

The Samsung Pay SDK requires you to set a Service ID when you configure the PartnerInfo object. To do this you will need to add a Service to your app in the Samsung Pay portal. When the new Service is created you will be provided with a Service ID and will be asked to upload the CSR provided by Worldpay.

Set the allowedCardBrands property

Worldpay only supports Samsung Pay payments with Visa, Mastercard, and American Express (Amex).

Configure the allowedCardBrands property of the request object to only receive card networks Worldpay support. See the brandList ArrayList lines in the example below.

Set the paymentProtocol property

Worldpay only supports the PROTOCOL_3DS parameter for the paymentProtocol with Samsung Pay.

Configure the paymentProtocol property of the request object to PROTOCOL_3DS as shown in the example below.

Copied!
Collection brandList = new ArrayList();
brandList.add(WalletConstants.CardNetwork.AMEX);
brandList.add(WalletConstants.CardNetwork.MASTERCARD);
brandList.add(WalletConstants.CardNetwork.VISA); // Only use the cards listed here
PaymentInfo paymentReq = new PaymentInfo.Builder()
.setMerchantName("TestMerchant").setAmount(getAmount(getAmount())
.setShippingAddress(getShippingAddressInfo())
.setOrderNumber(orderNoView.getText().toString())
.setPaymentProtocol(PaymentProtocol.PROTOCOL_3DS) //Worldpay only support PROTOCOL_3DS
.setAddressInPaymentSheet(AddressInPaymentSheet.DO_NOT_SHOW)
.setAllowedCardBrands(brandList) //add Worldpay supported card brands here
.setCardHolderNameEnabled(isCardHolderNameRequired)
.setRecurringEnabled(isRecurring)
.build();

Map the fields

Once a consumer authenticates themselves your app will receive a callback via the onSuccess() method. This method will provide 3 arguments, a PaymentInfo object, a String and a Bundle. The String is a string representation of a JSON object containing the encrypted payment credentials, below is an example of this JSON object:

Copied!
{
"billing_address":{
"city":"A",
"country":"GBR",
"state_province":"",
"street":"A",
"zip_postal_code":"94404151"
},
"card_last4digits":"1887",
"3DS":{
  "data":"AAAAAA.....",
  "type":"S",
  "version":"100"
},
"merchant_ref":"",
"method":"3DS",
"recurring_payment":false
}

This JSON object can be used to map data to Worldpay’s XML in the following way:

Samsung Pay fieldWorldpay XML field
3DS.data<data> element of the <ThreeDS> element of <SAMSUNGPAY-SSL>
3DS.version<version> element of the <ThreeDS> element of <SAMSUNGPAY-SSL>

If you are also collecting address data from the Samsung Pay wallet, you can either use the billingAddress elements of the above JSON but you may find it easier to use the strongly typed Address objects which represent billingAddress and shippingAddress which can be found within the PaymentInfo object.

The Samsung Address object contains the following fields which can be mapped to the corresponding fields for <billingAddress> and <shippingAddress> elements of Worldpay’s XML:

Samsung Pay fieldWorldpay XML fieldNotes
addressLine1<address1>
addresssLine2<address2>
addressLine3<address3>
postalCode<postalCode>
city<city>
state<state>
countryCode<countryCode>Samsung provide the countryCode in a format not supported by Worldpay. Worldpay require this in ISO 3166-1 alpha 2 format so you will need to carry out a conversion.

The Samsung request code can be found in the latest Samsung SDK.

Integrate to Worldpay

Prerequisite: You've successfullyintegrated Samsung Payin to your app, and can generate a payment encrypted payload.

When you've obtained an the data required from successful transaction callback method and have passed this to your server, send the payload to us within <SAMSUNGPAY-SSL>.

Example XML request

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
"http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <submit>
    <order orderCode="YOUR_ORDER_CODE">
      <description>SAMSUNG_PAY_TEST_ORDER</description>
      <amount value="100" currencyCode="GBP" exponent="2"/>
      <paymentDetails>
        <SAMSUNGPAY-SSL>
          <ThreeDS>
            <data>Your encrypted data</data>            
            <version>100</version>
          </ThreeDS>
        </SAMSUNGPAY-SSL>
      </paymentDetails>
      <shopper>
        <shopperEmailAddress>shopper@worldpay.com</shopperEmailAddress>
      </shopper>
    </order>
  </submit>
</paymentService>

Recurring payments

To take recurring payments you mustcreate a token and follow the stored credentials integration.

Full XML payment request using tokenisation and stored credentials:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
    <submit>
        <order orderCode="YOUR_ORDER_CODE">
            <description>test order</description>
            <amount value="100" currencyCode="GBP" exponent="2"/>
            <orderContent>
                <![CDATA[]]>
            </orderContent>
            <paymentDetails>
                <SAMSUNGPAY-SSL>
                    <ThreeDS>
                        <data>Your encrypted data</data>
                        <version>100</version>
                    </ThreeDS>
                </SAMSUNGPAY-SSL>
                <storedCredentials usage="FIRST" merchantInitiatedReason="RECURRING"></storedCredentials>
                <session shopperIPAddress="127.0.0.1" id="ssn489567618"/>
            </paymentDetails>
            <shopper>
                <shopperEmailAddress>shopper@worldpay.com</shopperEmailAddress>
                <authenticatedShopperID>shopperID</authenticatedShopperID>
                <browser>
                    <acceptHeader>text/html</acceptHeader>
                    <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>
                </browser>
            </shopper>
            <createToken tokenScope="shopper">
                <tokenEventReference>eventReference</tokenEventReference>
                <tokenReason>reason</tokenReason>
            </createToken>
        </order>
    </submit>
</paymentService>

Response

The responses you receive are the same as a standardshopper,merchantorusetoken response. We manage the transactionIdentifier returned by the schemes for cases where there's only ever a single agreement with one cardholder. Store the transactionIdentifer being returned to you for cases where you must handle multiple agreements for one cardholder in a single token.

Test

Samsung Pay supports both debug and release modes.

Worldpay's test environment is designed to work in tandem with debug mode and production will work with release mode.

Details of the above are included in theSamsung Pay SDKdocumentation.

Some links to Samsung Pay websites.

Samsung Pay: Turn your phone in to your wallet

Developer: Android Studio

Developer: Samsung Pay Developers

Create a payment with a decrypted payload