Q231: How can I use a payment gateway which is not supported by checkin24-7?

Sie sind hier: checkin24-7 » Hilfe » FAQ » Q231: How can I use a payment gateway which is not supported by checkin24-7?
Checkin24-7 now lets you integrate payment gateways which are not by default supported by Checkin24-7. Doing this requires programming skills using any server-side technology such as PHP. If you don't have a developer who can help you with this, please contact us and we will be happy to develop this for you.

Integration of a new payment gateway into checkin24-7 requires that you develop two scripts: a proxy script which will be called by checkin24-7 when the Pay Now button is clicked by the customer, and a callback script which will tell checkin24-7 about any change in the status of the payment by calling a callback URL.

In order to use a custom payment gateway, you must change in site settings the Payment processing site option to Custom payment gateway and then set the Proxy page parameter to the full URL of the proxy script. The resources should also have pricing defined and use OPTIONAL PAYMENT or OBLIGATORY PAYMENT as the reservation confirmation method. Alternatively the payment form can be included in any screen or email using the payment form tags described in Q204.

Proxy script

Checkin24-7 will submit the payment form to your proxy script, redirecting the customer there and sending detailed information about the reservation as POST parameters. You don't have to use all these parameters, for example many payment gateways don't let you pass the contact details (address, phone etc.) while others will so that the customer doesn't need to fill them out again on the payment gateway's website. Some of the parameters passed to the proxy script must be sent back to checkin24-7's callback URL once the payment is done. The payment gateways will let you pass custom fields so use them to store these parameters, specifically: reservation_id and security_key.

Your proxy script should initiate the payment by redirecting the customer to the secure page on the payment gateway's website. You can do this by creating a hidden form with the fields specific to your payment gateway on a blank page and use javascript to submit the form immediately. You can see some samples for for Wirecard or EBS or Authorize.net.

Here's the full list of parameters passed to the proxy script:
POST parameter nameDescription
reservation_idID of the reservation. Must be passed back to the callback_url
amountTotal to be paid online (including online payment surcharge if any)
currencyCurrency as a 3-letter ISO 4217 code, e.g. USD, EUR, CHF
surchargeOnline payment surcharge (as defined in site settings)
resource_nameName of the resource being reserved
resource_idID of the resource being reserved
site_nameName of the checkin24-7 site
language2-letter ISO 639-1 language code (e.g. EN, DE, FR, IT, ES)
redirect_urlURL where the customer should be redirected after the payment is done (whether successful or not)
callback_urlURL where you must post results of the transaction before redirecting the customer to redirect_url. You will find the specs for the parameters to be passed further down in this document.
security_keyYou must pass this security key back to the callback_url. This key is different for each reservation ID. Otherwise the payment will be ignored by Checkin24-7.
first_nameCustomer's first name (as filled out in the reservation form)
last_nameCustomer's last name
emailCustomer's email address
customer_idCustomer's unique user ID
addressCustomer's address
cityCustomer's city
stateCustomer's state
zipCustomer's zip/postal code
country2-letter country code (ISO 3166-1 alpha-2)
country_33-letter country code (ISO 3166-1 alpha-3)
phone_country_codeCountry code part of the phone number
phone_numberPhone number without country code
mobile_country_codeCountry code part of the mobile phone number
mobile_numberMobile phone number without country code
The script also receives all additional reservation form data. For example, if you added to the reservation form a check box 'Airport transfer' it would be passed as the parameter 'Airport_transfer'. Note that space and other non-alphanumerical characters are replaced with underscore. Checkboxes, if selected, will have the value: on (no value otherwise).

Callback script

The callback script will be called by the payment gateway when the transaction is processed. Often payment gateways call your callback script also whenever the status of a payment is changed (e.g in case of a chargeback). Your callback script must do two things in the following order:
  • 1. Post some parameters to checkin24-7's callback_url. This URL was passed to your proxy script (it will be always http://www.checkin24-7.com/payment-custom-ipn.php). The parameters accepted by the callback URL are listed below. Doing this will tell checkin24-7 about the payment so it will be saved in the database and in case of obligatory payment or optional payment the reservation status will be updated automatically. This usually triggers the confirmation emails to be sent to the customer. The online payment received email or SMS notification (if defined by you) will be also sent out.
  • 2. Only then redirect the customer to redirect_url. This URL was also passed to the proxy script. This way the customer can see the new status of their reservation (on checkin24-7.com in case of simple integration and on your website in case of advanced integration) on the reservation completed template.

You can post the payment status changes to callback_url many times. Each such change in the payment status will be saved in the database so the administrator can see the transaction log.

Here's the full list of parameters which your callback script should send to callback_url. Most of these fields are required (see the third column):
POST Parameter nameDescriptionObligatory field
payment_statusStatus of the payment. Can be one of: Completed, Denied, Failed, Pending, Refunded, Reversed. You should set this to Completed for a successful payment. Otherwise use one of the other statuses.Yes
reservation_idID of the reservation. This was passed to the proxy script under the same name.Yes
security_keySecurity key. This was passed to the proxy script under the same name.Yes
amountAmount paid.Yes
currencyCurrency of the payment.Yes
transaction_idID of the transaction.Yes
status_descriptionText description of the payment status.No
reason_codeCustom error code, if any.No