Create Cardholder 3DS Contact

Overview

Cardholder contact information is required to enroll a card for 3D Secure authentication. A 3D Secure transaction prompts the cardholder to enter an OTP (One-Time Password) sent to their email or mobile device. Use this endpoint to set up the email and mobile contact to receive the OTP.

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/cardholders/v2/create

Staging (gateway.ahrvo.network)

POST https://gateway.ahrvo.network/card/issuance/api/issuing/cardholders/v2/create

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:

{
  "budget_id": "ci202008281528472924",
  "first_name": "Emma",
  "last_name": "Johnson",
  "call_prefix": "+1",
  "mobile": "2125551234",
  "email": "emma.johnson@example.com",
  "date_of_birth": "1996-10-31",
  "state": "Illinois",
  "city": "Chicago",
  "address_line": "456 Maple Avenue",
  "post_code": "60601",
  "country_code": "US",
  "security_index": "2",
  "security_answer": "Han"
}

Request Fields

Field	Type	Required	Description
`budget_id`	string	Yes	ID of the budget account this cardholder associates with
`first_name`	string	Yes	First name of the cardholder
`last_name`	string	Yes	Last name of the cardholder
`call_prefix`	string	Yes	Country code of the mobile. Supported: +61, +1, +44, +852, +81, +82, +65, +90, +86, +33
`mobile`	string	Yes	Mobile number of the cardholder, without country code
`email`	string	Yes	Email of the cardholder
`date_of_birth`	string	Yes	Date of birth of the cardholder (YYYY-MM-DD)
`state`	string	Yes	State of the cardholder
`city`	string	Yes	City of the cardholder
`address_line`	string	Yes	Address of the cardholder
`post_code`	string	Yes	Post code of the cardholder
`country_code`	string	Yes	Country of the cardholder in ISO 3166 format (e.g., US)
`security_index`	string	Yes	Index of security question (1-5)
`security_answer`	string	Yes	Answer to the security question

Security Questions

The security_index field corresponds to the following questions:

Index	Security Question
`1`	What was your first pet's name?
`2`	What is your maternal grandmother's maiden name?
`3`	What is the name of your favourite childhood friend?
`4`	What was the make of your first car?
`5`	In what city or town did your mother and father meet?

Supported Country Codes (call_prefix)

+1 - United States, Canada
+33 - France
+44 - United Kingdom
+61 - Australia
+65 - Singapore
+81 - Japan
+82 - South Korea
+86 - China
+90 - Turkey
+852 - Hong Kong

Response

Success Response (200 OK)

{
  "code": "SUCCESS",
  "data": {
    "cardholder_id": "471041678120300545"
  }
}

Response Fields

Field	Type	Description
`code`	string	Status string indicating the result. "SUCCESS" refers to successful cardholder creation
`data`	object	Response data object
`data.cardholder_id`	string	Unique ID of the created cardholder

Error Responses

400 Bad Request: Invalid input data (invalid email format, missing required fields)
401 Unauthorized: Invalid or missing authentication token
403 Forbidden: API not enabled for this account
409 Conflict: Cardholder already exists for this budget account

Code Examples

cURL

curl -X POST \
  'https://gateway.ahrvo.network/card/issuance/api/issuing/cardholders/v2/create' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "budget_id": "ci202008281528472924",
    "first_name": "Emma",
    "last_name": "Johnson",
    "call_prefix": "+1",
    "mobile": "2125551234",
    "email": "emma.johnson@example.com",
    "date_of_birth": "1996-10-31",
    "state": "Illinois",
    "city": "Chicago",
    "address_line": "456 Maple Avenue",
    "post_code": "60601",
    "country_code": "US",
    "security_index": "2",
    "security_answer": "Han"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/card/issuance/api/issuing/cardholders/v2/create"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "budget_id": "ci202008281528472924",
    "first_name": "Emma",
    "last_name": "Johnson",
    "call_prefix": "+1",
    "mobile": "2125551234",
    "email": "emma.johnson@example.com",
    "date_of_birth": "1996-10-31",
    "state": "Illinois",
    "city": "Chicago",
    "address_line": "456 Maple Avenue",
    "post_code": "60601",
    "country_code": "US",
    "security_index": "2",
    "security_answer": "Han"
}

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/cardholders/v2/create';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  budget_id: 'ci202008281528472924',
  first_name: 'Emma',
  last_name: 'Johnson',
  call_prefix: '+1',
  mobile: '2125551234',
  email: 'emma.johnson@example.com',
  date_of_birth: '1996-10-31',
  state: 'Illinois',
  city: 'Chicago',
  address_line: '456 Maple Avenue',
  post_code: '60601',
  country_code: 'US',
  security_index: '2',
  security_answer: 'Han'
};

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

Usage Notes

3D Secure Enrollment: This endpoint creates the cardholder profile required for 3D Secure authentication
OTP Delivery: The email and mobile number will be used to send OTP codes during 3DS authentication
Security Questions: Choose a security question and answer that the cardholder can easily remember
Data Privacy: Ensure all personal information is collected with proper consent
Account Approval: This feature requires explicit approval from your account manager
One Cardholder per Budget: Each budget account can have one associated cardholder for 3DS

3D Secure Authentication Flow

Create Cardholder: Use this endpoint to register cardholder contact information
Enroll Card: Associate the cardholder with a card for 3DS authentication
Transaction Initiated: When a 3DS transaction occurs, an OTP is sent to the registered email/mobile
Cardholder Verification: Cardholder enters the OTP to complete the transaction
Transaction Completed: Upon successful verification, the transaction is processed

Best Practices

Verify Contact Information: Ensure email and mobile number are valid and belong to the cardholder
Secure Storage: Store the cardholder_id securely for future reference
Update Information: Provide a way for cardholders to update their contact information
Test in Sandbox: Test the complete 3DS flow in sandbox environment before going live
Handle Errors: Implement proper error handling for failed cardholder creation

Update Cardholder Contact - Update existing cardholder information
Get Cardholder Details - Retrieve cardholder information
Enroll Card for 3DS - Associate a card with the cardholder

Overview​

Resource Access​

Request Headers​

Request Body​

Request Fields​

Security Questions​

Supported Country Codes (call_prefix)​

Response​

Success Response (200 OK)​

Response Fields​

Error Responses​

Code Examples​

cURL​

Python​

JavaScript (Node.js)​

Usage Notes​

3D Secure Authentication Flow​

Best Practices​

Related Endpoints​

Interactive API Explorer​