Get Subscription Token

This is useful when you need to re-establish a customer session or verify tokens for returning users.

Common use: recover a customer’s saved payment tokens using their Email or Phone number.

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 `getSubscriptionToken`
`CompanyToken`	string	Yes	Token provided by DPO to authorize API operations
`SearchCriteria`	integer	Yes	Determines how to identify the customer:`1` = by Email `2` = by Phone number
`SearchCriteriaValue`	string	Yes	Email address or phone number (depending on chosen `SearchCriteria`)

Example Request (XML)

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <CompanyToken>68B90B5E-25F6-4146-8AB1-C7A3A0CAABB3</CompanyToken>
  <Request>getSubscriptionToken</Request>
  <SearchCriteria>1</SearchCriteria>
  <SearchCriteriaValue>[email protected]</SearchCriteriaValue>
</API3G>

Tip:
Use SearchCriteria=1 (email) for most integrations. Use 2 (phone number) only if the customer was registered primarily by mobile.

Response

Example Success Response (XML)

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Result>000</Result>
  <ResultExplanation>Success</ResultExplanation>
  <SubscriptionToken>37CB51E6-EF18-4E27-A80E-8448B7B0342A</SubscriptionToken>
  <CustomerToken>C1E0F067-DFB9-4CA0-8CC2-FCC6018243B3</CustomerToken>
</API3G>

Field Reference

Field	Type	Description
`Result`	integer	Response code
`ResultExplanation`	string	Description of the response
`SubscriptionToken`	string	The customer’s subscription token (payment token)
`CustomerToken`	string	The customer’s unique Super Wallet token

Result Codes

Code	ResultExplanation	Meaning / Action
`000`	Success	Tokens retrieved successfully
`803`	Invalid or missing `Request` name	Ensure `getSubscriptionToken`
`888`	System error	Retry or contact support
`902`	Data mismatch	Verify `SearchCriteria` and `SearchCriteriaValue`
`950`	Missing mandatory fields	Check XML tags
`991`	Encrypted string empty	Invalid or corrupted request
`999`	Customer not found	Ensure customer exists or was created correctly

Typical Usage Flow

sequenceDiagram
  participant M as Merchant
  participant D as DPO API

  M->>D: getSubscriptionToken (CompanyToken, SearchCriteria, SearchCriteriaValue)
  D-->>M: Result 000 + SubscriptionToken + CustomerToken
  M->>M: Store or refresh local tokens for recurring charges
  Note over M,D: Use these tokens for future customerChargeToken or addCard calls

Notes & Best Practices

Use cases: Retrieve existing customer tokens to enable auto-payments or re-link wallets.
Search behavior:
• When using SearchCriteria=1, provide the customer’s email address.
• When using SearchCriteria=2, provide the customer’s phone number (including country code).
Security: Tokens uniquely identify wallet accounts; handle them with care.
Verification: Always validate Result=000 before using returned tokens.
Fallback: If 999 (Customer not found), consider prompting the user to register via createAccount.