Adding Customers to Vault

Add a new customer to the vault with their payment information by calling the NMI Payments API.


API Key Configuration Security Key You can find your API security key at key management under 'Merchant keys'.

This key is private and should be kept secure on your server. It authenticates your merchant account and authorizes vault operations.

Your sandbox key has been included in the code sample on the right.

Security: Never expose your API security key in client-side code. Always keep it secure on your server. While we have included your test key in the code sample, you should not commit it to source control and instead inject it via an environment variable.

Server-side Example

// Add customer to vault using payment token
const express = require('express');
const axios = require('axios');
const router = express.Router();

router.post('/add-to-vault', async (req, res) => {
  try {
    const { paymentToken, customerId, firstName, lastName, email } = req.body;
    
    // Call NMI's Direct Post API
    const response = await axios.post('https://secure.networkmerchants.com/api/transact.php', {
      security_key: '{user.privateApiKey}',
      customer_vault: 'add_customer',
      payment_token: paymentToken,
      customer_vault_id: customerId,
      first_name: firstName,
      last_name: lastName,
      email: email
    });
    
    // Check for successful response (response code 1)
    if (response.data.response === '1') {
      return res.json({
        success: true,
        customerVaultId: response.data.customer_vault_id
      });
    } else {
      return res.json({
        success: false,
        error: response.data.responsetext
      });
    }
  } catch (error) {
    console.error('Error adding to vault:', error);
    return res.status(500).json({
      success: false,
      error: 'An error occurred while adding to vault'
    });
  }
});

module.exports = router;
# Add customer to vault using payment token
import requests
from urllib.parse import urlencode

def add_to_vault(payment_token, customer_data):
    try:
        payload = {
            'security_key': '{user.privateApiKey}',
            'customer_vault': 'add_customer',
            'payment_token': payment_token,
            'customer_vault_id': customer_data['customerId'],
            'first_name': customer_data['firstName'],
            'last_name': customer_data['lastName'],
            'email': customer_data['email']
        }
        
        response = requests.post(
            'https://secure.networkmerchants.com/api/transact.php',
            data=payload
        )
        
        # Parse the response (NMI returns form-encoded data)
        response_data = dict(x.split('=') for x in response.text.split('&'))
        
        if response_data.get('response') == '1':
            print('Customer added to vault successfully')
            return response_data.get('customer_vault_id')
        else:
            raise Exception(response_data.get('responsetext', 'Failed to add customer to vault'))
            
    except Exception as error:
        print(f'Error adding to vault: {error}')
        raise error

# Example usage
def handle_add_to_vault():
    customer_data = {
        'customerId': 'cust_12345',
        'firstName': 'John',
        'lastName': 'Doe',
        'email': '[email protected]'
    }
    
    # payment_token comes from your payment component
    vault_id = add_to_vault(payment_token, customer_data)
    print(f'Customer vault ID: {vault_id}')
// Add customer to vault using payment token
@PostMapping("/add-to-vault")
public ResponseEntity<Map<String, Object>> addToVault(@RequestBody VaultRequest request) {
    try {
        // Prepare the request to NMI's API
        RestTemplate restTemplate = new RestTemplate();
        
        MultiValueMap<String, String> params = new LinkedMultiValueMap<>();
        params.add("security_key", "{user.privateApiKey}");
        params.add("customer_vault", "add_customer");
        params.add("payment_token", request.getPaymentToken());
        params.add("customer_vault_id", request.getCustomerId());
        params.add("first_name", request.getFirstName());
        params.add("last_name", request.getLastName());
        params.add("email", request.getEmail());
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
        
        HttpEntity<MultiValueMap<String, String>> entity = new HttpEntity<>(params, headers);
        
        // Call NMI's Direct Post API
        ResponseEntity<String> response = restTemplate.exchange(
            "https://secure.networkmerchants.com/api/transact.php",
            HttpMethod.POST,
            entity,
            String.class
        );
        
        // Parse response (query string format)
        Map<String, String> responseData = parseQueryString(response.getBody());
        
        Map<String, Object> result = new HashMap<>();
        
        // Check for successful response (response code 1)
        if ("1".equals(responseData.get("response"))) {
            result.put("success", true);
            result.put("customerVaultId", responseData.get("customer_vault_id"));
        } else {
            result.put("success", false);
            result.put("error", responseData.getOrDefault("responsetext", "Failed to add customer to vault"));
        }
        
        return ResponseEntity.ok(result);
        
    } catch (Exception error) {
        System.err.println("Error adding to vault: " + error.getMessage());
        
        Map<String, Object> errorResult = new HashMap<>();
        errorResult.put("success", false);
        errorResult.put("error", "An error occurred while adding to vault");
        
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(errorResult);
    }
}
// Add customer to vault using payment token
[HttpPost("add-to-vault")]
public async Task<IActionResult> AddToVault([FromBody] VaultRequest request)
{
    try
    {
        var formData = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("security_key", "{user.privateApiKey}"),
            new KeyValuePair<string, string>("customer_vault", "add_customer"),
            new KeyValuePair<string, string>("payment_token", request.PaymentToken),
            new KeyValuePair<string, string>("customer_vault_id", request.CustomerId),
            new KeyValuePair<string, string>("first_name", request.FirstName),
            new KeyValuePair<string, string>("last_name", request.LastName),
            new KeyValuePair<string, string>("email", request.Email)
        });
        
        var response = await _httpClient.PostAsync(
            "https://secure.networkmerchants.com/api/transact.php",
            formData
        );
        
        var responseContent = await response.Content.ReadAsStringAsync();
        var responseData = ParseQueryString(responseContent);
        
        if (responseData.ContainsKey("response") && responseData["response"] == "1")
        {
            return Ok(new
            {
                success = true,
                customerVaultId = responseData.GetValueOrDefault("customer_vault_id")
            });
        }
        else
        {
            return BadRequest(new
            {
                success = false,
                error = responseData.GetValueOrDefault("responsetext", "Failed to add customer to vault")
            });
        }
    }
    catch (Exception ex)
    {
        return StatusCode(500, new
        {
            success = false,
            error = "An error occurred while adding to vault"
        });
    }
}
<?php
// Add customer to vault using payment token
function addToVault($paymentToken, $customerData) {
    try {
        $payload = [
            'security_key' => '{user.privateApiKey}',
            'customer_vault' => 'add_customer',
            'payment_token' => $paymentToken,
            'customer_vault_id' => $customerData['customerId'],
            'first_name' => $customerData['firstName'],
            'last_name' => $customerData['lastName'],
            'email' => $customerData['email']
        ];
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://secure.networkmerchants.com/api/transact.php');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($payload));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($response === false) {
            throw new Exception('cURL error occurred');
        }
        
        // Parse the response (NMI returns form-encoded data)
        parse_str($response, $responseData);
        
        if ($responseData['response'] === '1') {
            return [
                'success' => true,
                'customerVaultId' => $responseData['customer_vault_id']
            ];
        } else {
            return [
                'success' => false,
                'error' => $responseData['responsetext'] ?? 'Failed to add customer to vault'
            ];
        }
        
    } catch (Exception $error) {
        error_log('Error adding to vault: ' . $error->getMessage());
        return [
            'success' => false,
            'error' => 'An error occurred while adding to vault'
        ];
    }
}

// Example usage
function handleAddToVault() {
    $customerData = [
        'customerId' => 'cust_12345',
        'firstName' => 'John',
        'lastName' => 'Doe',
        'email' => '[email protected]'
    ];
    
    // $paymentToken comes from your payment component
    $result = addToVault($paymentToken, $customerData);
    
    if ($result['success']) {
        echo 'Customer vault ID: ' . $result['customerVaultId'];
    } else {
        echo 'Error: ' . $result['error'];
    }
}

// REST API endpoint example
if ($_SERVER['REQUEST_METHOD'] === 'POST' && $_SERVER['REQUEST_URI'] === '/add-to-vault') {
    header('Content-Type: application/json');
    
    $input = json_decode(file_get_contents('php://input'), true);
    
    if (!$input) {
        http_response_code(400);
        echo json_encode(['success' => false, 'error' => 'Invalid JSON input']);
        exit;
    }
    
    $result = addToVault(
        $input['paymentToken'],
        [
            'customerId' => $input['customerId'],
            'firstName' => $input['firstName'],
            'lastName' => $input['lastName'],
            'email' => $input['email']
        ]
    );
    
    if ($result['success']) {
        http_response_code(200);
    } else {
        http_response_code(500);
    }
    
    echo json_encode($result);
}
?>
<?php
// app/Http/Controllers/CustomerVaultController.php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class CustomerVaultController extends Controller
{
    /**
     * Delete customer from vault
     */
    public function deleteVault(Request $request): JsonResponse
    {
        $request->validate([
            'customerVaultId' => 'required|string'
        ]);

        try {
            $response = Http::asForm()->post('https://secure.networkmerchants.com/api/transact.php', [
                'security_key' => '{user.privateApiKey}',
                'customer_vault' => 'delete_customer',
                'customer_vault_id' => $request->customerVaultId
            ]);

            $responseData = $this->parseNmiResponse($response->body());

            if ($responseData['response'] === '1') {
                return response()->json(['success' => true]);
            } else {
                return response()->json([
                    'success' => false,
                    'error' => $responseData['responsetext'] ?? 'Failed to delete customer'
                ], 400);
            }

        } catch (\Exception $e) {
            Log::error('Error deleting from vault: ' . $e->getMessage());
            
            return response()->json([
                'success' => false,
                'error' => 'An error occurred while deleting from vault'
            ], 500);
        }
    }

    /**
     * Parse NMI's form-encoded response
     */
    private function parseNmiResponse(string $response): array
    {
        parse_str($response, $data);
        return $data;
    }
}