Name verification

Verify cardholder names match registered address information.

Overview

Name verification checks whether the cardholder's name matches the name associated with the registered address on file. This feature helps reduce fraud by validating the identity of the person making the payment.

To enable name verification, you need to:

Configure your backend to request name verification during session creation.
Implement the onGetShopper callback in your SDK configuration to provide shopper details (firstName and lastName). The SDK uses these values for name verification — not the cardholder name field automatically.
Retrieve the verification result from the transaction details API after payment.

Step 1: Enable name verification in your session

When creating a checkout session on your backend, include the identityVerification object in your API request:

{
  "merchant": "merchant-01",
  "site": "site-01",
  "merchantTransactionId": "txn-001",
  "amounts": {
    "currencyCode": "USD",
    "transactionValue": 100.00
  },
  "transactionMethod": {
    "intent": {
      "card": "authorisation"
    }
  },
  "identityVerification": {
    "nameVerification": true
  }
}

Parameter	Description
`identityVerification.nameVerification` boolean	Set to `true` to enable name verification for the transaction.

Step 2: Provide shopper details

Implement the onGetShopper callback in your SDK configuration to provide the cardholder's first and last name. onGetShopper is (() async -> TransactionShopper?)?.

import PXPCheckoutSDK

let checkoutConfig = CheckoutConfig(
    environment: .test,
    session: sessionData,
    transactionData: TransactionData(
        amount: Decimal(100.00),
        currency: "USD",
        entryType: .ecom,
        intent: TransactionIntentData(card: .authorisation),
        merchantTransactionId: UUID().uuidString,
        merchantTransactionDate: { Date() }
    ),
    merchantShopperId: "shopper-123",
    ownerId: "your-owner-id",
    onGetShopper: {
        TransactionShopper(
            firstName: "John",
            lastName: "Doe"
        )
    }
)

let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)

When fetching shopper details asynchronously:

onGetShopper: {
    let shopper = await self.fetchShopperDetails()
    return TransactionShopper(
        firstName: shopper.firstName,
        lastName: shopper.lastName
    )
}

For name verification, the SDK sends firstName and lastName from onGetShopper on the transaction request. If you collect a cardholder name in the UI, return those values from onGetShopper. Align TransactionShopper.id with merchantShopperId for card-on-file flows.

The firstName and lastName fields are required for name verification to work. Learn more about the onGetShopper callback.

TransactionShopper type reference

Field	Description
`firstName` String?	The cardholder's first name.
`lastName` String?	The cardholder's last name.

Step 3: Retrieve the verification result

After a transaction is completed, retrieve the name verification result by calling the Get transaction details API on your backend.

The name verification result isn't returned in the SDK transaction response. You must retrieve it from the API using the merchantTransactionId and systemTransactionId received in CardSubmitComponentConfig.onPostAuthorisation (via NewCardComponentConfig.submit).

GET

/v1/transactions/{merchant}/{site}

Request example

To get a transaction's details, you'll need to supply the merchant and site associated with the transaction, and either its merchantTransactionId or its systemTransactionId.

Use the following request example to get a transaction's details using a merchant transaction ID.

curl --request GET \
     --url https://api-services.pxp.io/api/v1/transactions/MERCHANT-1/SITE-1?merchantTransactionId=ECOM-001 \
     --header 'accept: application/json'

Path parameters

Parameter	Description
`merchant` string (≤ 10 characters) required	The unique merchant identifier associated with this transaction, as assigned by PXP.
`site` string (≤ 10 characters) required	The unique site identifier associated with this transaction, as assigned by PXP.

Query parameters

Parameter	Description
`merchantTransactionId` string (≤ 50 characters) required	The unique identifier that you assigned to this transaction.
`systemTransactionId` string (≤ 40 characters) required	The unique identifier assigned to this transaction by PXP.

Response example

If your request is successful, you'll receive a 200 response containing an array of transaction records. The last element of the array contains the most recent transaction state. The name verification result is returned in the fundingData.providerResponse.nameVerificationResult field.

[
  {
    "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "state": "Authorised",
    "merchantTransactionId": "ECOM-001",
    "fundingData": {
      "providerResponse": {
        "nameVerificationResult": "NoInformationAvailable"
      }
    }
  }
]

Verification result values

The following table describes the possible verification result values and their meaning.

Value	Description
`NoInformationAvailable`	No verification information was available from the card issuer.
`FirstNameMatchedLastNameMatched`	Both first and last names matched the registered information.
`FirstNameMatchedLastNameNotMatched`	First name matched, but last name did not match.
`FirstNameMatchedLastNameNotChecked`	First name matched, but last name was not checked.
`FirstNameMatchedLastNamePartialMatch`	First name matched, last name partially matched.
`FirstNameNotMatchedLastNameMatched`	First name did not match, but last name matched.
`FirstNameNotMatchedLastNameNotMatched`	Neither first name nor last name matched.
`FirstNameNotMatchedLastNameNotChecked`	First name did not match, last name was not checked.
`FirstNameNotMatchedLastNamePartialMatch`	First name did not match, last name partially matched.
`FirstNameNotCheckedLastNameMatched`	First name was not checked, but last name matched.
`FirstNameNotCheckedLastNameNotMatched`	First name was not checked, last name did not match.
`FirstNameNotCheckedLastNameNotChecked`	Neither first name nor last name was checked.
`FirstNameNotCheckedLastNamePartialMatch`	First name was not checked, last name partially matched.
`FirstNamePartialMatchLastNameMatched`	First name partially matched, last name matched.
`FirstNamePartialMatchLastNameNotMatched`	First name partially matched, last name did not match.
`FirstNamePartialMatchLastNameNotChecked`	First name partially matched, last name was not checked.
`FirstNamePartialMatchLastNamePartialMatch`	Both first and last names partially matched.

Complete example

Here's a complete example showing how to implement name verification:

import UIKit
import PXPCheckoutSDK

class CheckoutViewController: UIViewController {
    
    private var pxpCheckout: PxpCheckout?
    private var newCardComponent: NewCardComponent?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        Task {
            await initializeCheckout()
        }
    }
    
    private func initializeCheckout() async {
        do {
            // Step 1: Create session with name verification enabled (backend)
            let sessionData = try await createSessionWithNameVerification()
            
            // Step 2: Initialize SDK with onGetShopper callback
            let checkoutConfig = CheckoutConfig(
                environment: .test,
                session: sessionData,
                transactionData: TransactionData(
                    amount: Decimal(100.00),
                    currency: "USD",
                    entryType: .ecom,
                    intent: TransactionIntentData(card: .authorisation),
                    merchantTransactionId: UUID().uuidString,
                    merchantTransactionDate: { Date() }
                ),
                merchantShopperId: "shopper-123",
                ownerId: "owner-123",
                onGetShopper: {
                    // Return shopper details from your system
                    let shopper = await self.fetchShopperDetails()
                    return TransactionShopper(
                        firstName: shopper.firstName,
                        lastName: shopper.lastName
                    )
                }
            )
            
            pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)
            
            // Create and configure the new card component
            let newCardConfig = NewCardComponentConfig()
            var submit = CardSubmitComponentConfig()

            submit.onPreAuthorisation = { _ async in
                TransactionInitiationData()
            }

            submit.onPostAuthorisation = { [weak self] (result: MerchantSubmitResult) in
                guard let self = self else { return }

                Task {
                    await self.retrieveVerificationResult(
                        merchantTransactionId: result.merchantTransactionId,
                        systemTransactionId: result.systemTransactionId
                    )
                }
            }

            newCardConfig.submit = submit
            
            let component = try pxpCheckout?.create(.newCard, componentConfig: newCardConfig)
            newCardComponent = component as? NewCardComponent
            
            // Mount the component in your view hierarchy
            if let contentView = newCardComponent?.buildContent() {
                // Add contentView to your UI
            }
            
        } catch {
            print("Failed to initialize checkout: \(error)")
        }
    }
    
    private func createSessionWithNameVerification() async throws -> SessionData {
        // Backend API call to create session with identity verification
        let sessionRequest: [String: Any] = [
            "merchant": "merchant-01",
            "site": "site-01",
            "merchantTransactionId": UUID().uuidString,
            "amounts": [
                "currencyCode": "USD",
                "transactionValue": 100.00
            ],
            "transactionMethod": [
                "intent": [
                    "card": "authorisation"
                ]
            ],
            "identityVerification": [
                "nameVerification": true
            ]
        ]
        
        // Make your API call and return session data
        // This is placeholder - implement your actual API call
        return SessionData(
            sessionId: "session-123",
            hmacKey: "hmac-key",
            encryptionKey: "encryption-key"
        )
    }
    
    private func fetchShopperDetails() async -> (firstName: String, lastName: String) {
        // Fetch shopper details from your backend
        // This is placeholder - implement your actual data fetch
        return (firstName: "John", lastName: "Doe")
    }
    
    private func retrieveVerificationResult(
        merchantTransactionId: String,
        systemTransactionId: String
    ) async {
        do {
            // Backend API call to get transaction details
            let url = URL(string: "https://your-api.com/api/v1/transactions/merchant-01/site-01?merchantTransactionId=\(merchantTransactionId)&systemTransactionId=\(systemTransactionId)")!
            
            let (data, _) = try await URLSession.shared.data(from: url)
            let transactions = try JSONDecoder().decode([Transaction].self, from: data)
            
            if let latestTransaction = transactions.last,
               let verificationResult = latestTransaction.fundingData?.providerResponse?.nameVerificationResult {
                
                print("Name verification result: \(verificationResult)")
                
                // Handle the verification result
                switch verificationResult {
                case "FirstNameMatchedLastNameMatched":
                    print("Name verification successful")
                case "NoInformationAvailable":
                    print("Name verification information not available")
                default:
                    print("Name verification failed or partially matched")
                }
            }
        } catch {
            print("Failed to retrieve verification result: \(error)")
        }
    }
}

// Helper models for parsing transaction response
struct Transaction: Codable {
    let systemTransactionId: String
    let merchantTransactionId: String
    let fundingData: FundingData?
}

struct FundingData: Codable {
    let providerResponse: ProviderResponse?
}

struct ProviderResponse: Codable {
    let nameVerificationResult: String?
}