Verify Token / Transaction Status Lookup

Verify a transaction by transaction token or company reference, and retrieve the latest payment details from DPO.

You can initiate verifyToken at any time. You must verify the token when the customer returns to your application. If you do not verify the token within 30 minutes after the payment is completed, DPO sends an alert email to the provider indicating that no verification process occurred.

Version endpoints

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

Send requests using XML in the request body.

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

Request parameters

Parameter	Data type	Description	Required
`CompanyToken`	Token	Token you received from 3G to operate this API.	Mandatory
`Request`	Text	Must be `verifyToken`.	Mandatory
`TransactionToken`	Token	Transaction token received from the redirected URL.	Mandatory, or optional if `CompanyRef` is sent.
`CompanyRef`	Text	Company reference number.	Mandatory, or optional if `TransactionToken` is sent.
`VerifyTransaction`	Boolean (1/0)	By default, the system verifies the transaction and marks it as `website verified` in 3G systems. Set this to `0` if you only want to confirm that the transaction was made, process the details, and then send `verifyToken` again with this value set to `1` after you successfully process the client. Default: `1` (true).	Optional
`ACCref`	Text	Internal accounting reference number.	Optional
`customerPhone`	Text	Customer phone number. Can be updated.	Optional. Mandatory if `customerPhonePrefix` is sent.
`customerPhonePrefix`	Number	Customer phone prefix without `+`.	Optional. Mandatory if `customerPhone` is sent.
`customerEmail`	Text	Customer email address. Can be updated.	Optional

Parameter	Data type	Description	Required
`Request`	Text	Must be `verifyToken`.	Mandatory
`CompanyToken`	Text (Token - UUID)	Token you received from 3G to operate this API.	Mandatory
`TransactionToken`	Text (Token - UUID)	Transaction token received from the redirected URL.	Mandatory, or optional if `CompanyRef` is sent.
`CompanyRef`	Text	Company reference number.	Mandatory, or optional if `TransactionToken` is sent.
`VerifyTransaction`	Boolean (1/0)	By default, the system verifies the transaction and marks it as `website verified` in 3G systems. Set this to `0` if you only want to confirm that the transaction was made, process the details, and then send `verifyToken` again with this value set to `1` after you successfully process the client. Default: `1`.	Optional
`ACCref`	Text	Internal accounting reference number.	Optional
`customerPhone`	Text	Customer phone number. Can be updated.	Optional. Mandatory if `customerPhonePrefix` is sent.
`customerPhonePrefix`	Number	Customer phone prefix without `+`.	Optional. Mandatory if `customerPhone` is sent.
`customerEmail`	Text	Customer email address. Can be updated.	Optional

API v6 request example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <CompanyToken>57466282-EBD7-4ED5-B699-8659330A6996</CompanyToken>
  <Request>verifyToken</Request>
  <TransactionToken>72983CAC-5DB1-4C7F-BD88-352066B71592</TransactionToken>
</API3G>

API v7 request format

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Request>verifyToken</Request>
  <CompanyToken>{CompanyToken}</CompanyToken>
  <TransactionToken>{transToken}</TransactionToken>
  <CompanyRef>{CompanyRef}</CompanyRef>
  <VerifyTransaction>{VerifyTransaction}</VerifyTransaction>
  <ACCref>{ACCref}</ACCref>
  <customerPhone>{customerPhone}</customerPhone>
  <customerPhonePrefix>{customerPhonePrefix}</customerPhonePrefix>
  <customerEmail>{customerEmail}</customerEmail>
</API3G>

API v7 request example

<API3G>
  <CompanyToken>90EC1DA4-A7C5-432C-930C-098715D3130E</CompanyToken>
  <Request>verifyToken</Request>
  <TransactionToken>6253BFCA-848B-4884-A5FA-68E425643BD1</TransactionToken>
</API3G>

API v6 response fields

The server responds to the verifyToken request with the following fields.

Parameter	Data type	Description
`Result`	3-digit code	Code sent with the result of the request.
`ResultExplanation`	Text	Free text result explanation.
`CustomerName`	Text	Customer name as entered on the 3GDirectpay payment page. Sent if the transaction was paid or failed.
`CustomerCredit`	Text	Last 4 digits of the credit card. Sent if the transaction was paid or failed.
`CustomerCreditType`	Text	Credit card type.
`TransactionApproval`	Text	Transaction approval number. Sent if the transaction was paid or failed.
`TransactionCurrency`	Text	Final payment currency. The customer can convert the payment. Sent if the transaction was paid or failed.
`TransactionAmount`	Money	Paid amount. Sent if the transaction was paid or failed.
`FraudAlert`	3-digit code	Fraud code according to the fraud codes table.
`FraudExplnation`	Text	Free text fraud analysis.
`TransactionNetAmount`	Amount	Net transaction amount.
`TransactionSettlementDate`	Date	Transaction settlement date.
`TransactionRollingReserveAmount`	Amount	Transaction rolling reserve amount.
`TransactionRollingReserveDate`	Date	Rolling reserve release date.
`CustomerPhone`	Text	Customer phone number.
`CustomerCountry`	Text	Customer country.
`CustomerAddress`	Text	Customer address.
`CustomerCity`	Text	Customer city.
`CustomerZip`	Text	Customer ZIP code.
`MobilePaymentRequest`	Text	Mobile payment request status.
`AccRef`	Text	Internal accounting reference number.

API v6 response example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Result>000</Result>
  <ResultExplanation>Transaction Paid</ResultExplanation>
  <CustomerName>Cons Connie </CustomerName>
  <CustomerCredit></CustomerCredit>
  <CustomerCreditType>Mobile</CustomerCreditType>
  <TransactionApproval>RHP2ZIGD5U</TransactionApproval>
  <TransactionCurrency>KES</TransactionCurrency>
  <TransactionAmount>1.00</TransactionAmount>
  <FraudAlert>001</FraudAlert>
  <FraudExplnation>Low Risk (Not checked)</FraudExplnation>
  <TransactionNetAmount>0.99</TransactionNetAmount>
  <TransactionSettlementDate>2023/09/04</TransactionSettlementDate>
  <TransactionRollingReserveAmount>0.00</TransactionRollingReserveAmount>
  <TransactionRollingReserveDate>2023/08/25</TransactionRollingReserveDate>
  <CustomerPhone>706527126</CustomerPhone>
  <CustomerCountry>Kenya</CustomerCountry>
  <CustomerAddress></CustomerAddress>
  <CustomerCity>Mbsa</CustomerCity>
  <CustomerZip></CustomerZip>
  <MobilePaymentRequest>Not sent</MobilePaymentRequest>
  <AccRef></AccRef>
  <TransactionFinalCurrency>KES</TransactionFinalCurrency>
  <TransactionFinalAmount>1.00</TransactionFinalAmount>
</API3G>

API v7 response examples

Success response

<?xml version="1.0" encoding="UTF-8"?>
<API3G>
  <Result>000</Result>
  <ResultExplanation>Transaction Paid</ResultExplanation>
  <TransactionCreatedDate>2024/01/03 09:11:44</TransactionCreatedDate>
  <TransactionSettlementDate>2024/01/17</TransactionSettlementDate>
  <TransactionRollingReserveAmount>0.00</TransactionRollingReserveAmount>
  <TransactionRollingReserveDate>2024/01/03</TransactionRollingReserveDate>
  <TransactionExpiryDate>2024/01/04 00:11:44</TransactionExpiryDate>
  <TransactionPaymentDate>2024/01/03 09:14:52</TransactionPaymentDate>
  <CustomerName>vv vv</CustomerName>
  <CustomerPhone>203888888888</CustomerPhone>
  <CustomerCountry>Israel</CustomerCountry>
  <CustomerAddress>6666</CustomerAddress>
  <CustomerCity>ee</CustomerCity>
  <CustomerZip>e</CustomerZip>
  <CustomerEmail>[email protected]</CustomerEmail>
  <PaymentType></PaymentType>
  <CardType>MASC</CardType>
  <ApprovalNumber>400309113213</ApprovalNumber>
  <CardLastFour>0008</CardLastFour>
  <CardFirstSix>51234500</CardFirstSix>
  <TransactionAmount>44.7947</TransactionAmount>
  <TransactionCurrency>AED</TransactionCurrency>
  <PartPaymentRef>0</PartPaymentRef>
  <AllocationAmount>1.3047</AllocationAmount>
  <AllocationCode>demo1</AllocationCode>
  <CompanyRef>49FYTA9009</CompanyRef>
  <CompanyAccRef>OTC9L5_992404700</CompanyAccRef>
  <TransactionRef>R4981192</TransactionRef>
  <ServiceDescription>Refill account</ServiceDescription>
  <ServiceDate></ServiceDate>
  <TransactionFraudAlert>001</TransactionFraudAlert>
  <TransactionFraudExplanation>Low Risk (Not checked)</TransactionFraudExplanation>
  <TransactionFinalAmount>44.7947</TransactionFinalAmount>
  <TransactionFinalCurrency>AED</TransactionFinalCurrency>
</API3G>

Error response

<?xml version="1.0" encoding="UTF-8"?>
<API3G>
  <Code>950</Code>
  <Explanation>Request missing transaction level mandatory fields - fieldName</Explanation>
</API3G>

API v6 response codes

Code	Explanation
`000`	Transaction paid.
`001`	Authorized.
`002`	Transaction overpaid or underpaid.
`003`	Pending bank.
`005`	Queued authorization.
`007`	Pending split payment. Part-payment transactions are not fully paid.
`801`	Request missing company token.
`802`	Company token does not exist.
`803`	No request or error in request type name.
`804`	Error in XML.
`900`	Transaction not paid yet.
`901`	Transaction declined.
`902`	Data mismatch in one of the fields: field explanation.
`903`	The transaction passed the payment time limit.
`904`	Transaction cancelled.
`950`	Request missing transaction-level mandatory fields: field explanation.

API v7 response codes

Code	Explanation
`000`	Transaction paid.
`001`	Authorized.
`002`	Transaction overpaid or underpaid.
`007`	Pending split payment. Part-payment transactions are not fully paid.
`801`	Request missing company token.
`802`	Company token does not exist.
`803`	No request or error in request type name.
`804`	Error in XML.
`900`	Transaction not paid yet.
`901`	Transaction declined.
`902`	Data mismatch in one of the fields: field explanation.
`903`	The transaction passed the payment time limit.
`904`	Transaction cancelled.
`950`	Request missing transaction-level mandatory fields: field explanation.

Fraud alert codes

Code	Explanation
`000`	Genuine transaction.
`001`	Low risk. Not checked.
`002`	Suspected fraud alert.
`003`	Fraud alert cleared. Merchant marked as clear.
`004`	Suspect fraud alert.
`005`	Fraud alert cleared. Low risk checked or genuine transaction.
`006`	Black. Fraudulent transaction.

Code	Explanation
`000`	Genuine transaction.
`002`	Suspected fraud alert.
`003`	Fraud alert cleared. Merchant marked as clear.
`004`	Suspect fraud alert.
`005`	Fraud alert cleared. Genuine transaction.
`006`	Black. Fraudulent transaction.