createToken(V6)

Description

The createToken will create a transaction in the Direct Pay Online system, it is constructed from 5 levels:

Request

Transaction level – Mandatory - Contains all the basic transaction information
Services level – Mandatory - Contains all the information regarding the services sold in the transaction – must contain at-least one service
Allocations level – Contains all the information regarding the allocation of money received from transaction to be paid to other providers in Direct Pay Online system. If this level is not sent, the system will allocate all the money from this transaction to the provider
Additional level – Contains an option to block specific payment options in the transaction (for example, on an application which needs fast payment, block off Direct Pay Online bank payment)
Travelers level – Contains information regarding travelers (passengers / guests) which will a process in Direct Pay Online system to verify that one of the payers name matches the name of one of the travelers

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

Response

The method will respond with the result of your request.

Variables to send:

Parameter	Data type	Description
CompanyToken	Token	Token you got from 3G to operate this API	Mandatory
Request	Text	createToken	Mandatory

Transaction level (Mandatory):

Transaction must be wrapped in <Transaction> tag.

Transaction example

<Transaction>
	<PaymentAmount>300</PaymentAmount>
	<PaymentCurrency>tzs</PaymentCurrency>
	<CompanyRefUnique>1</CompanyRefUnique>
	<CompanyRef>YourRef12345</CompanyRef>
	<PTL>56</PTL>
	<customerFirstName>John</customerFirstName>
	<customerLastName>Doe</customerLastName>
	<customerEmail>test@directpayonline.com</customerEmail>
	<DefaultPayment>MO</DefaultPayment>
	<DefaultPaymentCountry>Tanzania</DefaultPaymentCountry>
	<DefaultPaymentMNO>Tigo</DefaultPaymentMNO>
	<TransactionSource>Mobile</TransactionSource>
	<MetaData>
    	<![CDATA[
    	{
    		"key": "Value",
    		.......
    	}
    	]]>
	</MetaData>
</Transaction>

Variables to be sent at Transaction level:

Parameter	Data type	Description
PaymentAmount	Money	Total amount in the selected currency. No more than 2 digits after the comma	Mandatory
PaymentCurrency	Text	From table of options as accepted from DPO	Mandatory
CompanyRef	Text	Company reference number, i.e also referred to as Booking ref	Optional
RedirectURL	Text	URL to redirect the customer after the payment. The customer will be redirected to this URL with the below variables in GET method. You can send your link with additional variables, the system will recognize it and the additional variables will be sent out with “&” instead of “?” in the beginning. Variables: TransID - Transaction ref. CCDapproval - Approval number PnrID - Customer ref TransactionToken - Transaction ref. (repeated) CompanyRef - Customer ref. (repeated)	Optional
BackURL	Text	URL to let the customer go back from the payment page. The customer will be redirected to this URL with "TransactionToken" and "CompanyRef" variables in GET method. You can send your link with additional variables, the system will recognize it and the additional variables will be sent our with "&" instead of "?" in the beginning	Optional
CompanyRefUnique	Boolean	Tells the system to verify if the company reference number (transaction ID given by the provider) given is already in the system and paid, if so, returns error to API result.This is to prevent double payments	Optional. Default: False
PTL	Number	Number of hours to payment time limit	Optional. Default: 96 hours
PTLtype	Text	Define if “PTL” tag is hours or minutes. options: “hours” or “minutes”	Optional. Default: hours
TransactionChargeType	Number	Type of transaction: 1 for Charge - immediate charge 2 for Authorize-Manual - for an authorization process and then manual charge using “chargeToken” 3 for Authorize-Auto - for authorization process and then automatically charge on chosen date	Optional. Default: 1 (Charge)
TransactionAutoChargeDate	DateTime	Date and time of automatic charge of transaction, if authorized by that date. Formats: YYYY/MM/DD HH:MM(:SS), YYYY/MM/DD, YYYY-MM-DD HH:MM(:SS), YYYY-MM-DD	Optional/Mandatory if TransactionChargeType=”Authorize-Auto”
customerEmail	Text	E-mail of the customer to send the link	Optional
customerFirstName	Text	Customer name	Optional
customerLastName	Text	Customer last name	Optional
customerAddress	Text	Customer address	Optional
customerCity	Text	Customer city	Optional
customerCountry	ISO code	Customer country ISO 2 letter code http://en.wikipedia.org/wiki/ISO_3166-1	Optional
customerDialCode	ISO code	Customer country ISO 2 letter code	Optional
customerPhone	Number	Customer Phone number	Optional
customerZip	Text	Customer zip code	Optional
DemandPaymentbyTraveler	Boolean (1/0)	If marked as 1, the system will require one of the travelers which are included in the travelers tag to be the payer.	Optional
EmailTransaction	Boolean (1/0)	If marked as 1, the system will send the customer an e-mail about the transaction with a link to pay	Optional
CompanyAccRef	Text	Internal accounting reference number	Optional
userToken	Token	To define who created the transaction	Optional
DefaultPayment	Text	The code of the default payment option (the one to be displayed first in the payment page), options: CC – Credit card MO – Mobile PP – PayPal BT – Bank transfer XP – xPay	Optional
DefaultPaymentCountry	Text	Should be used only for Mobile default payment. Name of the default country for the payment option (DefaultPayment will work without this option too) Ex.: <DefaultPaymentCountry>kenya</DefaultPaymentCountry>	Optional
DefaultPaymentMNO	Text	Should be used only for Mobile default payment. Name of the default MNO (mobile network operator) for the payment option (DefaultPayment will work without this option too) Ex.: <DefaultPaymentMNO>mpesa</DefaultPaymentMNO>	Optional
TransactionToPrep	Boolean (1/0)	Will mark the transaction as Marketplace Prep	Optional
AllowRecurrent	Boolean (1/0)	Will allow payment via recurrent	Optional
FraudTimeLimit	Number	Set fraud time limit in minutes (from current date)	Optional
Voidable	Boolean (1/0)	If this tag sent, transaction will be checked in scoring process, if 0 and scoring above high risk/very high risk then will be blocked, if 1 then will go to a check by DPO support team	Optional
ChargeType	Text		Optional
TRANSmarketplace	Number	If this tag is sent, allocation amount will be update based on the API_GetCCTclientprecentage stored proc	Optional
TRANSblockCountries	Boolean (1/0)	transaction block countries	Optional
MetaData	Text(2000)	Some custom data, that need store for specify transaction (Max allowed 2000 symbols)	Optional
SMSTransaction	Boolean (1/0)	sms transaction	Optional
TransactionType	Text	If set, update the transaction status id based on it	Optional
DeviceId	Text	In use if transaction type is duma directpay	Optional
DeviceCountry	Text	In use if transaction type is duma directpay	Optional
TransactionSource	Text	This field will indicate the source of the transaction. If none provided the default source will be applied (default = API). Available sources (more can be added if needed): Computer Mobile API Website Catalogue Realtime Settlement DPO Card DPO Store Lite Portal Marketplace Pay My Bills Shopify Wordpress Magento Whcms Wix Ecwid Android SDK IOS SDK DPO Pay mobile Android DPO Pay mobile IOS	Optional

Service level (Mandatory):

Services must be wrapped in <Services> tag and each services must be wrapped in <Service> tag, there is no limit in individual services to be sent in services tag.

Services example

<Services>
  <Service>
    <ServiceType>33</ServiceType>
    <ServiceDescription>Service number 1</ServiceDescription>
    <ServiceDate>2018/01/20 19:00</ServiceDate>
  </Service>
    <Service>
    	<ServiceType>39</ServiceType>
    	<ServiceDescription>Service number 2</ServiceDescription>
    	<ServiceDate>2018/01/20 19:00</ServiceDate>
		<ServiceFrom>JFK</ServiceFrom>
    	<ServiceTo>CDG</ServiceTo>
  </Service>
  <Service>
    	<ServiceTypeName>Commission</ServiceTypeName>
    	<ServiceDescription>Service number 2</ServiceDescription>
    	<ServiceDate>2018/01/20 19:00</ServiceDate>
		<ServiceFrom>JFK</ServiceFrom>
    	<ServiceTo>CDG</ServiceTo>
  </Service>
</Services>

Variables to be sent at Services level:

Parameter	Data type	Description
ServiceDescription	Text	The description of the payment made	Mandatory
ServiceType	Number	Service type number according to the options accepted from DPO	Mandatory-Optional (Need send ServiceType or ServiceTypeName)
ServiceTypeName	Text	Service type name according to the options accepted from DPO	Mandatory-Optional (Need send ServiceType or ServiceTypeName)
ServiceDate	DateTime	Service date of the booked service Format: YYYY/MM/DD HH:MM	Mandatory
ServiceFrom	Iata	3 letters departure airport code	Optional
ServiceTo	Iata	3 letters destination airport code	Optional
ServiceRef	Text	Service Reference	Optional

Allocations level (Optional):

Allocations must be wrapped in <Allocations> tag and each allocation in <Allocation> tag. The limit for an allocation must be the 89% of the total of the transaction. Some fields are mandatory for each allocation sent.

Allocations level

<Allocations>
  <Allocation>
    <AllocationCode>demo1</AllocationCode>
    <AllocationAmount>130.00</AllocationAmount>
    <AllocationServiceType>39</AllocationServiceType>
  </Allocation>
  <Allocation>
    <AllocationCode>demo2</AllocationCode>
    <AllocationAmount>40.00</AllocationAmount>
    <AllocationServiceType>33</AllocationServiceType>
	<AllocationServiceDescription>Description of the allocation</AllocationServiceDescription>
  </Allocation>
</Allocations>

Variables to be sent at Allocation level:

Parameter	Data type	Description
AllocationCode	Text	The code of the other provider to allocate money to.	Mandatory
AllocationAmount	Money	The allocated amount	Mandatory
AllocationServiceType	Number	Allocation service type from list of services	Mandatory
AllocationServiceDescription	Text	Free text	Optional
AllocationInvoice	Text	Invoice of the allocation	Optional
AllocationPnr	Text	Pnr of the allocation	Optional
AllocationBlock	Boolean(1/0)	Insert into API_CreateToken_additional_insert	Optional

Additional level (Optional):

Additional must be wrapped in <Additional> tag and each additional information inside of it must be wrapped in <BlockPayment> tag.
Variables to be sent at Additional level:

Parameter	Data type	Description
BlockPayment	Text	The code of the payment options to be blocked, options: CC – Credit card MO – Mobile PP – PayPal BT – Bank transfer XP – xPay	Optional

Travelers level (Optional):

Travelers must be wrapped in <Travelers> tag and each traveler in <Traveler> tag. Some fields are mandatory for each traveler sent.

Travelers example

<Travelers>
  <Traveler>
    <TravelerFirstName>John</TravelerFirstName>
 	<TravelerLastName>Doe</TravelerLastName>
    <TravelerPhone>12312312</TravelerPhone>
    <TravelerPhonePrefix>254</TravelerPhonePrefix>
  </Traveler>
  <Traveler>
    <TravelerFirstName>Rose</TravelerFirstName>
    <TravelerLastName>Doe</TravelerLastName>
  </Traveler>
</Travelers>

Variables to be sent at Traveler level:

Parameter	Data type	Description
TravelerFirstName	Text	First name	Mandatory
TravelerLastName	Text	Last name	Mandatory
TravelerPhone	Text	Phone number	Optional
TravelerPhonePrefix	Numeric	Phone number prefix (without +)	Optional

Request example:

Simple one service transaction (In this type of transaction, the customer will be redirected to the “Redirect URL” once paid):

request example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
<CompanyToken>57466282-EBD7-4ED5-B699-8659330A6996</CompanyToken>
<Request>createToken</Request>
<Transaction>
<PaymentAmount>450.00</PaymentAmount>
<PaymentCurrency>USD</PaymentCurrency>
<CompanyRef>49FKEOA</CompanyRef>
<RedirectURL>http://www.domain.com/payurl.php</RedirectURL>
<BackURL>http://www.domain.com/backurl.php </BackURL>
<CompanyRefUnique>0</CompanyRefUnique>
<PTL>5</PTL>
</Transaction>
<Services>
  <Service>
    <ServiceType>45</ServiceType>
    <ServiceDescription>Flight from Nairobi to Diani</ServiceDescription>
    <ServiceDate>2013/12/20 19:00</ServiceDate>
  </Service>
</Services>
</API3G>

Two Services with allocation and travelers names and transaction based on e-mail alert (you can see in this example that there is no definition of the Redirect or Back URL, as this transaction will be completed in DPO website):

request example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
<CompanyToken>57466282-EBD7-4ED5-B699-8659330A6996</CompanyToken>
<Request>createToken</Request>
<Transaction>
<PaymentAmount>950.00</PaymentAmount>
<PaymentCurrency>USD</PaymentCurrency>
<CompanyRef>49FKEOA</CompanyRef>
<RedirectURL></RedirectURL>
<BackURL></BackURL>
<CompanyRefUnique>0</CompanyRefUnique>
<PTL>5</PTL>
<customerEmail>test@directpayonline.com</customerEmail>
<FraudTimeLimit>60</FraudTimeLimit>
</Transaction>
<Services>
  <Service>
    <ServiceType>45</ServiceType>
    <ServiceDescription>Flight from Nairobi to Diani</ServiceDescription>
    <ServiceDate>2013/12/20 19:00</ServiceDate>
  </Service>
  <Service>
    <ServiceType>45</ServiceType>
    <ServiceDescription>Flight from Diani to Wilson</ServiceDescription>
    <ServiceDate>2013/12/25 09:00</ServiceDate>
  </Service>
</Services>
<Allocations>
  <Allocation>
    <AllocationCode>demo1</AllocationCode>
    <AllocationAmount>850</AllocationAmount>
    <AllocationServiceType>45</AllocationServiceType>
  </Allocation>
</Allocations>
<Travelers>
  <Traveler>
    <TravelerFirstName>John</TravelerFirstName>
    <TravelerLastName>Doe</TravelerLastName>
    <TravelerPhone>456887014</TravelerPhone>
    <TravelerPhonePrefix>254</TravelerPhonePrefix>
  </Traveler>
  <Traveler>
    <TravelerFirstName>Rose</TravelerFirstName>
    <TravelerLastName>Doe</TravelerLastName>
  </Traveler>
</Travelers>
</API3G>

Simple one service transaction with payment option block:

request example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
<CompanyToken>57466282-EBD7-4ED5-B699-8659330A6996</CompanyToken>
<Request>createToken</Request>
<Transaction>
<PaymentAmount>950.00</PaymentAmount >
<PaymentCurrency>USD</PaymentCurrency>
<CompanyRef>49FKEOA</CompanyRef>
<RedirectURL>http://www.domain.com/payurl.php</RedirectURL>
<BackURL>http://www.domain.com/backurl.php </BackURL>
<CompanyRefUnique>0</CompanyRefUnique>
<PTL>5</PTL>
</Transaction>
<Services>
  <Service>
    <ServiceType>45</ServiceType>
    <ServiceDescription>Flight from Nairobi to Diani</ServiceDescription>
    <ServiceDate>2013/12/20 19:00</ServiceDate>
  </Service>
</Services>
<Additional>
  <BlockPayment>BT</BlockPayment>
  <BlockPayment>PP</BlockPayment>
</Additional>
</API3G>

AdditionalAirlineFields Transaction

Parameter	Data type	Description	Is Mandatory
AdditionalAirlineFields	XML (String)	Additional transaction props	Optional

Additional Airline Fields Prams:

Parameter

Data type

Description

Is Mandatory

TicketType

DocumentType

DateIssued

IATACarrierCode

IATATravelAgencyNbr

TicketCarrierName

TicketIssuerCityName

PassengerCount

ConjTicketIndicator

ElecTicketIndicator

TicketNumber

FlightLegDetails

Travelers

Text

DateTime

Text

Numeric

Text

XML (String)

Ticket Type

Document Type

Date Issued

IATA Carrier Code

IATA Travel Agency Number

Ticket Carrier Name

Ticket Issuer City Name

Number of Passengers

Conjunction Ticket Indicator

Electronic Ticket Indicator

Exchanged/Original Ticket No or PNR

Flight Leg Details

Traveler Details

Optional

Mandatory

Optional

Mandatory

Optional

Traveler Details Prams:

Parameter	Data type	Description	Is Mandatory
TravelerFirstName	Text	First name	Mandatory
TravelerLastName	Text	Last name	Mandatory
TravelerPhone	Text	Phone number	Optional
TravelerPhonePrefix	Numeric	Phone number prefix (without +)	Optional
TravelerDateOfBirth	DateTime	Traveler Date Of Birth	Optional
TravelerCountryCode	Text	Traveler Country Code	Optional

Flight Leg Details Prams:

Parameter	Data type	Description	Is Mandatory
FlightDescription	Text	The description of the payment made	Mandatory
FlightType	Number	Service type number according to the options accepted from DPO	Mandatory
FightDate	DateTime	Service date of the booked service Format: YYYY/MM/DD HH:MM	Mandatory
FlightFrom	Text	3 letters departure airport code	Mandatory
FightTo	Text	3 letters destination airport code	Mandatory
FlightRef	Text	Service Reference	Optional
CarrierCode	Text	IATA carrier code	Mandatory
ServiceClass	Text	Service Class	Mandatory
FlightNumber	Text	Flight Number	Mandatory
FareBasisCode	Text	Fare Basis Code	Mandatory
StopOverCode	Text	Stop Over Code	Mandatory

Additional Airlines Fields request example:

<API3G>
    <CompanyToken>90EC1DA4-A7C5-432C-930C-098715D3130E</CompanyToken>
    <Request>createToken</Request>
    <Transaction>
        <PaymentAmount>3.00</PaymentAmount>
        <PaymentCurrency>USD</PaymentCurrency>
        <CompanyRef>tr11212bnbv</CompanyRef>
        <CompanyRefUnique>0</CompanyRefUnique>
        <PTL>100000</PTL>
        <CompanyAccRef>www</CompanyAccRef>
        <PTLtype>minutes</PTLtype>
        <DefaultPayment>XP</DefaultPayment>
        <AllowRecurrent></AllowRecurrent>
        <customerFirstName>Dima</customerFirstName>
        <customerLastName>Kyselov</customerLastName>
        <customerCity>Nairobddi</customerCity>
        <customerCountry>KE</customerCountry>
        <CardHolderName>Dimdad Kyselovfd</CardHolderName>
        <customerEmail>devdimatest@gmail.com</customerEmail>
        <customerPhone>789564545</customerPhone>
        <DefaultPaymentCountry>Israel</DefaultPaymentCountry>
    </Transaction>
    <Services>
        <Service>
            <ServiceType>6456</ServiceType>
            <ServiceDescription>Airlines Service</ServiceDescription>
            <ServiceDate>2020/05/12</ServiceDate>
        </Service>
    </Services>
   <AdditionalAirlineFields>
        <TicketType>TICKET_PURCHASE</TicketType>
        <DocumentType>ADDITIONAL_COLLECTION</DocumentType>
        <DateIssued>2013/12/20 19:00</DateIssued>
        <IATACarrierCode>CP</IATACarrierCode>
        <IATATravelAgencyNbr>CPT</IATATravelAgencyNbr>
        <TicketCarrierName>KenyaAirways</TicketCarrierName>
        <TicketIssuerCityName >Nairobi</TicketIssuerCityName>
        <PassengerCount>3</PassengerCount>
        <ConjTicketIndicator>12233</ConjTicketIndicator>
        <ElecTicketIndicator>1A848F</ElecTicketIndicator>
        <ExchTicketIndicator>1A848E5</ExchTicketIndicator>
        <FlightLegDetails>
            <FlightLeg>
                <FlightDescription>Flight from TelAviv to CapeTown</FlightDescription>
                <FlightType>45</FlightType>
                <FlightDate>2013/12/20</FlightDate>
                <FlightFrom>TLV</FlightFrom>
                <FlightTo>CPT</FlightTo>
                <FlightRef>1234ABC</FlightRef>
                <CarrierCode>AI</CarrierCode>
                <ServiceClass>A</ServiceClass>
                <FlightNumber>101</FlightNumber>
                <FareBasisCode>SPRSVR</FareBasisCode>
                <StopOverCode>X</StopOverCode>
            </FlightLeg>
            <FlightLeg>
                <FlightDescription>Flight from CapeTown to TelAviv</FlightDescription>
                <FlightType>45</FlightType>
                <FlightDate>2013/12/21 16:00</FlightDate>
                <FlightFrom>CPT</FlightFrom>
                <FlightTo>TLV</FlightTo>
                <FlightRef>1234ABC</FlightRef>
                <CarrierCode>AI</CarrierCode>
                <ServiceClass>A</ServiceClass>
                <FlightNumber>101</FlightNumber>
                <FareBasisCode>SPRSVR</FareBasisCode>
                <StopOverCode>X</StopOverCode>
            </FlightLeg>
        </FlightLegDetails>
        <Travelers>
            <Traveler>
                <TravelerFirstName>John</TravelerFirstName>
                <TravelerLastName>Doe</TravelerLastName>
                <TravelerPhone>45640404</TravelerPhone>
                <TravelerPhonePrefix>123</TravelerPhonePrefix>
                <TravelerDateOfBirth>2001/12/21</TravelerDateOfBirth>
                <TravelerCountryCode>US</TravelerCountryCode>
            </Traveler>
            <Traveler>
                <TravelerFirstName>Rose</TravelerFirstName>
                <TravelerLastName>Doe</TravelerLastName>
            </Traveler>
        </Travelers>
    </AdditionalAirlineFields>
</API3G>

Response:

The server will respond for the createToken request according to the following results:

Parameter	Data type	Description
Result	3 digits code	A code will be sent with the result of the request
ResultExplanation	Text	Free text of the result
TransToken	Text	Token of the transaction (if created)
TransRef	Text	Ref of the transaction (if created)
notes	Text	Contain the request notes, if there are any.
AllocationID	Number	xPay ID in case there is an allocation in the trasaction
AllocationCode	Text	Receiver's Merchants code

NOTE; Payment page URL is: https://secure1.sandbox.directpay.online/payv2.php?ID={{TransToken}}

For example: https://secure1.sandbox.directpay.online/payv2.php?ID=72983CAC-5DB1-4C7F-BD88-352066B71592

Codes in the response:

Code	Explanation
000	Transaction created
801	Request missing company token
802	Company token does not exist
803	No request or error in Request type name
804	Error in XML
901	Error max string size allowed
902	Request missing transaction level mandatory fields - name of field
904	Currency not supported
905	The transaction amount has exceeded your allowed transaction limit, please contact: support@directpay.online
906	You exceeded your monthly transactions limit, please contact: support@directpay.online
922	Provider does not exist
923	Allocated money exceeds payment amount
930	Block payment code incorrect
940	CompanyREF already exists and paid
950	Request missing mandatory fields - name of field, Request fields empty
960	Tag has been sent multiple times

Success result example:

response example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Result>000</Result>
  <ResultExplanation>Transaction created</ResultExplanation>
  <TransToken>72983CAC-5DB1-4C7F-BD88-352066B71592</TransToken>
  <TransRef>1285DB12G</TransRef>
  <Allocations>
    <Allocation>
	  <AllocationID>95746</AllocationID>
	  <AllocationCode>f8g</AllocationCode>
	</Allocation>
  </Allocations>
</API3G>

Error result example:

response example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Result>920</Result>
  <ResultExplanation>Request missing mandatory allocation field AllocationCode</ResultExplanation>
</API3G>