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 name | Description |
|---|
| reservation_id | ID of the reservation. Must be passed back to the callback_url |
| amount | Total to be paid online (including online payment surcharge if any) |
| currency | Currency as a 3-letter ISO 4217 code, e.g. USD, EUR, CHF |
| surcharge | Online payment surcharge (as defined in site settings) |
| resource_name | Name of the resource being reserved |
| resource_id | ID of the resource being reserved |
| site_name | Name of the planyo site |
| language | 2-letter ISO 639-1 language code (e.g. EN, DE, FR, IT, ES) |
| redirect_url | URL where the customer should be redirected after the payment is done (whether successful or not) |
| callback_url | URL 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_key | You 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_name | Customer's first name (as filled out in the reservation form) |
| last_name | Customer's last name |
| email | Customer's email address |
| customer_id | Customer's unique user ID |
| address | Customer's address |
| city | Customer's city |
| state | Customer's state |
| zip | Customer's zip/postal code |
| country | 2-letter country code (ISO 3166-1 alpha-2) |
| country_3 | 3-letter country code (ISO 3166-1 alpha-3) |
| phone_country_code | Country code part of the phone number |
| phone_number | Phone number without country code |
| mobile_country_code | Country code part of the mobile phone number |
| mobile_number | Mobile 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 planyo's callback_url. This URL was passed to your proxy script (it will be always https://www.planyo.com/payment-custom-ipn.php). The parameters accepted by the callback URL are listed below. Doing this will tell planyo 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 planyo.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 name | Description | Obligatory field |
|---|
| payment_status | Status 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_id | ID of the reservation. This was passed to the proxy script under the same name. | Yes |
| security_key | Security key. This was passed to the proxy script under the same name. | Yes |
| amount | Amount paid. | Yes |
| currency | Currency of the payment. | Yes |
| transaction_id | ID of the transaction. | Yes |
| status_description | Text description of the payment status. | No |
| reason_code | Custom error code, if any. | No |