Update Token

Modify existing transaction data with updateToken using DPO Pay API v6 or v7.

Update Token

Modify existing transaction data for a transaction token before the transaction reaches a status that no longer allows updates.

Use updateToken to update transaction details such as the amount, company reference, customer details, accounting reference, payment time limit, and airline details where supported.

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
`Request`	Text	Must be `updateToken`.	Mandatory
`CompanyToken`	Token	Token you received from 3G to operate this API.	Mandatory
`TransactionToken`	Token	Transaction token received from `createToken`.	Mandatory
`PaymentAmount`	Money	Transaction amount, up to 2 decimal places.	Optional
`CompanyRef`	Text	Company reference number.	Optional
`CustomerEmail`	Text	Customer email address used to send the payment link.	Optional
`CustomerFirstName`	Text	Customer first 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. See `http://en.wikipedia.org/wiki/ISO_3166-1`.	Optional
`CustomerDialCode`	ISO code	Customer country ISO 2-letter code. See `http://en.wikipedia.org/wiki/ISO_3166-1`.	Optional
`CustomerPhone`	Number	Customer phone number.	Optional
`CustomerZip`	Text	Customer ZIP code.	Optional
`CompanyAccRef`	Text	Internal accounting reference number.	Optional
`UserToken`	Token	Defines who created the transaction.	Optional

Parameter	Data type	Description	Required
`Request`	Text	Must be `updateToken`.	Mandatory
`CompanyToken`	Token	Token you received from 3G to operate this API.	Mandatory
`TransactionToken`	Token	Transaction token received from `createToken`.	Mandatory
`PaymentAmount`	Money	Transaction amount, up to 2 decimal places.	Optional
`PaymentMarkupMDRFee`	Money	Transaction markup MDR fee, up to 2 decimal places.	Optional
`CompanyRef`	Text	Company reference number.	Optional
`CustomerEmail`	Text	Customer email address used to send the payment link.	Optional
`CustomerFirstName`	Text	Customer first 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. See `http://en.wikipedia.org/wiki/ISO_3166-1`.	Optional
`CustomerDialCode`	ISO code	Customer country ISO 2-letter code. See `http://en.wikipedia.org/wiki/ISO_3166-1`.	Optional
`CustomerPhone`	Number	Customer phone number.	Optional
`CustomerZip`	Text	Customer ZIP code.	Optional
`CompanyAccRef`	Text	Internal accounting reference number.	Optional
`UserToken`	Token	Defines who created the transaction.	Optional
`AdditionalAirlineFields`	XML (String)	Additional airline transaction properties.	Optional
`PTL`	Number	Payment time limit value to add.	Optional
`PTLtype`	Text	Payment time limit type. Use `hour` or `minute`.	Optional

API v7 additional airline fields

Use AdditionalAirlineFields to update additional airline transaction properties.

AdditionalAirlineFields parameters

Parameter	Data type	Description	Required
`TicketType`	Text	Ticket type.	Optional
`DocumentType`	Text	Document type.	Optional
`DateIssued`	DateTime	Date issued.	Mandatory
`IATACarrierCode`	Text	IATA carrier code.	Mandatory
`IATATravelAgencyNbr`	Text	IATA travel agency number.	Optional
`TicketCarrierName`	Text	Ticket carrier name.	Optional
`TicketIssuerCityName`	Text	Ticket issuer city name.	Optional
`PassengerCount`	Numeric	Number of passengers.	Optional
`ConjTicketIndicator`	Text	Conjunction ticket indicator.	Optional
`ElecTicketIndicator`	Text	Electronic ticket indicator.	Optional
`TicketNumber`	Text	Exchanged or original ticket number, or PNR.	Mandatory
`FlightLegDetails`	XML (String)	Flight leg details.	Optional
`Travelers`	XML (String)	Traveler details.	Optional

Traveler parameters

Parameter	Data type	Description	Required
`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 parameters

Parameter	Data type	Description	Required
`FlightDescription`	Text	Description of the payment made.	Mandatory
`FlightType`	Number	Service type number according to the options accepted by DPO.	Mandatory
`FlightDate`	DateTime	Service date of the booked service. Format: `YYYY/MM/DD HH:MM`.	Mandatory
`FlightFrom`	Text	3-letter departure airport code.	Mandatory
`FlightTo`	Text	3-letter 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	Stopover code.	Mandatory

Statuses that allow `updateToken`

updateToken is available for transactions in the following statuses.

Status ID	Status name
`2`	Sent
`3`	Queued
`4`	Website Pending
`5`	Prep
`10`	Pending
`12`	Authorised

API v6 request example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <CompanyToken>68B90B5E-25F6-4146-8AB1-C7A3A0C41A7F</CompanyToken>
  <Request>updateToken</Request>
  <TransactionToken>EC9E975A-A7A2-4031-8972-BF123CDD9EDD</TransactionToken>
  <PaymentAmount>44</PaymentAmount>
  <CompanyRef>DPO1212</CompanyRef>
  <CustomerEmail>[email protected]</CustomerEmail>
  <CustomerFirstName>Steven dsa</CustomerFirstName>
  <CustomerLastName>Muallem</CustomerLastName>
  <CustomerAddress>Rose Avenue 6</CustomerAddress>
  <CustomerCity>Nairobi</CustomerCity>
  <CustomerCountry>KE</CustomerCountry>
  <CustomerDialCode>KE</CustomerDialCode>
  <CustomerPhone>4433332312</CustomerPhone>
  <CustomerZip>121212</CustomerZip>
  <CompanyAccRef>DPO3232</CompanyAccRef>
  <UserToken>3DBC6853-8352-4902-8370-C6B38C379999E</UserToken>
</API3G>

API v7 request example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <CompanyToken>68B90B5E-25F6-4146-8AB1-C7A3A0C41A7F</CompanyToken>
  <Request>updateToken</Request>
  <TransactionToken>EC9E975A-A7A2-4031-8972-BF123CDD9EDD</TransactionToken>
  <PaymentAmount>44</PaymentAmount>
  <PaymentMarkupMDRFee>2.93</PaymentMarkupMDRFee>
  <CompanyRef>DPO1212</CompanyRef>
  <CustomerEmail>[email protected]</CustomerEmail>
  <CustomerFirstName>Steven dsa</CustomerFirstName>
  <CustomerLastName>Muallem</CustomerLastName>
  <CustomerAddress>Rose Avenue 6</CustomerAddress>
  <CustomerCity>Nairobi</CustomerCity>
  <CustomerCountry>KE</CustomerCountry>
  <CustomerDialCode>KE</CustomerDialCode>
  <CustomerPhone>4433332312</CustomerPhone>
  <CustomerZip>121212</CustomerZip>
  <CompanyAccRef>DPO3232</CompanyAccRef>
  <UserToken>3DBC6853-8352-4902-8370-C6B38C379999E</UserToken>
  <AdditionalAirlineFields>
    <TicketType>TICKET_PURCHASE</TicketType>
    <DocumentType>ADDITIONAL_COLLECTION</DocumentType>
    <DateIssued>2013/12/20 20:00</DateIssued>
    <IATACarrierCode>CP</IATACarrierCode>
    <IATATravelAgencyNbr>56451855</IATATravelAgencyNbr>
    <TicketCarrierName>KenyaAirways</TicketCarrierName>
    <TicketIssuerCityName>Nairobi</TicketIssuerCityName>
    <PassengerCount>3</PassengerCount>
    <ConjTicketIndicator>12233</ConjTicketIndicator>
    <ElecTicketIndicator>1A848F</ElecTicketIndicator>
    <TicketNumber>45678945675</TicketNumber>
    <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>1045</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>1045</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 fields

Parameter	Data type	Description
`Result`	3-digit code	Code sent with the result of the request.
`ResultExplanation`	Text	Free text result explanation.

Parameter	Data type	Description
`Code`	3-digit code	Code sent with the result of the request.
`Explanation`	Text	Free text result explanation.
`ExtraInfo`	Text	Free text with additional error details.

Response codes

Code	Explanation
`000`	Token been updated.
`999`	Custom error message.
`804`	Error in XML.
`950`	Request missing transaction-level mandatory fields.

Code	Explanation
`000`	Token been updated.
`999`	Custom error message.
`804`	Error in XML.
`950`	Request missing transaction-level mandatory fields.
`955`	Request missing transaction-level mandatory additional fields.

Success response examples

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Result>000</Result>
  <ResultExplanation>Token been updated</ResultExplanation>
</API3G>

Failure response example for API v7

<?xml version="1.0" encoding="UTF-8"?>
<API3G>
  <Code>999</Code>
  <Explanation>Transaction invalid</Explanation>
</API3G>