On This Page

Samsung Pay Developer Guide

Audience and Purpose

This document is written for merchants who want to enable customers to use Samsung Pay to pay for in-app purchases. This document provides an overview for integrating the Samsung Pay SDK and describes how to request the
Cybersource
 API to process an authorization. Merchants must use the Samsung Pay SDK to receive the customer's encrypted payment data before requesting the
Cybersource
 API to process the transaction.
Cybersource
 supports Samsung Pay as a digital wallet, and this guide shows how to authorize a Samsung Pay digital wallet payment with and without 3-D Secure 2.2 authentication.

Conventions

The following special statements are used in this document:
IMPORTANT
An
Important
 statement contains information essential to successfully completing a task or learning a concept.
WARNING
A
Warning
 contains information or instructions, which, if not heeded, can result in a security risk, irreversible loss of data, or significant cost in time or revenue or both.

Related Documentation

Refer to the Support Center for complete technical documentation:

Customer Support

For support information about any service, visit the Support Center:

Recent Revisions to This Document

26.03.01

Initial release of the
Elavon
 version of this guide.

Introduction

You can use the
Cybersource
 platform to process and manage Samsung Pay transactions.

Samsung Pay Overview

Samsung Pay is a simple, secure in-app mobile and Web payment solution. You can choose
Cybersource
 to process Samsung Pay transactions through all e-commerce channels.
You can simplify your payment processing by allowing
Cybersource
 to decrypt the payment data for you during processing.
This method integrates simply and enables you to process transactions without seeing the payment network token and transaction data.
  1. Using the Samsung API, request the customer’s encrypted payment data.
  2. Using the
    Cybersource
     API, construct and submit the authorization request, and include the encrypted payment data from the Samsung Pay callback.
  3. Cybersource
     decrypts the encrypted payment data to create the payment network token and processes the authorization request.

Samsung Pay Digital Wallets

With
Elavon
,
Cybersource
 supports Samsung Pay as a digital wallet, a mobile app that enables users to link their credit cards, debit cards, loyalty card to their mobile phones. The mobile wallet enables fast online checkouts and contactless in-store payments.
Cybersource
 digital wallets integrate through
Unified Checkout
, ensuring secure transactions.
Elavon
 supports 3-D Secure 2.2 with Diners Club, Mastercard, and Visa card transactions. The section Authorizing Samsung Pay Digital Wallet Payments covers authorizations of Samsung Pay digital wallet payments without 3-D Secure and with 3-D Secure.

Requirements for Using Samsung Pay

In order to use the
Cybersource
 platform to process Samsung Pay transactions, you must have:
  • A
    Cybersource
     account. If you do not already have a
    Cybersource
     account, contact your local
    Cybersource
     sales representative.
  • A merchant account
    with a supported processor.
  • A profile on the Samsung Pay Partner Portal and an associated partner ID.
IMPORTANT
Samsung Pay relies on authorizations with payment network tokens. You can sign up for Samsung Pay only when both of the following statements are true:
  • Your processor supports payment network tokens.
  • Cybersource
     supports payment network tokens with your processor.
If one or both of the preceding statements are not true, you must take one of the following actions before you can sign up for Samsung Pay:
  • Obtain a new merchant account with a processor that supports payment network tokens.
  • Wait until your processor supports payment network tokens.

Supported Card Types

Processor
Card Types
Optional Features
Elavon
  • Diners Club
  • Mastercard
  • Visa

Related Information

Transaction Endpoints

Test transactions:
Production transactions:

Getting Started

Follow these steps to set up Samsung Pay with
Cybersource
:

Registering with Samsung Pay

  1. Create a profile by completing the merchant application on the Samsung Pay Partner Portal.

    ADDITIONAL INFORMATION

    After your merchant application is approved, you receive a unique partner ID. Include this ID in your application.
    IMPORTANT
    You need the partner ID in order to generate a Certificate Signing Request (CSR) in the
    Business Center
    . Samsung requires the CSR file in order to encrypt sensitive payment data; it contains an identifier and public key.
  2. Using the Samsung Pay Partner Portal, upload the CSR file.
  3. Enter an application name and a package name. When you associate the CSR file with the application, Samsung generates a product ID.
  4. Create login details for application developers on the Samsung Pay Partner Portal.
  5. Download and integrate the Samsung Pay SDK into your application.

    ADDITIONAL INFORMATION

    The SDK contains:
    • A Javadoc
    • The Samsung Pay SDK files
      samsungpay.jar
       and
      sdk-v1.0.0.jar
    • A sample app
    • The branding guide
    • Image files
  6. Register a Samsung account ID and request a
    debug-api-key
     file using the Samsung Pay Partner Portal. The Samsung account ID, the
    debug-api-key
    , and the product ID are used to validate your application so that you can use the Samsung Pay SDK for testing.
  7. Submit your application for approval using the Samsung Pay Partner Portal. Upload the final version of the Android Application Package (APK) file using the Samsung Pay Partner Portal, and include screenshots of your checkout page displaying the Samsung Pay logo.

Registering with
Cybersource

  2. On the left navigation pane, click the
    Payment Configuration
     icon.
  3. Click
    Digital Payment Solutions
    . The Digital Payments page opens.
  4. Click
    Configure
    . The Samsung Pay Registration panel opens.
  5. Enter your Samsung partner ID.
  6. Click
    Generate New CSR
    .
  7. To download your CSR, click the
    Download
     icon next to the key.
  8. Follow your browser's instructions to save and open the file.

    ADDITIONAL INFORMATION

    IMPORTANT
    Only one CSR is permitted for each unique Samsung partner ID. If you modify your Samsung partner ID, you must generate a new CSR.
  9. Complete the enrollment process by submitting your CSR to Samsung.

Creating a Project

You use Android Studio to create a new Android Studio project, which is required to integrate the Samsung SDK.
  1. Download Android Studio from the following website: https://developer.android.com/studio/index.html.
  2. Open Android Studio and click
    Start a new Android Studio project
    .
  3. In the New Project settings menu, enter the name of your application and the company domain.
  4. To change the package name, click
    Edit
    . By default, Android Studio sets the last element of the project's package name to the name of your application.
  5. Click
    Next
    .
  6. In the Target Android Devices settings menu, choose the required API levels.
  7. Click
    Next
    .
  8. Choose the required activity and click
    Finish
    .

Integrating the Samsung Pay SDK

  1. Add the
    samsungpay.jar
     and
    sdk-v1.0.0.jar
     files to the
    libs
     folder of your Android project.
  2. Choose
    Gradle Scripts > build.gradle
     and enter the dependencies shown below.

    ADDITIONAL INFORMATION

    dependencies {
    compile files('libs/samsungpay.jar')
    compile files(libs/sdk-v1.0.0.jar')
}
  3. Import the package.

    ADDITIONAL INFORMATION

    import com.samsung.android.sdk.samsungpay;

Using the API Key

The API key is used to verify that your app (in debug mode or release mode) can use the Samsung Pay SDK APIs with the Samsung Pay application. To get the API key, you must create a
debug-api-key
 file and include it in the
manifest
 file.
  1. To use the API key, include it in the
    manifest
     file with a custom tag. This enables the merchant app android
    manifest
     file to provide the
    DebugMode
    ,
    spay_debug_api_key
     values as metadata.

Example: Debug Mode

<meta-data
    android:name="debug_mode"
    android:value="Y" />
<meta-data
    android:name="spay_debug_api_key"
    android:value="asdfggkndkeie17283094858" />

Example: Release Mode

<meta-data
    android:name="debug_mode"
    android:value="N" />

Verify That Your Application is Eligible for Samsung Pay

You must initialize the
SSamsungPay
 class to verify that your application is eligible for Samsung Pay and to display the Samsung Pay button to the customer (refer to branding guidelines).
The
SSamsungPay
 class provides the following API methods:
  • initialize()
    —initializes the Samsung Pay SDK and verifies eligibility for Samsung Pay, including the device, software, and business area.
    IMPORTANT
    Request the
    initialize()
     API method of the
    SSamsungPay
     class before using the Samsung Pay SDK.
  • getVersionCode()
    —retrieves the version number of the Samsung Pay SDK as an integer.
  • getVersionName()
    —retrieves the version name of the Samsung Pay SDK as a string.
After the
initialize()
 API method request is successful, display the Samsung Pay button to the customer.
If the
initialize()
 API method request fails, the method displays one of the following errors:
  • SsdkUnsupportedException
    —the device is not a Samsung device or does not support the Samsung Pay package.
  • NullPointerException
    —the context passed is null.

Example: Samsung Pay Class

SSamsungPay spay = new SSamsungPay();
try {
    spay.initialize(mContext);
} catch (SsdkUnsupportedException e1) {
    e1.printStackTrace();
    pay_button.setVisibility(View.INVISIBLE);
}

Initiating a Payment

You are required to use a specific transaction request structure and required fields to initiate a payment.

Required Fields for Initiating a Payment

The following fields are required for initiating a payment; include these fields in the
PaymentInfo
 class:
IMPORTANT
If the required fields are not included, you receive a
NullPointerException
 error.
Merchant Name
The merchant name as it appears on the payment sheet of Samsung Pay and customer’s bank statement.
Amount
Payment Protocol
3-D Secure.
Permitted Card Brands
Specify the card brands that are supported such as American Express, JCB, Mastercard, or Visa.
Merchant ID
Order Number
Shipping Address
This field is required if
SEND_SHIPPING or NEED_BILLING_AND_SEND_SHIPPING
 is set for
AddressVisibilityOption
.
Address Visibility Option
Card Holder Name
Recurring Option

Example: Transaction Request Structure

private PaymentInfo makeTransactionDetails() {
// Supported card brands
ArrayList<CardInfo.Brand> brandList = new ArrayList<CardInfo.Brand>();
if (visaBrand.isChecked())
brandList.add(CardInfo.Brand.VISA);
if (mcBrand.isChecked())
brandList.add(CardInfo.Brand.Mastercard);
if (amexBrand.isChecked())
brandList.add(CardInfo.Brand.AMERICANEXPRESS);

// Basic payment information
PaymentInfo paymentReq = new PaymentInfo.Builder()
.setMerchantId(“merchantID”)
.setMerchantName("Test").setAmount(getAmount())
.setShippingAddress(getShippingAddressInfo())
.setOrderNumber(orderNoView.getText().toString())
.setPaymentProtocol(PaymentProtocol.PROTOCOL_3DS)
.setAddressInPaymentSheet(AddressInPaymentSheet.DO_NOT_SHOW)
.setAllowedCardBrands(brandList) .setRecurringEnabled(isRecurring)
.setCardHolderNameEnabled(isCardHolderNameRequired)
.build();
return paymentReq;
}

// Add shipping address details
private Address getShippingAddressInfo() {
Address address = new Address.Builder()
.setAddressee(name.getText().toString())
.setAddressLine1(addLine1.getText().toString())
.setAddressLine2(addline2.getText().toString())
.setCity(city.getText().toString())
.setState(state.getText().toString())
.setCountryCode(country.getSelectedItem().toString())
.setPostalCode(zip.getText().toString()).build(); return address;
}

// Add amount details private Amount getAmount() {
Amount amount = new Amount.Builder()
.setCurrencyCode(currencyType.getSelectedItem().toString())
.setItemTotalPrice(productPrice.getText().toString())
.setShippingPrice(shippingPrice.getText().toString())
.setTax(taxPrice.getText().toString())
.setTotalPrice(totalAmount.getText().toString()).build();
return amount;
}

Requesting a Payment

  1. Use the
    startSamsungPay()
     API method in the
    PaymentManager
     class. The
    PaymentManager
     class includes the following API methods:

    ADDITIONAL INFORMATION

    • startSamsungPay()
      —requests to initiate payment with Samsung Pay.
    • updateAmount()
      —updates the transaction amount if shipping address or card information is updated by Samsung Pay.
    • updateAmountFailed()
      —returns an error code when the new amount cannot be updated because of a wrong address.
  2. Request the
    startSamsungPay()
     API method and include the following data:

    ADDITIONAL INFORMATION

    • PaymentInfo
      —contains payment information.
    • PID
      —the product ID created in the Samsung Pay Partner Portal.
    • StatusListener
      —the result of the payment request is delivered to
      StatusListener
      . This listener should be registered before you call the
      startSamsungPay()
       API method.
    When you request the
    startSamsungPay()
     API method, the Samsung Pay online payment sheet is displayed on your application. The customer selects a registered card for payment and can also update the billing and shipping address.
    The payment reply is delivered as one of the following events to
    StatusListener
    :
    • onSuccess()
      —this event is requested when Samsung Pay confirms the payment. It includes
      encryptedPaymentCredential
       in JSON format:
      • method:
         Payment protocol: 3-D Secure.
      • merchant_ref:
         Merchant reference code.
      • billing_address.street
        : Number, street name.
      • billing_address.state_province:
         Two-letter state code.
      • billing_address.zip_postal_code:
         Five-character zip code.
      • billing_address.city:
         City name.
      • billing_address.county:
        Two-letter country code.
      • 3ds.type:
        S
         for Samsung Pay. Encrypted.
      • 3ds.version:
         Current version
        100
        . Encrypted.
      • 3ds.data:
         Base64-encoded payment data. Encrypted.
      Refer to the Samsung Pay developer website for information on how to decrypt the encrypted payment credential.
    • onFailure()
      —this event is requested when the transaction fails. It returns an error code and error message.

Example: Request startSamsungPay() API Method

public void onPayButtonClicked(View v) {
    // Call startSamsungPay() method of PaymentManager class.
    // To create a transaction request for makeTransactionDetails() in
    the following code, see Example: Transaction Request Structure.
    try {
        mPaymentManager.startSamsungPay(makeTransactionDetails(), "enter
        product ID",
mStatusListener);
    } catch (NullPointerException e) {
    e.printStackTrace();
    }
}

private PaymentManager.StatusListener mStatusListener = new
PaymentManager.StatusListener() {
    @Override
    public void onFailure(int errCode, String msg) {
        Log.d(TAG, " onFailed );
    }
    @Override
    public void onSuccess(PaymentInfo arg0, String result) {
        Log.d(TAG, "onSuccess ");
    };

Authorization Service

You can authorize a payment for Samsung Pay using two different types of decryption methods:
Cybersource
 or Merchant. Each decryption method requires a different set of required API fields. In addition, depending on which card type is used, different fields are required for requesting the authorization service.
Processor-Specific Information About Authorizations and Captures
Payment Processor
Authorization and Capture Information
Elavon
Elavon
 limits authorization and capture amounts to 999999999999 (twelve 9s).
FDMS South
For the Indonesian rupiah (IDR) and Chilean peso (CLP) currencies:
  • Rounding occurs, which can cause a minor discrepancy of one currency unit between the amount you requested and the amount that is authorized.
  • When a transaction is enabled for partial authorization, you must ensure that the requested amount does not include any digits to the right of the decimal separator.

Authorizing a Payment with JCB Using
Cybersource
 Decryption Method

Required Fields for Authorizing a Payment Using JCB and the
Cybersource
 Decryption Method

The following fields are required when submitting an authorization request using the
Cybersource
 decryption method:
  • descriptor
    -set this field under the
    fluidData
     object to
    RklEPUNPTU1PTi5TQU1TVU5HLklOQVBQLlBBWU1FTlQ=
    .
  • paymentInformation.fluidData.value
    -set this field to the Base64-encoded value obtained from the
    paymentData
     property of the
    PKPaymentToken
     object.
  • processingInformation.paymentSolution
    -set this field to
    008
    .

Related Information

Authorizing a Payment

  1. Send the service request to
    https://api.cybersource.com
    /pts/v2/payments
    .
  2. Include the required fields in the request.
  3. Include optional fields in the request as needed.
  4. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success. For information about response codes, see Transaction Response Codes.

Example:
Cybersource
 Decryption with JCB Using the REST API

Authorization Request
{
    "processingInformation": {
        "paymentSolution": "008"
    },
    "consumerAuthenticationInformation": {
        "cavv": "EHuWW9PiBkWvqE5juRwDzAUFBAk=",
        "eciRaw": "05"
    },
    "paymentInformation": {
        "tokenizedCard": {
            "number": "xxxx55555555xxxx",
            "expirationMonth": "12",
            "expirationYear": "2031",
            "transactionType": "1",
            "type": "007"
        }
    },
    "billTo": {
        "firstName": "Jane",
        "lastName": "Smith",
         "address1": "123 Main Street",
         "address2": "Suite 12345",
         "locality": "Small Town",
         "administrativeArea": "CA",
         "postalCode": "98765",
         "country": "US",
         "email": "js@example.com",
         "phoneNumber": "9999999999"
      },
      "orderInformation": {
         "amountDetails": {
             "currency": "USD",
             "totalAmount": "100.00"
         }
      }
}
Authorization Response
{
    "clientReferenceInformation": {
        "code": "ref123"
    },
    "orderInformation": {
        "amountDetails": {
            "currency": "USD",
            "authorizedAmount": "100.00"
        }
    },
    "processingInformation": {
        "reconciliationID": "15356268CR2XF23X"
    },
    "processorInformation": {
        "approvalCode": "888888",
        "responseCode": "100",
        "paymentSolution": "008",
        "avs": {
            "codeRaw": "I1"
        }
    }  
}

Authorizing a Payment with Mastercard Using
Cybersource
 Decryption Method

Required Fields for Authorizing a Payment Using Mastercard and the
Cybersource
 Decryption Method

The following fields are required when submitting an authorization request using the
Cybersource
 decryption method:
  • descriptor
    -set this field under the
    fluidData
     object to
    RklEPUNPTU1PTi5TQU1TVU5HLklOQVBQLlBBWU1FTlQ=
    .
  • processingInformation.commerceIndicator
    -set this field to
    spa
    .
  • paymentInformation.tokenizedCard.transactionType
    -set this field to
    1
    .
  • processingInformation.paymentSolution
    -set this field to
    008
    .

Related Information

Example:
Cybersource
 Decryption with Mastercard Using the REST API

Authorization Request
{
    "clientReferenceInformation": {
        "code": "demorefnum"
    },
    "processingInformation": {
        "paymentSolution": "008",
        "commerceIndicator": "spa"
    },
    "paymentInformation": {
        "tokenizedCard": {
            "transactionType": "1"
        }
    },
    "fluidData": {
      "descriptor": "ABCDEFabcdefABCDEFabcdef0987654321234567",
      "value": "RklEPUNPTU1PTi5TQU1TVU5HLklOQVBQLlBBWU1FTlQ="
    },
    "billTo": {
        "firstName": "James",
        "lastName": "Smith",
         "address1": "111 S. Division St.",
         "address2": "Suite 123",
         "locality": "Ann Arbor",
         "administrativeArea": "MI",
         "postalCode": "48104-2201",
         "country": "US",
         "email": "demo@example.com",
         "phoneNumber": "9999999999"
      },
      "orderInformation": {
         "amountDetails": {
             "currency": "USD",
             "totalAmount": "100.00"
         }
      }
}
Authorization Response
{
    "clientReferenceInformation": {
        "code": "demorefnum"
    },
    "orderInformation": {
        "amountDetails": {
            "currency": "USD",
            "authorizedAmount": "100.00"
        }
    },
    "processingInformation": {
        "reconciliationID": "13209255CGJSMQCR"
    },
    "processorInformation": {
        "approvalCode": "888888",
        "responseCode": "100",
        "avs": {
            "code": "I1"
        }
    },
    "submitTimeUtc": "2015-11-03T205035Z"
    }    
}

Authorizing a Payment with Visa Using
Cybersource
 Decryption Method

Required Fields for Authorizing a Payment Using Visa and the
Cybersource
 Decryption Method

The following fields are required when submitting an authorization request using the
Cybersource
 decryption method:
  • descriptor
    -set this field under the
    fluidData
     object to
    RklEPUNPTU1PTi5TQU1TVU5HLklOQVBQLlBBWU1FTlQ=
    .
  • processingInformation.commerceIndicator
    -set this field to
    internet
    .
  • paymentInformation.tokenizedCard.transactionType
    -set this field to
    1
    .
  • processingInformation.paymentSolution
    -set this field to
    008
    .

Related Information

Example:
Cybersource
 Decryption with Visa Using the REST API

Authorization Request
{
    "clientReferenceInformation": {
        "code": "demorefnum"
    },
    "processingInformation": {
        "paymentSolution": "008",
        "commerceIndicator": "internet"
    },
    "paymentInformation": {
        "tokenizedCard": {
            "transactionType": "1"
        }
    },
    "fluidData": {
      "descriptor": "ABCDEFabcdefABCDEFabcdef0987654321234567",
      "value": "RklEPUNPTU1PTi5TQU1TVU5HLklOQVBQLlBBWU1FTlQ="
    },
    "billTo": {
        "firstName": "James",
        "lastName": "Smith",
         "address1": "111 S. Division St.",
         "address2": "Suite 123",
         "locality": "Ann Arbor",
         "administrativeArea": "MI",
         "postalCode": "48104-2201",
         "country": "US",
         "email": "demo@example.com",
         "phoneNumber": "9999999999"
      },
      "orderInformation": {
         "amountDetails": {
             "currency": "USD",
             "totalAmount": "100.00"
         }
      }
}
Authorization Response
{
    "clientReferenceInformation": {
        "code": "demorefnum"
    },
    "orderInformation": {
        "amountDetails": {
            "currency": "USD",
            "authorizedAmount": "100.00"
        }
    },
    "paymentInformation": {
         "tokenizedCard": {
            "prefix": "294672",
            "suffix": "4397",
            "expirationMonth": "08"
         }
    },
    "processingInformation": {
        "reconciliationID": "13209254CGJSMQCQ"
    },
    "processorInformation": {
        "approvalCode": "888888",
        "responseCode": "100",
        "avs": {
            "code": "I1"
        }
    }   
}

Authorizing a Payment with JCB Using Merchant Decryption Method

Required Fields for Authorizing a Payment Using JCB and the Merchant Decryption Method

The following fields are required when submitting an authorization request using the Merchant decryption method:
  • consumerAuthenticationInformation.cavv
    -set this field to the 3-D Secure cryptogram of the payment network token.
  • paymentInformation.card.number
    -set this field to the payment network token value.
  • paymentInformation.card.expirationMonth
    /
    paymentInformation.tokenizedCard.expirationMonth
    -set this field to the payment network token expiration month value.
  • paymentInformation.card.expirationYear
    /
    paymentInformation.tokenizedCard.expirationYear
    -set this field to the payment network token expiration year value.
  • consumerAuthenticationInformation.eciRaw
    -set this field to the ECI value contained in the Samsung Pay reply message.
  • paymentinformation.tokenizedCard.cryptogram
    -set this field to the network token cryptogram.
  • paymentInformation.tokenizedCard.transactionType
    -set this field to
    1
    .
  • processingInformation.paymentSolution
    -set this field to
    008
    .

Related Information

Example: Merchant Decryption with JCB Using the REST API

Authorization Request
{
    "consumerAuthenticationInformation": {
        "cavv": "EHuWW9PiBkWvqE5juRwDzAUFBAk=",
        "eciRaw": "05"
    },
    "processingInformation": {
        "paymentSolution": "008"
    },
    "paymentInformation": {
        "tokenizedCard": {
            "expirationMonth": "12",
            "expirationYear": "2031",
            "number": "xxxx11111111xxxx",
            "transactionType": "1",
            "type": "007"
        }
    },
    "billTo": {
        "firstName": "Jane",
        "lastName": "Smith",
         "address1": "123 Main St.",
         "address2": "Suite 12345",
         "locality": "Small Town",
         "administrativeArea": "CA",
         "postalCode": "98765",
         "country": "US",
         "email": "js@example.com",
         "phoneNumber": "9999999999"
      },
      "orderInformation": {
         "amountDetails": {
             "currency": "USD",
             "totalAmount": "100.00"
         }
      }
}
Authorization Response
{
    "clientReferenceInformation": {
        "code": "ref123"
    },
    "orderInformation": {
        "amountDetails": {
            "currency": "USD",
            "authorizedAmount": "100.00"
        }
    },
    "processingInformation": {
        "reconciliationID": "15356268CR2XF23X"
    },
    "processorInformation": {
        "approvalCode": "888888",
        "responseCode": "100",
        "avs": {
            "code": "X",
            "codeRaw": "I1"
        }
    }    
}

Authorizing a Payment with Mastercard Using Merchant Decryption Method

Required Fields for Authorizing a Payment Using Mastercard and the Merchant Decryption Method

The following fields are required when submitting an authorization request using the Merchant decryption method:
  • paymentInformation.card.number
    -set this field to the payment network token value.
  • paymentInformation.card.expirationMonth
    /
    paymentInformation.tokenizedCard.expirationMonth
    -set this field to the payment network token expiration month value.
  • paymentInformation.card.expirationYear
    /
    paymentInformation.tokenizedCard.expirationYear
    -set this field to the payment network token expiration year value.
  • processingInformation.commerceIndicator
    - set this field to
    spa
    .
  • paymentinformation.tokenizedCard.cryptogram
    -set this field to the network token cryptogram.
  • paymentInformation.tokenizedCard.transactionType
    -set this field to
    1
    .
  • processingInformation.paymentSolution
    -set this field to
    008
    .
  • consumerAuthenticationInformation.ucafAuthenticationData
    –set this field to the 3-D Secure cryptogram of the payment network token.
  • consumerAuthenticationInformation.ucafCollectionIndicator
    -set this field to
    2
    .

Related Information

Example: Merchant Decryption with Mastercard Using the REST API

Authorization Request
{
    "clientReferenceInformation": {
        "code": "demorefnum"
    },
    "consumerAuthenticationInformation": {
        "ucafAuthenticationData": "ABCDEFabcdefABCDEFabcdef0987654321234567",
        "ucafCollectionIndicator": "2"
    },
    "processingInformation": {
        "paymentSolution": "008"
    },
    "paymentInformation": {
        "tokenizedCard": {
            "expirationMonth": "12",
            "expirationYear": "2021",
            "number": "xxxx55555555xxxx",
            "transactionType": "1"
        }
    },
    "billTo": {
        "firstName": "James",
        "lastName": "Smith",
         "address1": "111 S. Division St.",
         "address2": "Suite 123",
         "locality": "Ann Arbor",
         "administrativeArea": "MI",
         "postalCode": "48104-2201",
         "country": "US",
         "email": "demo@example.com",
         "phoneNumber": "9999999999"
      },
      "orderInformation": {
         "amountDetails": {
             "currency": "USD",
             "totalAmount": "100.00"
         }
      }
}
Authorization Response
{
    "clientReferenceInformation": {
        "code": "demorefnum"
    },
    "orderInformation": {
        "amountDetails": {
            "currency": "USD",
            "authorizedAmount": "100.00"
        }
    },
    "processingInformation": {
        "reconciliationID": "13209255CGJSMQCR"
    },
    "processorInformation": {
        "approvalCode": "888888",
        "responseCode": "100",
        "avs": {
            "code": "I1"
        }
    },
    "submitTimeUtc": "2015-11-03T205035Z"
    }    
}

Authorizing a Payment with Visa Using Merchant Decryption Method

Required Fields for Authorizing a Payment Using Visa and the Merchant Decryption Method

The following fields are required when submitting an authorization request using the Merchant decryption method:
  • consumerAuthenticationInformation.cavv
    -set this field to the 3-D Secure cryptogram of the payment network token.
  • paymentInformation.card.number
    -set this field to the payment network token value.
  • paymentInformation.card.expirationMonth
    /
    paymentInformation.tokenizedCard.expirationMonth
    -set this field to the payment network token expiration month value.
  • paymentInformation.card.expirationYear
    /
    paymentInformation.tokenizedCard.expirationYear
    -set this field to the payment network token expiration year value.
  • consumerAuthenticationInformation.eciRaw
    -for JCB transactions, set this field to the ECI value contained in the Samsung Pay reply message.
  • processingInformation.commerceIndicator
    -set this field to
    internet
    .
  • paymentinformation.tokenizedCard.cryptogram
    -set this field to the network token cryptogram.
  • paymentInformation.tokenizedCard.transactionType
    -set this field to
    1
    .
  • processingInformation.paymentSolution
    -set this field to
    008
    .

Related Information

Example: Merchant Decryption with Visa Using the REST API

Authorization Request
{
    "clientReferenceInformation": {
        "code": "demorefnum"
    },
    "consumerAuthenticationInformation": {
        "cavv": "ABCDEFabcdefABCDEFabcdef0987654321234567"
    },
    "processingInformation": {
        "commerceIndicator": "internet",
        "paymentSolution": "008"
    },
    "paymentInformation": {
        "tokenizedCard": {
            "expirationMonth": "12",
            "expirationYear": "2021",
            "number": "xxxx100000000xxxx",
            "transactionType": "1"
        }
    },
    "billTo": {
        "firstName": "James",
        "lastName": "Smith",
         "address1": "111 S. Division St.",
         "address2": "Suite 123",
         "locality": "Ann Arbor",
         "administrativeArea": "MI",
         "postalCode": "48104-2201",
         "country": "US",
         "email": "demo@example.com",
         "phoneNumber": "9999999999"
      },
      "orderInformation": {
         "amountDetails": {
             "currency": "USD",
             "totalAmount": "100.00"
         }
      }
}
Authorization Response
{
    "clientReferenceInformation": {
        "code": "demorefnum"
    },
    "orderInformation": {
        "amountDetails": {
            "currency": "USD",
            "authorizedAmount": "100.00"
        }
    },
    "processingInformation": {
        "reconciliationID": "13209254CGJSMQCQ"
    },
    "processorInformation": {
        "approvalCode": "888888",
        "responseCode": "100",
        "avs": {
            "code": "I1"
        }
    },
    "submitTimeUtc": "2015-11-03T205035Z"
    }    
}

Authorization Reversal Service

The authorization reversal service is a follow-on service that uses the request ID returned from the previous authorization. An authorization reversal releases the hold that the authorization placed on the customer’s credit card funds. Use this service to reverse an unnecessary or undesired authorization.
Processor-Specific Information About Authorization Reversals
Payment Processor
Authorization Reversal Information
Elavon
Card types supported for full authorization reversals: Diners Club, Mastercard, Visa.
A full authorization reversal must occur within 24 hours of the authorization.
FDC Germany
You are responsible for complying with the processor’s specific requirements for full authorization reversals. Contact the processor for more information.
FDMS South
Card types supported for full authorization reversals: Visa, Mastercard, Discover, and JCB (US Domestic).
For JCB cards, US Domestic means that the currency is USD and your location is the U.S., Puerto Rico, Guam, U.S. Virgin Islands, or Northern Mariana Islands.
Full authorization reversals are supported only for transactions that do not go through a currency conversion.
Full authorization reversals are supported for the following types of merchants and currencies:
  • Merchants located in the U.S. who authorize, settle, and fund in U.S. dollars.
  • Merchants located in Canada who authorize, settle, and fund in Canadian dollars.
  • Merchants located in Latin America or the Caribbean who authorize, settle, and fund in U.S. dollars.
  • Merchants located in Europe who authorize, settle, and fund in the currency for the country in which the merchant is located.
Software Express
Card types supported for full authorization reversals: Visa, Mastercard.

Required Fields for Reversing an Authorization

The following fields are required when creating an authorization reversal request:
clientReferenceInformation.code
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
processingInformation.paymentSolution
Set to
008
.

Related Information

Reversing an Authorization

  1. Send the service request to
    POST https://&lt;
    url_prefix
    &gt;/v2/payments/{id}/reversals
    . Use one of these prefixes:
    • Test:
      apitest.cybersource.com
    • Production:
      api.cybersource.com
    • Production in India:
      api.in.cybersource.com

    ADDITIONAL INFORMATION

    Where
    id
     is the authorization ID returned in the authorization response. 
    {
  "id": "6481692924466004003001"
}
    The URL with the
    id
     value is included in the authorization response:
    {
    "_links": {
        "authReversal": {
            "method": "POST",
            "href": "/pts/v2/payments/6481692924466004003001/reversals"
        },
  2. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success. For information about response codes, see Transaction Response Codes.

Example: Basic Credit Card Authorization Reversal Using the REST API

Authorization Reversal Request
{
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "reversalInformation": {
    "amountDetails": {
      "totalAmount": "102.21"
    },
    "reason": "exception"
  }
}
Authorization Reversal Response
{
    "submitTimeUtc": "2021-04-22T16:44:03Z",
    "status": "approved",
    "errorInformation": {
        "reason": "EXCEPTION",
        "message": "The request was processed successfully."
    }
}

Capture Service

The capture service is a follow-on service that uses the request ID returned from the previous authorization. The request ID links the capture to the authorization. This service transfers funds from the customer’s account to your bank and usually takes two to four days to complete.
Processor-Specific Information About Authorizations and Captures
Payment Processor
Authorization and Capture Information
Elavon
Elavon
 limits authorization and capture amounts to 999999999999 (twelve 9s).
FDMS South
For the Indonesian rupiah (IDR) and Chilean peso (CLP) currencies:
  • Rounding occurs, which can cause a minor discrepancy of one currency unit between the amount you requested and the amount that is authorized.
  • When a transaction is enabled for partial authorization, you must ensure that the requested amount does not include any digits to the right of the decimal separator.

Required Fields for Capturing a Payment

The following fields are required when creating a capture request:
clientReferenceInformation.code
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
processingInformation.paymentSolution
Set to
008
.

Related Information

Capturing a Payment

  1. Pass the original authorization ID in the URL, and send the service request to
    POST https://&lt;
    url_prefix
    &gt;/v2/payments/{id}/captures
    . Use one of these URL prefixes:
    • Test:
      apitest.cybersource.com
    • Production:
      api.cybersource.com
    • Production in India:
      api.in.cybersource.com

    ADDITIONAL INFORMATION

    Where
    id
     is the authorization ID returned in the authorization response. 
    {
  "id": "6481692924466004003001"
}
    The URL with the
    id
     value is included in the authorization response:
    {
  "_links": {
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/6481692924466004003001/captures"
    }
  }
  2. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success. For information about response codes, see Transaction Response Codes.

Example: Basic Credit Card Capture Using the REST API

Capture Request
{
  "clientReferenceInformation": {
    "code": "482046C3A7E94F5BD1FE3C66C"
  },
  "processingInformation": {
    "paymentSolution": "008"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "49.95",
      "currency": "USD"
    }
  }
}
Capture Response
{
    "clientReferenceInformation": {
        "code": "482046C3A7E94F5BD1FE3C66C"
    },
    "processingInformation": {
        "reconciliationID": "02850840187309570"
    },
    "orderInformation": {
        "amountDetails": {
           "totalAmount": "49.95",
           "currency": "USD"
        }
    }
}

Sale Service

A sale is a bundled authorization and capture. Request the authorization and capture services at the same time.
Cybersource
 processes the capture immediately.

Required Fields for Performing a Sale

The following fields are required when submitting a sale request:
Fields required for requesting the authorization service
Use the same values that are set for requesting the Authorization Service.
The sales request is sent to the following endpoint:
https://api.cybersource.com
/pts/v2/payments.

Related Information

Authorizing and Capturing a Payment

You can authorize and capture a payment at the same time, which is known as performing a sale.
  1. Send the service request to
    https://api.cybersource.com
    /pts/v2/payments
    .
  2. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success. For information about response codes, see Transaction Response Codes.

Example: Basic Credit Card Sale Using the REST API

Authorization and Capture (Sale) Request
{
    "clientReferenceInformation": {
        "code": "demorefnum"
    },
    "processingInformation": {
        "paymentSolution": "008",
        "commerceIndicator": "aesk"
    },
    "paymentInformation": {
        "tokenizedCard": {
            "transactionType": "1",
            "type": "003"
        }
    },
    "fluidData": {
      "descriptor": "ABCDEFabcdefABCDEFabcdef0987654321234567",
      "value": "RklEPUNPTU1PTi5TQU1TVU5HLklOQVBQLlBBWU1FTlQ="
    },
    "billTo": {
        "firstName": "James",
        "lastName": "Smith",
         "address1": "111 S. Division St.",
         "address2": "Suite 123",
         "locality": "Ann Arbor",
         "administrativeArea": "MI",
         "postalCode": "48104-2201",
         "country": "US",
         "email": "demo@example.com",
         "phoneNumber": "9999999999"
      },
      "orderInformation": {
         "amountDetails": {
             "currency": "USD",
             "totalAmount": "100.00"
         }
      }
}
Authorization and Capture (Sale) Response
{
    "clientReferenceInformation": {
        "code": "demorefnum"
    },
    "orderInformation": {
        "amountDetails": {
            "currency": "USD",
            "authorizedAmount": "100.00",
            "totalAmount": "100.00"
        }
    },
    "paymentInformation": {
         "tokenizedCard": {
            "prefix": "593056",
            "suffix": "0842",
            "expirationMonth": "08",
            "expirationYear": "2021"
         }
    },
    "processingInformation": {
        "reconciliationID": "13209256CGJSMQCZ"
    },
    "processorInformation": {
        "approvalCode": "888888",
        "responseCode": "100",
        "avs": {
            "code": "I1"
        }
    },
    "submitTimeUtc": "2015-11-03T205202Z"
    }    
}

Authorizing Samsung Pay Digital Wallet Payments

Elavon
 supports Samsung Pay digital wallet transactions. A Samsung Pay digital wallet uses
tokenization
 to prevent sensitive card data from being exposed or intercepted during transactions. A token is generated when a user adds a supported card to their Samsung Pay digital wallet.
Elavon
 supports 3-D Secure 2.2 with Diners Club, Mastercard, and Visa card transactions.
IMPORTANT
Elavon
 does not support the 3-D Secure 2.2 protocol if it is used with
network tokens
 or
digital payment
.
Cybersource
 will decline any transaction processed by
Elavon
 that uses both 3-D Secure 2.2 and either network tokens or digital payments.
This section shows you how to request authorization of a Samsung Pay digital wallet payment:

Authorizing a Samsung Pay Digital Wallet Payment without 3-D Secure

The topics in this section show to how to authorize a Samsung Pay digital wallet payment without 3-D Secure authentication:
  • Basic steps
  • Required fields
  • Mastercard example
  • Common error responses and resolutions
When 3-D Secure is not used, the transaction ID is automatically populated with the cryptogram value
For general information about basic authorizations, see the "Standard Payments Processing" section of the .

Basic Steps to Authorize a Samsung Pay Digital Wallet Payment without 3-D Secure

  1. Follow these steps to request a Samsung Pay payment on a supported card without 3-D Secure authentication:
  2. Create the request message with the required
    REST
     API fields.
  3. Send the message to one of these endpoints:
    • Production:
      POST
      https://api.cybersource.com
      /pts/v2/payments
    • Test:
      POST
      https://apitest.cybersource.com
      /pts/v2/payments
  4. Verify the response messages to make sure that the request was successful.

    ADDITIONAL INFORMATION

    A 200-level HTTP response code indicates success. See the .
  5. If the response message contain errors, see Common Error Responses for Transactions without 3-D Secure.

Required Fields to Authorize a Samsung Pay Digital Wallet Payment without 3-D Secure

These REST API fields are required to request authorization of a Samsung Pay Digital Wallet payment without 3-D Secure authentication.
clientReferenceInformation.code
merchantInformation.merchantId
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.firstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.phoneNumber
orderInformation.billTo.postalCode
paymentInformation.tokenizedCard.cryptogram
Set the value to the network token cryptogram from Samsung Pay.
paymentInformation.tokenizedCard.expirationMonth
paymentInformation.tokenizedCard.expirationYear
paymentInformation.tokenizedCard.transactionType
Set the value to
1
 for network tokens.
paymentInformation.tokenizedCard.type
Set the value to the card type code. Possible values:
  • 001
     for Visa
  • 002
     for Mastercard
  • 005
     for Diners Club
processingInformation.commerceIndicator
Set the value to
internet
 for a Diners Club, Discover, and Visa card for an authorization request without 3-D Secure authentication.
processingInformation.paymentSolution
Set the value to
008
 for Samsung Pay digital wallet transactions.

Mastercard Example: Authorize a Samsung Pay Digital Wallet Payment without 3-D Secure

Request
{
  "clientReferenceInformation": {
    "code": "MC-NO3DS-SAMSUNGPAY-004"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "67.50",
      "currency": "EUR"
    },
    "billTo": {
      "firstName": "Hans",
      "lastName": "Mueller",
      "address1": "Alexanderplatz 1",
      "locality": "Berlin",
      "postalCode": "10178",
      "country": "DE",
      "email": "hans.mueller@example.de",
      "phoneNumber": "+49-30-12345678"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "cryptogram": "CwABBJQ0AgAAAAAgJDUCAAAAAAA=",
      "transactionType": "1",
      "expirationMonth": "04",
      "expirationYear": "2028",
      "type": "002"
    }
  },
  "processingInformation": {
    "paymentSolution": "008",
    "commerceIndicator": "internet"
  },
  "merchantInformation": {
    "merchantId": "demo_merchant_12345"
  }
}

Common Error Responses for Transactions without 3-D Secure

This topic lists common error responses to transaction requests without 3-D Secure authentication.
3DS ECI provided for non-3DS transaction
Cause: Invalid e-commerce indicator for a transaction that does not use 3-D Secure.
Resolution: Make sure the
processingInformation.commerceIndicator
 field is set to
internet
 to indicate a transaction without 3-D Secure authentication. You could also omit the field from your request and let the gateway assign the value.
Authentication data present in non-3DS transaction
Cause: Conflicting authentication data.
Resolution: Remove the cardholder authentication data, which is used for transactions with 3-D Secure:
  • Remove the
    consumerAuthenticationInformation. cavv
     field (for Diners Club or Visa cards).
  • Remove the
    consumerAuthenticationInformation. ucafAuthenticationData
     field (for Mastercard only).
Digital wallet transaction missing required cryptogram
Cause: Missing or invalid cryptogram.
Resolution: Make sure the
paymentInformation.tokenizedCard.cryptogram
 field is populated with the correct value.

Authorizing a Samsung Pay Digital Wallet Payment with 3-D Secure

The topics in this section show to how to authorize a Samsung Pay digital wallet payment with 3-D Secure authentication:
  • Basic steps
  • Required fields
  • Diners Club example
For general information about basic authorizations, see the "Standard Payments Processing" section of the .

Basic Steps to Authorize a Samsung Pay Digital Wallet Payments with 3-D Secure

  1. Follow these steps to authorize a Samsung Pay payment on Mastercard with 3-D Secure authentication:
  2. Create the request message with the required
    REST
     API fields.
    • Use the API fields listed in Required Fields to Authorize a Samsung Pay Digital Wallet Payment with 3-D Secure.
      These REST API fields are specific to this payload:
      • merchantInformation.merchantDomain
      • consumerAuthenticationInformation.cavv
        —Diners Club and Visa only
      • consumerAuthenticationInformation.ucafAuthenticationData
        —Mastercard only
      • consumerAuthenticationInformation.ucafCollectionIndicator
        —Mastercard only
      • paymentInformation.tokenizedCard.cryptogram
      • paymentInformation.tokenizedCard.transactionType
      • paymentInformation.tokenizedCard.type
      • processingInformation.commerceIndicator
      • processingInformation.paymentSolution
      • processingInformation.paymentNetworkTokenTransactionType
    • Refer to the example Diners Club Example: Authorize a Samsung Pay Digital Wallet Payment with 3-D Secure.
      IMPORTANT
      The example is based on a Diners Club transaction. Set these fields to the appropriate values based on the card type:
      • paymentInformation.tokenizedCard.type
      • processingInformation.commerceIndicator
  3. Send the message to one of these endpoints:
    • Production:
      POST
      https://api.cybersource.com
      /pts/v2/payments
    • Test:
      POST
      https://apitest.cybersource.com
      /pts/v2/payments
  4. Verify the response messages to make sure that the request was successful.

    ADDITIONAL INFORMATION

    A 200-level HTTP response code indicates success. See the .

Required Fields to Authorize a Samsung Pay Digital Wallet Payment with 3-D Secure

These REST API fields are required to request authorization of a Samsung Pay digital wallet payment with 3-D Secure authentication.
clientReferenceInformation.code
consumerAuthenticationInformation.cavv
For Diners Club and Visa cards only—Set this value to the universal cardholder authentication number to indicate 3-D Secure authentication.
consumerAuthenticationInformation.directoryServerTransactionId
consumerAuthenticationInformation.paSpecificationVersion
consumerAuthenticationInformation.ucafAuthenticationData
For Mastercard transactions only—Set this value to the universal cardholder authentication field (UCAF) data to indicate 3-D Secure authentication.
consumerAuthenticationInformation.ucafCollectionIndicator
For Mastercard transactions only—Set the value of this field to
2
. UCAF collection is supported on your website and the UCAF was populated. This value indicates a successful Mastercard Identity Check transaction.
merchantInformation.merchantId
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.firstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.phoneNumber
orderInformation.billTo.postalCode
paymentInformation.tokenizedCard.cryptogram
Set the value to the network token cryptogram from Samsung Pay.
paymentInformation.tokenizedCard.expirationMonth
paymentInformation.tokenizedCard.expirationYear
paymentInformation.tokenizedCard.transactionType
Set the value to
1
.
paymentInformation.tokenizedCard.type
Set the value to the card type code. Possible values:
  • 001
     for Visa
  • 002
     for Mastercard
  • 005
     for Diners Club
processingInformation.commerceIndicator
Set the value to the code for the 3-D Secure authentication service. Possible values:
  • pb
     for 3-D Secure authentication by Diners Club ProtectBuy
  • spa
     for 3-D Secure authentication by Mastercard Identity Check
  • vbv
     for 3-D Secure authentication by Visa Secure
processingInformation.paymentSolution
Set the value to
008
 for Samsung Pay digital wallet transactions.

Diners Club Example: Authorize a Samsung Pay Digital Wallet Payment with 3-D Secure

Request
{
  "clientReferenceInformation": {
    "code": "DINERS-3DS-SAMSUNGPAY-006"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "199.00",
      "currency": "EUR"
    },
    "billTo": {
      "firstName": "Pierre",
      "lastName": "Dubois",
      "address1": "15 Rue de la Paix",
      "locality": "Paris",
      "postalCode": "75001",
      "country": "FR",
      "email": "pierre.dubois@example.fr",
      "phoneNumber": "+33-1-42-96-12-34"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "cryptogram": "BwABBJQ0AgAAAAAgJDUCAAAAAAA=",
      "transactionType": "1",
      "expirationMonth": "08",
      "expirationYear": "2027",
      "type": "005"
    }
  },
  "consumerAuthenticationInformation": {
    "cavv": "BgABBJQ0AgAAAAAgJDUCAAAAAA=",
    "directoryServerTransactionId": "8a2+89r+vs8fsc8w+v+79y==",
    "paSpecificationVersion": "2.2.0"
  },
  "processingInformation": {
    "paymentSolution": "008",
    "commerceIndicator": "pb"
  },
  "merchantInformation": {
    "merchantId": "demo_merchant_12345"
  }
}