Card Vault connector

Elavon Converge.

Charge a card stored in Card Vault through Converge's XML API, without the card number touching your servers.

How it works

Converge takes transactions as an XML document posted in a form field named xmldata. You build that request as usual, put the Card Vault placeholders where the card data goes, and send it to the Card Vault proxy with the card's token. The proxy fills in the card data, sends the request to Converge and returns Converge's reply unchanged.

Before you start

  • A Converge account with an API user. You need the account ID (ssl_merchant_id), the API user ID (ssl_user_id) and its terminal PIN (ssl_pin). For testing, use a Converge demo account; its requests go to api.demo.convergepay.com.
  • A card stored in Card Vault, and its token. To send the CVV, store the card with a CVV and a ttl; the CVV is kept only until then.
  • If you set a proxy domain allowlist on your client ID, add api.convergepay.com (and api.demo.convergepay.com for testing).

Fill in your own values where the examples say YOUR_.... The card placeholders, such as ${ccn}, stay as they are: the proxy replaces them.

Charge a stored card (ccsale)

Authorizes and captures the amount in one step. Change ssl_amount (dollars and cents, with a decimal point) and ssl_invoice_number for each order.

What Elavon Converge receives

POST https://api.convergepay.com/VirtualMerchant/processxml.do (testing: https://api.demo.convergepay.com/VirtualMerchantDemo/processxml.do), with this body (laid out for reading; the request sends it as one line):

xmldata=<txn>
  <ssl_merchant_id>YOUR_MERCHANT_ID</ssl_merchant_id>
  <ssl_user_id>YOUR_USER_ID</ssl_user_id>
  <ssl_pin>YOUR_PIN</ssl_pin>
  <ssl_transaction_type>ccsale</ssl_transaction_type>
  <ssl_card_number>${ccn}</ssl_card_number>
  <ssl_exp_date>${mm}${yy}</ssl_exp_date>
  <ssl_cvv2cvc2_indicator>1</ssl_cvv2cvc2_indicator>
  <ssl_cvv2cvc2>${cvv}</ssl_cvv2cvc2>
  <ssl_amount>10.00</ssl_amount>
  <ssl_invoice_number>INV-1001</ssl_invoice_number>
</txn>

The Card Vault proxy request

$ENIGMA_TOKEN is your Enigma Vault access token and $CARD_TOKEN the stored card's token. The quoted EOF keeps your shell from touching the ${...} placeholders.

curl -X POST https://api.enigmavault.io/cardvault/proxy \
  -H "Authorization: Bearer $ENIGMA_TOKEN" \
  -H "x-api-version: 1.14" \
  -H "cardToken: $CARD_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "url": "https://api.convergepay.com/VirtualMerchant/processxml.do",
  "httpMethod": "POST",
  "headers": [
    {
      "name": "Content-Type",
      "value": "application/x-www-form-urlencoded"
    }
  ],
  "body": "xmldata=<txn><ssl_merchant_id>YOUR_MERCHANT_ID</ssl_merchant_id><ssl_user_id>YOUR_USER_ID</ssl_user_id><ssl_pin>YOUR_PIN</ssl_pin><ssl_transaction_type>ccsale</ssl_transaction_type><ssl_card_number>${ccn}</ssl_card_number><ssl_exp_date>${mm}${yy}</ssl_exp_date><ssl_cvv2cvc2_indicator>1</ssl_cvv2cvc2_indicator><ssl_cvv2cvc2>${cvv}</ssl_cvv2cvc2><ssl_amount>10.00</ssl_amount><ssl_invoice_number>INV-1001</ssl_invoice_number></txn>"
}
EOF

Reading the reply

The proxy answers 200 with statusCode, contentType, headers and body from Elavon Converge. Converge answers HTTP 200 for approvals, declines and errors alike, so read the XML in the proxy response's body. <ssl_result>0</ssl_result> with <ssl_result_message>APPROVAL</ssl_result_message> is an approval; keep ssl_txn_id for refunds and voids. Any other ssl_result is a decline. A request Converge could not process comes back as <errorCode>, <errorName> and <errorMessage> instead.

Authorize only (ccauthonly)

Places a hold for the amount without capturing it, for example when you charge at shipping or check-out. Capture it later with a cccomplete request that carries the ssl_txn_id; that request has no card data, so send it to Converge directly rather than through the proxy.

What Elavon Converge receives

POST https://api.convergepay.com/VirtualMerchant/processxml.do (testing: https://api.demo.convergepay.com/VirtualMerchantDemo/processxml.do), with this body (laid out for reading; the request sends it as one line):

xmldata=<txn>
  <ssl_merchant_id>YOUR_MERCHANT_ID</ssl_merchant_id>
  <ssl_user_id>YOUR_USER_ID</ssl_user_id>
  <ssl_pin>YOUR_PIN</ssl_pin>
  <ssl_transaction_type>ccauthonly</ssl_transaction_type>
  <ssl_card_number>${ccn}</ssl_card_number>
  <ssl_exp_date>${mm}${yy}</ssl_exp_date>
  <ssl_cvv2cvc2_indicator>1</ssl_cvv2cvc2_indicator>
  <ssl_cvv2cvc2>${cvv}</ssl_cvv2cvc2>
  <ssl_amount>10.00</ssl_amount>
  <ssl_invoice_number>INV-1002</ssl_invoice_number>
</txn>

The Card Vault proxy request

$ENIGMA_TOKEN is your Enigma Vault access token and $CARD_TOKEN the stored card's token. The quoted EOF keeps your shell from touching the ${...} placeholders.

curl -X POST https://api.enigmavault.io/cardvault/proxy \
  -H "Authorization: Bearer $ENIGMA_TOKEN" \
  -H "x-api-version: 1.14" \
  -H "cardToken: $CARD_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "url": "https://api.convergepay.com/VirtualMerchant/processxml.do",
  "httpMethod": "POST",
  "headers": [
    {
      "name": "Content-Type",
      "value": "application/x-www-form-urlencoded"
    }
  ],
  "body": "xmldata=<txn><ssl_merchant_id>YOUR_MERCHANT_ID</ssl_merchant_id><ssl_user_id>YOUR_USER_ID</ssl_user_id><ssl_pin>YOUR_PIN</ssl_pin><ssl_transaction_type>ccauthonly</ssl_transaction_type><ssl_card_number>${ccn}</ssl_card_number><ssl_exp_date>${mm}${yy}</ssl_exp_date><ssl_cvv2cvc2_indicator>1</ssl_cvv2cvc2_indicator><ssl_cvv2cvc2>${cvv}</ssl_cvv2cvc2><ssl_amount>10.00</ssl_amount><ssl_invoice_number>INV-1002</ssl_invoice_number></txn>"
}
EOF

Reading the reply

The proxy answers 200 with statusCode, contentType, headers and body from Elavon Converge. Read the reply as for a sale: <ssl_result>0</ssl_result> is an approved authorization.

Things to know

  • No CVV. For a repeat charge after the CVV has expired, set <ssl_cvv2cvc2_indicator>0</ssl_cvv2cvc2_indicator> and leave out the ssl_cvv2cvc2 element. Sending ${cvv} with no CVV stored sends an empty value.
  • Expiry. ${mm}${yy} becomes the four-digit MMYY date Converge expects, for example 0330.
  • Names and addresses. If your Converge settings require cardholder or address fields (ssl_first_name, ssl_avs_address, ssl_avs_zip), add them to the XML. Card Vault inserts ${firstName} and ${lastName} exactly as stored, without XML escaping, so write your own values for any field that may contain & or <.
  • Allowlisting our addresses. If your Converge account restricts the addresses it accepts, the proxy calls from 18.210.171.115 and 44.196.108.239 (United States) and 18.200.188.77 and 63.35.37.99 (EU data residency).

See also all connectors, the API reference for POST /cardvault/proxy, and the proxy's addresses. Questions: support@enigmavault.io.