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

Field	Type	Req	Description
`Request`	string	Yes	Must be `addCard`
`CompanyToken`	string	Yes	Token provided by DPO to authorise API operations
`customerToken`	string	Yes	Customer token (from `createAccount`)
`CustomerCreditCard`	string	Yes	Credit card number (PAN)
`CustomerExpiry`	string	Yes	Card expiry. Format: `MMYY` (e.g., `1225`). Some integrations accept `MM/YY`, but `MMYY` is recommended for v6
`CustomerCvv`	string	Yes	Card CVV/CVC
`CustomerHolderName`	string	Yes	Cardholder name
`CustomerAllowSWrefunds`	integer	No	Verify card via current company account (default: `0`)
`CustomerThreeD`	object	No	3-D Secure verification payload (see fields below)

`CustomerThreeD` object

Field	Type	Description
`Enrolled`	string	Enrollment status from directory server
`Paresstatus`	string	PARes status (e.g., `Y`, `N`)
`Eci`	string	Electronic Commerce Indicator (e.g., `05`, `06`)
`Xid`	string	Transaction identifier
`Cavv`	string	CAVV/AVV value
`Signature`	string	3DS signature/result
`Veres`	string	Verification result (e.g., `AUTHENTICATION_SUCCESSFUL`)
`Pares`	string	PARes content (base64/encoded)

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

Field	Type	Description
`Result`	integer	Result code
`ResultExplanation`	string	Human-readable explanation
`customerToken`	string	Customer token (use for future wallet operations)
`subscriptionToken`	string	Tokenized card reference for payments/subscriptions
`cardType`	string	Card brand (e.g., `Visa`, `Mastercard`)
`cardLast4`	string	Last 4 digits of the card

Result Codes (from spec)

Code	Explanation
`000`	Successful – Card verified
`999`	Dynamic error (based on XML sent)
`950`	Dynamic error (based on XML sent)

Common v6 codes you may also encounter

Code	Meaning	Action
`801`	Missing `CompanyToken`	Provide a valid token
`803`	Bad/missing `Request` name	Ensure `addCard`
`804`	XML error	Check tag names/encoding
`902`	Data mismatch	Verify `customerToken` and 3DS fields

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.