API Reference

3D Secure (3DS)

Understanding 3D Secure authentication in the Kulipa system

Introduction to 3D Secure (3DS)

3D Secure (3DS) is an authentication protocol that adds an extra layer of security for online card transactions. When a cardholder makes an online purchase, 3DS may require additional authentication to verify the cardholder's identity before authorizing the transaction. 3DS requests expire after 570 seconds. If not approved in that timeframe, the request is cancelled and the payment is not made.

In the Kulipa system, 3DS is primarily implemented as an Out-Of-Band (OOB) authentication mechanism where users receive authentication requests in their wallet application and must confirm transactions using cryptographic signatures. The system also provides a fallback to SMS authentication when needed.

3DS Process Flow

The complete 3DS authentication process in Kulipa involves several steps from the initial online purchase to the final transaction completion:

sequenceDiagram
    participant User
    participant Merchant
    participant PaymentNetwork
    participant Kulipa
    participant WalletApp

    User->>Merchant: Initiates online purchase
    Merchant->>PaymentNetwork: Sends payment request
    PaymentNetwork->>Kulipa: 3DS authentication request
    Kulipa->>WalletApp: Sends cardAuthentication.created event
    Note over WalletApp: User sees authentication prompt
    WalletApp->>User: Displays transaction details
    User->>WalletApp: Reviews and signs authentication
    WalletApp->>Kulipa: Submits signed authentication
    Kulipa->>PaymentNetwork: Authentication result
    PaymentNetwork->>Merchant: Transaction authorized
    Kulipa->>WalletApp: Transaction completed

Authentication Methods

Kulipa supports multiple authentication methods for 3DS confirmation depending on your program configuration:

Wallet Signature Authentication

When wallet verification is required, Kulipa requires cryptographically signed payloads from the user's wallet to confirm 3DS authentication. The following examples show the payload structure:

EVM Wallets

  • Uses EIP-712 typed data signing
  • Domain includes chain ID and version information
  • Message contains the 3DS authentication ID
{
  "types": {
    "EIP712Domain": [
      { "name": "name", "type": "string" },
      { "name": "version", "type": "string" },
      { "name": "chainId", "type": "uint256" }
    ],
    "Authenticate": [{ "name": "id", "type": "string" }]
  },
  "primaryType": "Authenticate",
  "domain": {
    "name": "Kulipa Wallet Authentication",
    "version": "1",
    "chainId": 1
  },
  "message": {
    "id": "3ds-e259ee22-f857-444d-9c38-e0bf2ee669e3"
  }
}

Starknet Wallets

  • Uses Starknet typed data signing
  • Domain includes chain ID and revision information
  • Message structure optimized for Starknet
{
  "types": {
    "StarknetDomain": [
      { "name": "name", "type": "shortstring" },
      { "name": "version", "type": "shortstring" },
      { "name": "chainId", "type": "shortstring" },
      { "name": "revision", "type": "shortstring" }
    ],
    "Authenticate": [{ "name": "id", "type": "string" }]
  },
  "primaryType": "Authenticate",
  "domain": {
    "name": "Kulipa Wallet Authentication",
    "version": "1",
    "chainId": "SN_MAIN",
    "revision": "1"
  },
  "message": {
    "id": "3ds-03f278e1-2603-4502-a936-5913d242c5e8"
  }
}

ECDSA Signature Authentication

When wallet verification is not required, Kulipa requires a signed payload with the shared private ECDSA key instead of requiring wallet signatures from users.

The payload structure for ECDSA authentication contains only the essential fields:

{
  "primaryType": "Authenticate",
  "message": {
    "id": "3ds-e259ee22-f857-444d-9c38-e0bf2ee669e3"
  }
}

You must:

  1. Canonicalize the payload using JSON canonicalization
  2. Sign the canonicalized payload using your private ECDSA key (secp256k1 curve)
  3. Submit the signature in the signatures array

The distributor public key will be exchanged during onboarding.

Integration Guide

1. Webhook Events

When a 3DS authentication is required, your wallet application will receive a cardAuthentication.created event via webhooks. This event contains all the necessary transaction details for user verification. See Webhook Events for the complete event schema.

2. Authentication Decision

Use the 3DS authentication endpoints to accept or reject authentication requests:

3. Testing

In sandbox environments, use the 3DS simulation endpoint to test the complete flow:

See also