FAQ Q231: How can I use a payment gateway which is not supported by Planyo?

Planyo now lets you integrate payment gateways which are not by default supported by Planyo. Doing this requires programming skills using any server-side technology such as PHP.

Integration of a new payment gateway into planyo requires that you develop two scripts: a proxy script which will be called by planyo when the Pay Now button is clicked by the customer, and a callback script which will tell planyo 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 / online payments 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


Planyo 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 planyo'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 planyo 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 Planyo.
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:
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
FAQ