Implement DSRP remote payment

Overview

Use Mastercard DSRP remote payment to generate payment data for remote acceptance (for example, e-commerce).

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

Before you implement DSRP remote payments, 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 DigitalCard.Details.isPaymentTypeSupported() with PaymentType.dsrp.

func checkCardSupportForDSRP(card: DigitalCard) async throws -> Bool {
    return try await card.details.isPaymentTypeSupported(.dsrp)
}

Create the DSRP payment input data

Before generating DSRP payment data, you must provide the input data in RemotePaymentInputData.

func buildRemoteInputData() -> RemotePaymentSession.RemotePaymentInputData  {
    let amount = "000000500030"  // 5000.30 EUR in minor units
    let currencyCode = "978"     // ISO 4217 numeric
    let countryCode = "840"      // ISO 3166-1 numeric (example: US)
    let unpredictableNumber = "12345"
    
    return RemotePaymentSession.RemotePaymentInputData(
        amount: amount,
        currencyCode: currencyCode,
        transactionType: .purchase,
        unpredictableNumber: unpredictableNumber,
        countryCode: countryCode,
        cryptogramType: .de55
    )
}

RemotePaymentSession.RemotePaymentInputData has the following fields:

Input data	Type	Format	Description
amount	String	Numeric, minor units	Required Transaction amount in minor units (no decimal separator). For example, 119.00 USD is 11900 (then left-pad if your integration requires fixed length).
currencyCode	String	3-digit ISO 4217 numeric	Required Transaction currency code. For example, USD is 840.
countryCode	String	3-digit ISO 3166-1 numeric	Required Merchant country code. For example, United States is 840.
transactionType	Enum	.purchase	Required Financial transaction type. For DSRP payments, use .purchase.
cryptogramType	Enum	.ucaf or .de55	Required Cryptogram data format returned by the SDK.
unpredictableNumber	String	Numeric	Required Random number generated by the merchant or payment gateway.

Generate DSRP payment data

In your digital wallet application, call RemotePaymentSession.generateRemotePayment().

This API can throw an error. See Handle errors.

On success, the API returns RemotePaymentOutputData with the following fields:

Parameter	Description
cryptogramData	Byte array containing the formatted response. This is either UCAF or TLV data for the merchant to populate DE-55.
pan	PAN with any F padding removed (if present).
panSequenceNumber	PAN sequence number (PSN) of the card used.
track2EquivalentData	Track 2 data elements per ISO/IEC 7813 (excluding start sentinel, end sentinel, and LRC): PAN, field separator (D), expiration date (YYMM), service code, discretionary data, and optional F padding.
par	Payment account reference (PAR), if provided by the payment network.
expirationDate	Card expiration date.
cryptogramDataType	Cryptogram format returned (UCAF or DE55).

Handle errors

If generateRemotePayment() throws an error, treat the payment as failed. Reset your UI state. Guide the end user to the next best action.

Error	Description
deviceEnvironmentUnsafe	The device does not meet the security requirements.
sessionInProgress	Another payment session is still running.
invalidInputData	One or more fields in RemotePaymentInputData are missing or malformed.
noPaymentKeys	No payment keys are available for the transaction.
cardNotSupported	The digital card does not support DSRP remote payment.
cardNotActive	The digital card is not active.
noDefaultCard	No default card is set.
clientError	The remote payment flow failed due to a client-side error (for example, a network issue).
authenticationKeyInvalidated	The device passcode was disabled and secure storage was wiped.
biometricNotEnrolled	Biometrics are unavailable or not enrolled.

Each error can include a message that explains the failure. Use it for troubleshooting and support diagnostics.

NFC Wallet SDK automatically wipes stored credentials when authenticationKeyInvalidated occurs (for example, after a passcode reset or security change).

Your application should guide the end user through re-enrollment.

Full implementation example

Use this code sample to understand how the previous steps fit together.

func generateDSRP(digitalCard: DigitalCard?) async {
    do {
        let remotePaymentSession = RemotePaymentSession()

        let amount = "000000500030"      // 5000.30 in minor units, left-padded to 12
        let currencyCode = "978"         // ISO 4217 numeric (EUR)
        let countryCode = "840"          // ISO 3166-1 numeric (US example)
        let unpredictableNumber = "12345"

        let input = RemotePaymentSession.RemotePaymentInputData(
            amount: amount,
            currencyCode: currencyCode,
            transactionType: .purchase,
            unpredictableNumber: unpredictableNumber,
            countryCode: countryCode,
            cryptogramType: .de55
        )

        if let digitalCard {
            _ = try await remotePaymentSession.generateRemotePayment(
                withDigitalCardID: digitalCard.digitalCardID,
                remotePaymentInputData: input,
                userPrompt: "Authenticate"
            )
        } else {
            // Use the default digital card.
            _ = try await remotePaymentSession.generateRemotePayment(
                withDigitalCardID: nil,
                remotePaymentInputData: input,
                userPrompt: "Authenticate"
            )
        }
    } catch {
        guard let err = error as? RemotePaymentSession.Error else {
            return
        }

        switch err {
        case .deviceEnvironmentUnsafe:
            break
        case .sessionInProgress:
            break
        case .invalidInputData:
            break
        case .authenticationKeyInvalidated:
            break
        case .biometricNotEnrolled:
            break
        default:
            break
        }
    }
}