Add Card

If 3-D Secure (3DS) data is provided, the card can be verified during the add step.

Common use: enroll a customer’s card for future payments and refunds (tokenized), optionally verifying via 3DS.

Endpoint

POST https://secure.3gdirectpay.com/API/v6/

Headers

Content-Type: application/xml; charset=utf-8
Accept: application/xml

Request

Required Fields

CustomerThreeD object

Example Request (XML)

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <CompanyToken>68B90B5E-25F6-4146-8AB1-C7A3A0C41A7F</CompanyToken>
  <Request>addCard</Request>
  <customerToken>E6C04D7E-C267-4243-BD1C-49170F8A008B</customerToken>
  <CustomerCreditCard>4111111111111111</CustomerCreditCard>
  <CustomerExpiry>1225</CustomerExpiry>
  <CustomerCvv>123</CustomerCvv>
  <CustomerHolderName>Josh</CustomerHolderName>
  <CustomerAllowSWrefunds>1</CustomerAllowSWrefunds>
  <CustomerThreeD>
    <Enrolled>fkf></Enrolled>
    <Paresstatus>Y</Paresstatus>
    <Eci>05</Eci>
    <Xid>DYYVcrwnujRMnHDy1wlP1Ggz8w0=</Xid>
    <Cavv>mHyn+7YFi1EUAREAAAAvNUe6Hv8=</Cavv>
    <Signature>_</Signature>
    <Veres>AUTHENTICATION_SUCCESSFUL</Veres>
    <Pares>eAHNV1mzokgW/is</Pares>
  </CustomerThreeD>
</API3G>

Note: Sample values are illustrative. Provide only valid 3DS fields returned by your ACS/Directory Server.

Response

Example Success Response (XML)

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Result>000</Result>
  <ResultExplanation>Card verified</ResultExplanation>
  <customerToken>9C6BB1D2-B2DE-46B3-8AD7-409168936DDA</customerToken>
  <subscriptionToken>977E056D-3AD2-4DC5-AE8A-3B8CFF00741A</subscriptionToken>
  <cardType>Visa</cardType>
  <cardLast4>2222</cardLast4>
</API3G>

Field Reference

Result Codes (from spec)

Common v6 codes you may also encounter

Typical Usage Flow

sequenceDiagram
  participant M as Merchant
  participant D as DPO API

  M->>D: addCard (PAN, Expiry, CVV, Holder, customerToken)
  alt 3DS data provided
    M->>D: addCard + CustomerThreeD (ECI, CAVV, XID, etc.)
    D-->>M: Result 000 + tokens (subscriptionToken) + cardType/last4
  else no 3DS data
    D-->>M: Result + tokens (may be unverified per config)
  end
  M->>M: Store tokens (not PAN/CVV)<br/>Use subscriptionToken for future charges

Notes & Best Practices

• PCI-DSS: Do not log or store CustomerCreditCard or CustomerCvv. Persist only customerToken and subscriptionToken.
• Expiry format: Prefer MMYY (e.g., 1225). If your integration previously used MM/YY, standardize to MMYY for v6 unless instructed otherwise.
• 3DS: When available, pass CustomerThreeD to add a verified card on enrollment. Validate ECI/CAVV/XID presence for successful 3DS results.
• Refunds via Super Wallet: Set CustomerAllowSWrefunds=1 when you want the card verified via the current company account to allow SW refunds.
• Idempotency: If you may retry, use your own de-duplication key at the application layer to avoid unintended duplicates.
• Security: Always use TLS, mask PAN in UIs, and restrict access to tokens.