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://secure1.sandbox.directpay.online/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>
</Transaction>

Variables to be sent at Transaction level:

Parameter	Data type	Description
Request	Text	createToken	Mandatory
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	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
DeclinedURL	Text	URL to return the client if payment is declined. 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	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

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>
</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
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

Allocations level (Optional):

Allocations must be wrapped in <Allocations> tag and each allocation in <Allocation> tag. The limit for an allocation must be the 95% 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

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>
</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>

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
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
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>