Implement DSRP remote payment

Overview

Use Mastercard Digital Secure Remote Payment (DSRP) to generate payment data for remote acceptance, such as e-commerce.

In this flow, your digital wallet application generates payment data. You pass that data to your merchant system or payment gateway for authorization.

Before you start, complete Tokenization. See Tokenize a card.

The NFC Wallet SDK supports DSRP remote payment for Mastercard digital cards with the MCBP 2.x profile only.

If you need DSRP remote payment for a different profile or payment network, contact your Thales delivery team.

SDK Integration

Check prerequisites

Confirm the digital card supports DSRP remote payment using DigitalizedCardDetails.paymentTypeSupported(). This API returns a list of supported payment types. Verify that PaymentType.DSRP is present.

public boolean isDsrpSupported(DigitalizedCardDetails card) {
    final PaymentType[] supported = card.paymentTypeSupported();

    for (PaymentType p : supported) {
        if (p == PaymentType.DSRP) {
            return true;
        }
    }
    return false;
}

Create the DSRP payment input data

Create PaymentInputData. It contains the transaction parameters used to generate the DSRP remote payment payload.

Use PaymentInputData.PaymentInputBuilder with:

• withRemotePaymentParameters to provide amount and currencyCode
• withMCRemotePaymentParameters to provide countryCode, transactionType, cryptogramDataType, and unpredictableNumber

Use the following sample values as placeholders.

long amount = 11900; // minor units. Example: 119.00
char currencyCode = 702; // SGD (ISO 4217 numeric)
char countryCode = 702; // Singapore (ISO 3166-1 numeric)
TransactionType transactionType = TransactionType.PURCHASE;
long unpredictableNumber = 12345;
PaymentInputData paymentInputData = new PaymentInputData.PaymentInputBuilder(PaymentType.DSRP)
                .withRemotePaymentParameters(amount, currencyCode)
                .withMCRemotePaymentParameters(countryCode, transactionType, CryptogramDataType.DE55, unpredictableNumber)
                .build();

PaymentInputData for DSRP payment has the following fields:

Field	Type	Format	Requirement	Description
amount	long	Numeric, minor units	Required	Set the transaction amount in minor units (no decimal separator). Example: 119.00 USD is 11900.
currencyCode	char (integer)	3-digit ISO 4217 numeric	Required	Set the transaction currency code. Example: USD is 840.
countryCode	char (integer)	3-digit ISO 3166-1 numeric	Required	Set the merchant country code. Example: United States is 840.
transactionType	Enum	TransactionType.PURCHASE	Required	Set the financial transaction type. For DSRP remote payments, use TransactionType.PURCHASE.
cryptogramDataType	Enum	CryptogramDataType.UCAF or CryptogramDataType.DE55	Required	Set the cryptogram format returned by the SDK.
unpredictableNumber	long	Numeric	Required	Provide a random number generated by the merchant or payment gateway.

Generate a remote payment cryptogram

In your digital wallet application, call PaymentBusinessService.generateApplicationCryptogram() with PaymentType.DSRP to generate payment data for remote acceptance (for example, e-commerce).

You must implement a RemotePaymentServiceListener.

final PaymentBusinessService pbs = PaymentBusinessManager.getPaymentBusinessService();
pbs.generateApplicationCryptogram(
        PaymentType.DSRP, 
        paymentInputData, 
        remotePaymentServiceListener);

Implement RemotePaymentServiceListener

The remote payment listener handles events during DSRP cryptogram generation.

The listener has three callbacks:

• onAuthenticationRequired

  The SDK indicates CDCVM verification is required. See Perform CDCVM verification.
• onDataReadyForPayment

  Remote payment output data is ready. Retrieve it using PaymentService.getRemotePaymentData().

  Deactivate the payment service after you retrieve the data. If you skip deactivation, the next generation can fail with REMOTE_PAYMENT_WRONG_STATE.
• onError

  The SDK encountered a failure during remote payment generation.

  Deactivate the payment service to reset the state before retrying.

The following code snippet shows a basic implementation of the listener:

public class MyRemotePaymentPaymentServiceListener implements RemotePaymentServiceListener{
    /**********************************************************/
    /*                Payment Service listener                */
    /**********************************************************/
    @Override
    public void onAuthenticationRequired(PaymentService paymentService, CHVerificationMethod chVerificationMethod, long cvmResetTimeout) {
        toggleProgress(false);
        if (chVerificationMethod == CHVerificationMethod.BIOMETRICS
                || chVerificationMethod == CHVerificationMethod.DEVICE_KEYGUARD) {
            Intent intent = new Intent(this, DeviceCVMActivity.class);
            intent.putExtra(DeviceCVMActivity.EXTRA_CVM, chVerificationMethod);
            overridePendingTransition(0, 0);
            startActivityForResult(intent, REQ_CODE_FINGERPRINT);
        } else {
            // NOTE: Not supported any other verification
            AppLogger.e(TAG, "Verification method " + chVerificationMethod + " not currently supported!");
            deactivatePaymentService();
        }
    }

    @Override
    public void onDataReadyForPayment(PaymentService paymentService, TransactionContext transactionContext) {
        toggleProgress(false);
        RemotePaymentOutputData remotePaymentData = paymentService.getRemotePaymentData();
        Toast.makeText(this, " DSRP payment data is " +remotePaymentData.getCryptogramData(), Toast.LENGTH_LONG).show();
        deactivatePaymentService();
    }

    @Override
    public void onError(SDKError<PaymentServiceErrorCode> sdkPaymentServiceErrorCode) {
        AppLogger.e(TAG, "Failed to generate DSRP payment data with error code " + sdkPaymentServiceErrorCode.getErrorCode());
        Toast.makeText(this, "Failed to generate DSRP payment data with error code " + sdkPaymentServiceErrorCode.getErrorCode(), Toast.LENGTH_SHORT).show();
        deactivatePaymentService();
    }
}

Pass your listener instance when you call generateApplicationCryptogram(...).

Get DSRP payment data

Get RemotePaymentOutputData when RemotePaymentServiceListener.onDataReadyForPayment() is triggered.

RemotePaymentOutputData contains the following fields.

Field	Description
cryptogramData	Byte array containing the formatted response. This is either UCAF or TLV data for the merchant to populate DE-55.
dpan	DPAN with any F padding removed (if present).
dpanSequenceNumber	DPAN sequence number (PSN) of the card used.
track2EquivalentData	Track 2 equivalent data, according to ISO/IEC 7813, excluding start sentinel, end sentinel, and LRC.
PAR	Payment account reference (PAR), if provided by the payment network.
dPanexpirationDate	DPAN expiration date.
cryptogramDataType	Cryptogram format returned (UCAF or DE55).

track2EquivalentData includes:

• Primary Account Number
• Field separator (hex D)
• Expiration date (YYMM)
• Service code
• Discretionary data (defined by the payment network)
• Optional padding with hex F to align to a whole byte

Handle errors

When RemotePaymentServiceListener.onError(...) is triggered, the SDK provides a PaymentServiceErrorCode.

Always call PaymentBusinessService.deactivate() in onError(...) to reset the payment service state before you retry.

PaymentBusinessService.generateApplicationCryptogram(...) throws IllegalArgumentException if paymentInputData is null or if the listener is null.

Payment service error code	Description	Recommended action
REMOTE_PAYMENT_WRONG_STATE	The payment service is already activated when trying to perform a remote payment.	Call PaymentBusinessService.deactivate() after each generation. Call it when the end user cancels CDCVM.
REMOTE_PAYMENT_OUTPUT_INVALID	Output data cannot be parsed and is not available.	Retry the transaction.
REMOTE_PAYMENT_NOT_SUPPORTED	The default card does not support remote payment.	Check DigitalizedCardDetails.paymentTypeSupported() before payment. Use a digital card that supports PaymentType.DSRP.
REMOTE_PAYMENT_INPUT_INVALID	The input data exists but some fields are not valid.	Rebuild PaymentInputData with valid values. Ensure all required fields are set.
NO_DEFAULT_CARD	There is no default card.	Set a default card before generating a cryptogram.
CARD_OUT_OF_PAYMENT_KEYS	No payment credentials are available.	Replenish payment credentials before retrying.