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.
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 requires cryptographically signed payloads 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"
}
}
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:
- Accept:
POST /3ds/{id}/accept
- Reject:
POST /3ds/{id}/reject
3. Testing
In sandbox environments, use the 3DS simulation endpoint to test the complete flow:
- Simulate:
POST /simulate/3ds