home > support > API > Marketplace API > Create new Spreedly Payment

Create a Spreedly payment

Charge a credit card vaulted with Spreedly, storing details of the transaction on the booking and on success automatically committing the booking (if not already committed)


Notes

For those using Spreedly as a gateway this replaces the generic Payment Create API method and possibly also the Booking Commit method. Allows charging of a card (via a Spreedly Purchase) using a payment token likely obtained via a payment form, JSONP or a CORS JavaScript post (environment keys available via the Show Channel API).

For environments where AVS is likely to be enabled (i.e. most online transactions) do ensure you are providing Spreedly with the clients billing address at the poinft of adding the payment method. In the case of the JSONP/CORS methods you can check this has been stored successfully by viewing the response from Spreedly.

Learn more about TourCMS Spreedly integration

REST info

Endpoint/c/booking/payment/spreedly/new
FormatsXML
ExampleURL: /c/booking/payment/spreedly/new.xml
 
POST data:
<?xml version="1.0"?>
<payment>
  <spreedly_payment_method>AAABBBCCC</spreedly_payment_method>
  <booking_id>12345</booking_id>
  <payment_value>100</payment_value>
  <payment_currency>EUR</payment_currency>
</payment>
VerbPOST

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object spreedly_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 />');

// Set the Spreedly payment method token to use
$payment->addChild('spreedly_payment_method', 'AAABBBCCCDDDDEEE');

// 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');

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

// Call TourCMS API, charging the card
$result = $tourcms->spreedly_create_payment($payment, $channel);

if($result->error == "OK") {

	// Spreedly has successfully charged the card
	// TourCMS has committed the booking (if not already committed)
	// And stored details of the payment on the booking

	print "Thanks, payment added";
} else {

	// Spreedly was unable to charge the card
	// TourCMS has taken no action

	print "Sorry, unable to store the payment at this time";
}
Thanks, payment added

C# examples use the .Net Client Library

Overload list

XmlDocument SpreedlyCreatePayment ( 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);

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

// Set the Spreedly payment token (credit card) to use
XmlElement paymentToken = paymentData.CreateElement("payment_token");
paymentToken.InnerText = "AAABBBCCCDDD";
root.AppendChild(paymentToken);

// Send the data to the TourCMS API, recording the payment/refund
XmlDocument doc = myTourCMS.SpreedlyCreatePayment(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 SpreedlyCreatePayment ( 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)

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

' Set the Spreedly payment token (credit card) to use
Dim paymentToken As XmlElement = paymentData.CreateElement("spreedly_payment_method")
paymentToken = "AAAABBBBCCCCDDD"
root.AppendChild(paymentToken)

' Send the data to the TourCMS API, recording the payment/refund
Dim doc As XmlDocument = myTourCMS.SpreedlyCreatePayment(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

// Tell spreedly to charge 10GBP to the card represented by SPREEDLY_PAYMENT_METHOD_TOKEN
TourCMS.createSpreedlyPayment({
  channelId: 3930,
  payment: {
    spreedly_payment_method: "SPREEDLY_PAYMENT_METHOD_TOKEN",
    booking_id: "8400",
    payment_value: "10",
    currency: "GBP"
  },
  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
spreedly_payment_methodThe Spreedly Payment Method Token (credit card) to use. Likely obtained either via a payment form or CORS request. This must be provided.
booking_idTourCMS ID number for the Booking. This must be provided.
payment_valueAmount to charge the customer, if issuing a refund then use a negative value. This must be provided.
payment_currencyCurrency for the payment_value.
 
In most cases this will be the "sale_currency" for the Channel & Tour(s) being booked. If a different currency is provided TourCMS will use the exchange rate configured in the account to convert to the "sale_currency" before adding to the booking, in this case you must have an exchange rate loaded for this currency.
 
Instead, if you are using a Trust My Travel Spreedly account, and looking to implement their Multi Currency Pricing functionality, see the Trust My Travel note below.
payment_typeTextual description of the payment type. E.g. Credit card
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.
For those using Trust My Travel "Multi Currency Pricing" (Learn more)
salesledger_payment_valueAmount to store on the booking sale ledger in TourCMS (should be the amount in the channel currency).
 
The amount to charge the customer, in their chosen payment currency, should be passed in the payment_value node
salesledger_payment_currencyCurrency to store on the booking sale ledger in TourCMS (should be the sale currency for the Channel)

Trust My Travel “Multi Currency Pricing”

If your payment facilities have been provided by Trust My Travel and you are looking to implement their Multi Currency Pricing functionality - allowing your customers to pay in their own currency, yet have the correct amount be deducted from the TourCMS - you should use the following logic:

Customer paying in the normal channel sale currency

Use payment_value and payment_currency as normal

Customer paying in a different currency

Send the amount to bill the customer (i.e. their chosen payment currency) as payment_value and payment_currency, then send the amount to store on the sales ledger (i.e. the amount in your sale currency) as salesledger_payment_value and salesledger_payment_currency.

Trust My Travel will calculate the exchange rate you have used and verify that it is in a range that they will accept, if so they will attempt to charge the customer to the value of payment_value and if the payment is successful TourCMS will update the customers booking with a payment to the value salesledger_payment_value, keeping a note of the amount that the customer paid.

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