Enroll Card for 3D Secure

Overview

After creating cardholder contact information, use this endpoint to enroll a card for 3D Secure authentication. This process links the cardholder's contact details (email and mobile number) with a specific card, enabling OTP delivery during 3DS transactions.

NOTE: This API is offered on a client-by-client approval basis. Speak to your account manager to check eligibility.

Resource Access

Production (api.ahrvo.network)

POST https://api.ahrvo.network/card/issuance/api/issuing/3ds/v2/enroll

Staging (gateway.ahrvo.network)

POST https://gateway.ahrvo.network/card/issuance/api/issuing/3ds/v2/enroll

---

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
x-api-key	API Key	Yes	API key for authentication
Content-Type	application/json	Yes	Request body content type

Request Body

The request body should contain a JSON object with the following structure:

{
  "card_id": "card59202507231957437131",
  "cardholder_id": "471041678120300545"
}

Request Fields

Field	Type	Required	Description
card_id	string	Yes	A unique ID of the card to enroll for 3DS
cardholder_id	string	Yes	A unique ID of the cardholder (obtained from create cardholder endpoint)

Response

Success Response (200 OK)

{
  "code": "SUCCESS",
  "data": {
    "isSuccess": true
  }
}

Response Fields

Field	Type	Description
code	string	Status string indicating the result. "SUCCESS" refers to successful enrollment
data	object	Response data object
data.isSuccess	boolean	Boolean indicating if the enrollment was successful

Error Responses

• 400 Bad Request: Invalid card_id or cardholder_id provided
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: 3DS feature not enabled for this account
• 404 Not Found: Card or cardholder does not exist
• 409 Conflict: Card already enrolled for 3DS

Code Examples

cURL

curl -X POST \
  'https://gateway.ahrvo.network/card/issuance/api/issuing/3ds/v2/enroll' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_id": "card59202507231957437131",
    "cardholder_id": "471041678120300545"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/card/issuance/api/issuing/3ds/v2/enroll"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "card_id": "card59202507231957437131",
    "cardholder_id": "471041678120300545"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/card/issuance/api/issuing/3ds/v2/enroll';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'x-api-key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
};
const data = {
  card_id: 'card59202507231957437131',
  cardholder_id: '471041678120300545'
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• Prerequisites: You must first create cardholder contact information using the Create Cardholder 3DS Contact endpoint
• One Card, One Cardholder: Each card can be enrolled with only one cardholder's contact information
• Re-enrollment: If you need to update the cardholder information for a card, you must first unenroll it
• Card Status: The card must be in an active state to be enrolled for 3DS
• Immediate Effect: Once enrolled, the card is immediately ready for 3DS transactions

3D Secure Enrollment Flow

1. Create Cardholder: Register cardholder contact information (email and mobile)
2. Enroll Card: Use this endpoint to link the cardholder with a specific card
3. 3DS Ready: Card is now enrolled and ready for 3D Secure transactions
4. Transaction Flow: During a 3DS transaction, OTP will be sent to the registered contact
5. Authentication: Cardholder enters OTP to complete the secure transaction

Best Practices

• Verify Prerequisites: Ensure both card and cardholder exist before enrollment
• Store Enrollment Status: Keep track of which cards are 3DS-enrolled in your system
• Handle Errors: Implement proper error handling, especially for 409 conflicts
• Test Enrollment: Test the complete enrollment flow in sandbox before production
• User Communication: Inform cardholders when their card is enrolled for 3DS

Common Use Cases

New Card Issuance

When issuing a new card to a customer who requires 3DS:

1. Create the cardholder profile
2. Issue the card
3. Enroll the card for 3DS

Existing Card Upgrade

For existing cards that need 3DS enrollment:

1. Verify cardholder information exists (or create it)
2. Enroll the existing card
3. Notify the cardholder of the enhanced security

Bulk Enrollment

For enrolling multiple cards:

1. Create cardholder profiles in batch
2. Iterate through cards and enroll each one
3. Track successful and failed enrollments

Related Endpoints

• Create Cardholder 3DS Contact - Create the cardholder profile (prerequisite)
• Unenroll Card from 3DS - Remove 3DS enrollment from a card
• Update Cardholder Contact - Update existing cardholder information
• Get Card 3DS Status - Check if a card is enrolled for 3DS

Troubleshooting

Card Not Found (404)

• Verify the card_id is correct and the card exists
• Check that the card belongs to your account

Cardholder Not Found (404)

• Verify the cardholder_id is correct
• Ensure you've created the cardholder using the Create Cardholder endpoint

Already Enrolled (409)

• The card is already enrolled for 3DS
• If you need to change the cardholder, first unenroll the card

Forbidden (403)

• Contact your account manager to enable 3DS for your account
• Verify your API credentials have permission for 3DS operations

Interactive API Explorer