Objects Customer Data

• STRUCTURE
• EXAMPLE

The customer data data object represents the customer's billing information, which is typically required for the card payment processing.

STRUCTURE

✓ - required value
? - optional, value or null
✕ - always appears as null

Supported Profiles

Plain-Text Properties

When using the "plain-text properties" option, the customer_data object should be structured using the properties described in the table above (excluding encrypted property).

EXAMPLE

{
    "country": "GB",
    "first_name": "John",
    "last_name": "Johnson",
    "dob": "12\/31\/1980",
    "email": "[email protected]",
    "phone": 44201112222,
    "zip": "WC2N 5DU",
    "state": "JS",
    "city": "London",
    "address": "Random st., 12\/3",
    "profile": 1
}

Encrypted properties

This method provides a more secure way to transmit customer information in requests to the Praxis API.

When using the "encrypted properties" option, instead of providing individual properties for each customer data attribute, the request should contain only the encrypted parameter within the customer_data object.

This parameter contains an encrypted string representing the entire customer data object.

The encryption must be performed using the AES-256-GCM algorithm.

• Key - Data Encryption Key generated on Atlas.
• IV (Initialization Vector) - A randomly generated 12-byte value. Use a cryptographically secure random number generator (CSRNG) to generate the IV.

Data Encryption Keys can be generated in Atlas → Accounts (API) → Manage Data Encryption Keys section.

The resulting encrypted value must be a base64-encoded string representing a JSON object with the following parameters:

• iv - Base64-encoded value of the generated IV.
• ciphertext - Base64-encoded value of the generated ciphertext.
• tag - Base64-encoded value of the generated authentication tag.

Code Example

<?php

/**
 * Method for encryption PII details using AES-GCM algorithm
 *
 * @param  string $valueForEncryption The parameter to be encrypted
 * @param  string $dataEncryptionKey    Merchant's data encryption key
 *
 * @return  string|false
 */
function encrypt(string $valueForEncryption, string $dataEncryptionKey): string
{
    $method = "aes-256-gcm";

    //  Validate the key length
    if (strlen($dataEncryptionKey) !== 32) {
        return false; // Key must be 32 bytes (256 bits)
    }

    $iv = openssl_random_pseudo_bytes(12);  // GCM uses 12-byte IV
    $tag = ""; // Will be populated by openssl_encrypt

    $ciphertext = openssl_encrypt(
        $valueForEncryption,
        $method,
        $dataEncryptionKey,
        OPENSSL_RAW_DATA,
        $iv,
        $tag, // Pass by reference to get the tag
        16    // Tag length
    );

    if ($ciphertext === false) {
        return false; // Encryption failed
    }

    $iv_b64 = base64_encode($iv);
    $ciphertext_b64 = base64_encode($ciphertext);
    $tag_b64 = base64_encode($tag);

    // Prepend the IV, and tag  to the ciphertext and base64 encode
    return base64_encode(json_encode([
        'iv' => $iv_b64,
        'ciphertext' => $ciphertext_b64,
        'tag' => $tag_b64,
    ]));
}

// Example usage
$customerData = [
    "country" => "GB",
    "first_name" => "John",
    "last_name" => "Johnson",
    "dob" => "12/31/1980",
    "email" => "[email protected]",
    "phone" => 44201112222,
    "zip" => "WC2N 5DU",
    "state" => "JS",
    "city" => "London",
    "address" => "Random st., 12/3",
    "profile" => 1
];

$plaintext = json_encode($customerData);

$encryptionKey = "DATA_ENCRYPTION_KEY"; // 32-byte key

// Encrypt
$encrypted = encrypt($plaintext, $encryptionKey);

if ($encrypted !== false) {
    echo "Encrypted: " . $encrypted . "\n";
} else {
    echo "Encryption failed.\n";
}

Result Example

{
"encrypted": "eyJpdl9iNjQiOiJnMzFCWFhTY2g5eEVxTmpsIiwiY2lwaGVydGV4dF9iNjQiOiJwZ2FqdG5NYnNveGFwakJQK2Z5MmJ6KzRrR0hMbDNXVk1oUkY5Y21wWlRJZXVSWVFlTnVOM1J3Q0F4RDVLUzJjVnBDZXZSVmFVWFN5RkZ4NmlxVnp6NFwvSUxjM0VcL1REUjE1Q1czUFwvN3VTU1ozTW9jUjcwV0ZuMlVBa2VJOFpKV1dwd1lPK0NTRlBhUHJob1ZFbzc4VDBFeFFYWlRMQWlWVzR0VjM1MForXC9IOTV5TEJzc3pNcnQ0Q1g2SDk3VUt4RDdkSUdTaXpzUEFzQlMrZlVKVkQ5bm1ha2tTZ1hqVHZtOXpYQlU4SDk5OWFuNjI0Yys1RE9NSTdaMnliaUg5aXg0K2R0V0N5cTBLSFFZajNYR0lnOVwveFVwelJSMjZnNHo3b1JTaFE9IiwidGFnX2I2NCI6IlNFSWZ2dEJiZHY4d1RVcmJ4TVVrM1E9PSJ9"
}