home > support > API > Marketplace API > record details of a new payment

Record a payment / refund

Store details of a new payment on a booking sales ledger. Allows Tour Operators to integrate their own payment methods and update the TourCMS sales ledger automatically.


Notes

For use by Tour Operator accounts only (not for use by Marketplace Partners). Not for use on temporary bookings (if inputting a booking via the API it must be committed before logging payments).

REST info

Endpoint/c/booking/payment/new
FormatsXML
ExampleURL: /c/booking/payment/new.xml
 
POST data:
<?xml version="1.0"?>
<payment>
  <booking_id>12345</booking_id>
  <payment_value>100</payment_value>
  <payment_currency>EUR</payment_currency>
  <payment_type>Credit Card</payment_type>
  <payment_reference>98765</payment_reference>
</payment>
VerbPOST

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object create_payment ( SimpleXMLElement $payment_data, int $channel )


Parameters

$payment
SimpleXMLElement containing all of the payment information
$channel
Channel ID as per TourCMS API settings page

Example

// Set your Channel ID, as per the TourCMS API settings page
$channel = 3;

// Create a new SimpleXMLElement to hold the payment details
$payment = new SimpleXMLElement('<payment />');

// Must set the Booking ID on the XML, so TourCMS knows which to update
$payment->addChild('booking_id', '194');

// Must set the value of the payment
$payment->addChild('payment_value', '20');

// Optionally set the currency
$payment->addChild('payment_currency', 'GBP');

// Optionally set the payment type
$payment->addChild('payment_type', 'Credit Card');

// Optionally add a reference
$payment->addChild('payment_reference', '12345');

// Call TourCMS API, storing the payment
$result = $tourcms->create_payment($payment, $channel);

if($result->error == "OK")
	print "Thanks, payment added";
else
	print "Sorry, unable to store the payment at this time";
Thanks, payment added

C# examples use the .Net Client Library

Overload list

XmlDocument CreatePayment ( XmlDocument paymentData, int channelId )


Parameters

paymentData
XmlDocument containing all of the payment information
channelId
Channel ID as per TourCMS API settings page

Example

// Set the ID for the channel the booking is made with
int channelID = 3;

// Create an XMLDocument to hold the payment details
XmlDocument paymentData = new XmlDocument();

// Create the XML Declaration, append it to XML document
XmlDeclaration dec = paymentData.CreateXmlDeclaration("1.0", null, null);
paymentData.AppendChild(dec);

// Create the root element, append it to the XML document
XmlElement root = paymentData.CreateElement("payment");
paymentData.AppendChild(root);

// Now add the various elements to the payment

// Must set the Booking ID so TourCMS knows which booking to add payment onto
XmlElement bookingId = paymentData.CreateElement("booking_id");
bookingId.InnerText = "12345";
root.AppendChild(bookingId);


// _MUST_ set the value of the payment (negative if it's a refund)
XmlElement paymentValue = paymentData.CreateElement("payment_value");
paymentValue.InnerText = "100";
root.AppendChild(paymentValue);

// Optionally set the currency
XmlElement paymentCurrency = paymentData.CreateElement("payment_value");
paymentCurrency.InnerText = "GBP";
root.AppendChild(paymentCurrency);

// Optionally set the payment type
XmlElement paymentType = paymentData.CreateElement("payment_type");
paymentType.InnerText = "Credit card";
root.AppendChild(paymentType);

// Optionally add a reference
XmlElement paymentReference = paymentData.CreateElement("payment_reference");
paymentReference.InnerText = "6789";
root.AppendChild(paymentReference);

// Send the data to the TourCMS API, recording the payment/refund
XmlDocument doc = myTourCMS.CreatePayment(paymentData, channelId);

// Check the status
// Will be "OK" if the payment was stored successfully
string status = doc.SelectSingleNode("//error").InnerText;

Console.WriteLine(status);
OK

VB examples use the .Net Client Library

Overload list

XmlDocument CreatePayment ( XmlDocument paymentData, Integer channelId )


Parameters

paymentData
XmlDocument containing all of the payment information
channelId
Channel ID as per TourCMS API settings page

Example

' Set the ID for the channel the booking is made with
Dim channelID As Integer = 3

' Create an XMLDocument to hold the payment details
Dim paymentData As XmlDocument = new XmlDocument()

' Create the XML Declaration, append it to XML document
Dim dec As XmlDeclaration = paymentData.CreateXmlDeclaration("1.0", null, null)
paymentData.AppendChild(dec)

' Create the root element, append it to the XML document
Dim root As XmlElement = paymentData.CreateElement("payment")
paymentData.AppendChild(root)

' Now add the various elements to the payment

' Must set the Booking ID so TourCMS knows which booking to add payment onto
Dim bookingId As XmlElement = paymentData.CreateElement("booking_id")
bookingId.InnerText = "12345"
root.AppendChild(bookingId)

' _MUST_ set the value of the payment (negative if it's a refund)
Dim paymentValue As XmlElement = paymentData.CreateElement("payment_value")
paymentValue.InnerText = "100"
root.AppendChild(paymentValue)

' Optionally set the currency
Dim paymentCurrency As XmlElement = paymentData.CreateElement("payment_value")
paymentCurrency.InnerText = "GBP"
root.AppendChild(paymentCurrency)

' Optionally set the payment type
Dim paymentType As XmlElement = paymentData.CreateElement("payment_type")
paymentType.InnerText = "Credit card"
root.AppendChild(paymentType)

' Optionally add a reference
Dim paymentReference As XmlElement = paymentData.CreateElement("payment_reference")
paymentReference.InnerText = "6789"
root.AppendChild(paymentReference)

' Send the data to the TourCMS API, recording the payment/refund
Dim doc As XmlDocument = myTourCMS.CreatePayment(paymentData, channelId)

' Check the status
' Will be "OK" if the payment was stored successfully
Dim status As String = doc.SelectSingleNode("//error").InnerText

Console.WriteLine(status)
OK

NodeJS examples use the NodeJS Wrapper


Example

// Record a payment on the booking of value 10 (in the Channel currency)
TourCMS.createPayment({
  channelId: 3930,
  payment: {
    booking_id: "8400",
    payment_value: "10",
  },
  callback: function(response, status) {
    console.log(response.error);
  }
});
OK

Looking for sample code in a different language? TourCMS and community provided API libraries

Querystring parameters

There are no querystring parameters supported by this method.

Post fields

The following fields can be posted as XML when calling the API.

Post fields
XML NodeNotes
payment

The root XML element, can contain any of the following child nodes.

XML NodeNotes
booking_idTourCMS ID number for the Booking. This must be provided.
payment_valueAmount being paid, negative if issuing a refund.
This must be provided.
payment_currencyCurrency for the payment. Must be one of the configured currencies on the account. IF not set, will assume in the sale currency of the booking.
payment_typeTextual description of the payment type. E.g. Credit card
payment_dateOptional (if not set, will take todays date / time). YYYY-MM-DD
payment_referenceFreetext reference number (possibly from the payment gateway)
payment_transaction_referenceReference number in a specific format (to enable us to refund a payment later, if a credit card payment) e.g. WORL|1224
payment_noteAny extra detail that needs to be recorded
payment_byC for customer or A for agent
payment_by_idEither a Customer ID or an Agent ID. If not specified TourCMS will presume either the lead pax or agent has paid.
booking_status_updateSet to 0 to stop TourCMS automatically updating the booking status
creditcard_fee_typeInteger representing if and how to apply the preconfigured credit card fee:
 
0 - No credit card fee
 
1 - Fee included. E.g. you charge the customer 100 GBP with a 3% credit card fee included. The customer will pay 100 GBP and 100 GBP will be reduced from the outstanding balance. A 2.91 GBP fee will be added to the booking (don't use this if the customer is clearing their balance as it will leave money owed on the booking)
 
2 - Fee already added. E.g. you charge the customer 103 GBP with a 3% credit card fee added. The customer will pay 103 GBP and 103 GBP will be reduced from the outstanding balance. A 3 GBP fee will be added to the booking.
 
3 - Fee waived, use this if a fee should have been applied but was waived by staff
 
In the majority of cases, if a fee is being added then number 2 above will be used.

Response fields

Response fields
XML NodeNotes
request Confirmation of the request that you sent
error Any error message returned, if there is no error this will just contain the text OK
booking

If the booking is found the booking node will contain the following child nodes.

XML NodeNotes
booking_idBooking ID

More information