Payment API

Invoking the Payment API

https://www.bookerville.com/API-Payment?s3cr3tK3y=1234567890ABCDEFGHIJKLMNOPQRS

You will of course replace the "s3cr3tK3y" parameter with your own Bookerville API access token. If you don't have one, you may apply for one here: Request API Token

Note: for testing purposes it is fine to pass your API access token using simple query string parameters in the URL as in the sample above. Once you have completed testing, it is far better to pass it as an HTTP POST (form) parameter instead, because that is more secure.

The xmlPayload Field

The Payment API requires that you POST an XML document in a separate HTTP POST (form) key-value pair, called xmlPayload. The XML document you must submit in this field is as follows:

<bookingPayment> <bkvBookingId>85214</bkvBookingId> <operation>ADD | DELETE</operation> <bkvBookingPaymentId>12345</bkvBookingPaymentId> <datePaid>2024-04-24 04:23</datePaid> <type>Authorize.net | Credit/Debit Card | PayPal | Check | Bank Transfer | Other</type> <amount>850.00</amount> <refundableSecurityDepositPortion>0.00</refundableSecurityDepositPortion> <depositVenue>Channel | Manager</depositVenue> </bookingPayment>

<bkvBookingId>: This is the Bookerville id of the booking, which was returned to your software when you created the booking with the Booking API "ADD" operation.

<datePaid>: Must use "yyyy-MM-dd HH:mm" format, please note that the capital "HH" means this must be in 24-hour clock (European/Military) format.

<refundableSecurityDepositPortion>: This field is optional. If any part of the payment being posted is a refundable security deposit, specify the actual amount that is to be applied to the refundable security deposit balance. If this field is omitted, Bookerville assumes a value of 0.00.

Ex.: your software collected a $750.00 payment from the guest, $250.00 of that is a refundable security deposit. Your software could split the two into different Payment API invocations, one that has an <amount> field of 500.00 and a <refundableSecurityDepositPortion> field of 0.00 (or simply omitted), and the other Payment API call would have an <amount> field of 0.00 and a <refundableSecurityDepositPortion> field of 250.00. Or you could send it in one API call, but set the amount field to 750.00, and set the <refundableSecurityDepositPortion> field to 250.00.

<depositVenue>: If the transaction funds are being kept by your organization (or a channel partner of yours), specify "Channel" here. If the transaction funds have been collected in the property managers's account, specify "Manager" here.

<operation>: Either "ADD" or "DELETE". If DELETE, then <bkvBookingPaymentId> is mandatory.

<bkvBookingPaymentId>: Only required for DELETE operation. This value was returned to your software during the ADD operation.

Payment API Results

The results of a successful Payment API call will appear as the following example XML:
<BKV-API-Payment-Response> <status>success</status> </BKV-API-Payment-Response>

<status>: This field will either contain "success" or "failure". If "failure", look for <error> stanzas for help in resolving the issue.

Payment API Exceptions

The results of the Payment API may contain <error> stanzas or <warning> stanzas which are designed to help you debug issues. <error> stanzas are fatal, and a "failure" will be returned. <warning> stanzas are not fatal.

Examples:
<warning>Cannot recognize <type> field value: 'sjfhsdhjf'. Defaulting to 'Other'</warning> <error>API access token not found</error> <error>Cannot find booking for <bkvBookingId> value: '1234567'. Cannot continue</error> <error>Property 12345 'Sand Castle' is not participating with <your organization name>. Cannot continue</error> <error>Booking 19-254168-20150718, bkvBookingId: 1234567, was not created by <Your Organization Name>. Cannot update</error>

Note that <error> and <warning> stanzas may appear in-line with other XML content. Explanations will be given inside each stanza.