Initiate 3DS SDK with the Create a charge endpoint

North America—United States and Canada

Configure 3D Secure SDK Add 3DS authentication to create a charge Initiate 3DS SDK with pay for an order endpoint

To initiate the Clover 3DS SDK, you can charge a credit card or other payment source.

Prerequisites

Configure the 3DS SDK.
Generate a card token. You need to generate a new card token for each payment.

Steps

Send a POST request to the v1/charges endpoint to create a charge.
Enter the required parameters in the request—orderId, customer, and the payment source to charge, such as token or alternate_tender.
Enter the required information in thethreeds objects and related fields:
1. source—Source of the 3-D Secure (3DS) authentication, for example: CLOVER or NON_CLOVER.
2. authentication_result—EMV® 3-D Secure (3DS) authentication result.
Enter the required header: x-forwarded-for—Client internet protocol (IP) address of the web browser from which the customer’s payment originates.

Note: For testing in the sandbox environment, replace https://scl.clover.com/v1/charges with https://scl-sandbox.dev.clover.com/v1/charges

Request

curl --location 'https://scl-sandbox.dev.clover.com/v1/charges' \
--header 'Authorization: Bearer f5f3ef06361d8d5f38165f80fecacfbe' \
--header 'Content-Type: application/json' \
--data '{
    "amount": {{amount}},
    "source": {{clv_token_generated}},
    "currency": "USD",
    "threeds": {
        "source": "CLOVER",
        "browser_info": {
            "browser_ip": {{ip_address}},
            ...window._3DSUtil.getBrowserInfo()
        }
    }
}'

Responses

Frictionless successful transaction—Displays a successful authentication for 3DS without a challenge flow.

"threeds": {
    "validation_result": "AUTHENTICATION_SUCCESSFUL",
    "liability_protection_status": "PROTECTED"
}

Fingerprinting required (method-notification):—Displays the 3DS response information optionally used by issuers to gather browser fingerprints using JavaScript.

"threeds": {
        "validation_result": "THREEDS_METHOD_FLOW_REQUIRED",
        "liability_protection_status": "NOT_PROTECTED",
        "source": "CLOVER",
        "data": {
            "method_url": "https://acs.liveus.ravelin.net/3ds/acs/browser/method",
            "method_notification_url": "https://scl-sandbox.dev.clover.com/threeds-service/transactions/method-notification",
            "threeds_server_transaction_id": "be73b22e-0d8d-469c-afd3-06e758692b86",
            "threeds_protocol_version": "2.2.0"
        }
    }

Challenge flow required (challenge-notification): —Displays the 3DS response information after the issuers gathered browser fingerprints using JavaScript.

"threeds": {
        "validation_result": "CHALLENGE_FLOW_REQUIRED",
        "liability_protection_status": "NOT_PROTECTED",
        "source": "CLOVER",
        "data": {
            "acs_url": "https://acs.liveus.ravelin.net/3ds/acs/browser/creq",
            "acs_notification_url": "https://scl-sandbox.dev.clover.com/threeds-service/transactions/challenge-notification",
            "acs_transaction_id": "242393a7-e4bf-4e55-a7dd-c28287ecb910",
            "threeds_server_transaction_id": "633ee309-18db-4bb2-bcc1-2acb5f19fda0",
            "threeds_protocol_version": "2.2.0"
        }
    }

Transaction declined

Next steps

For responses related to Fingerprinting required or the Challenge flow required, gather browser fingerprints using JavaScript. The SDK performs the fingerprinting or challenge notification flow.

After the fingerprinting is complete, it dispatches an event (executePatch) with the updated status under \_evt.detail.3DSStatus. Implement the event-listener while initializing the SDK to fetch the updated status under \_evt.detail.3DSStatus.

Method-notification flow

	window.\_3DSUtil.perform3DSFingerPrinting({  
    {{\_3DSServerTransId}},  
    {{acsMethodUrl}},  
    {{methodNotificationUrl}}  
});

Response: Success, decline or a challenge flow.

Challenge-notification flow

window.clover3DSUtil.perform3DSChallenge({  
        messageVersion,  
        acsTransID,  
        acsUrl,  
        threeDSServerTransID  
});

Response: Success or decline.

Configure webhook

Add theexecutePatch eventListener handler to finalize the 3DS transaction.

curl --location 'https:///scl-sandbox.dev.clover.com/v1/charges/v1/charges/finalize_payment' \
--header 'Authorization: Bearer f5f3ef06361d8d5f38165f80fecacfbe' \
--header 'Content-Type: application/json' \
--data '{
    "charge_id": {{charge_id obtained from v1/charge call}},
    "threeds": {
        "source": "CLOVER",
        "flow_status": event?.detail?._3DSStatus
    }
}'