Creator Help

Accept Payments through Forms

Table of Contentsup

Overview

Zoho Creator supports creation of Payment forms to enable you to accept payments from your users. Through a set of simple payment configurations, you can accept various types of payments easily from your users. Following are some uses of this feature.

  • Sell items - Show a list of items for your users to choose and allow them to buy one or more items.
  • Collect donation - If you are a non-profit organization, collect donation from your users.
  • Online registration - Create a registration form for events/training etc., and collect a fee through the payment form

Payments module is supported in the following plans:

  • Regular Plans - Professional and Enterprise
  • Express Plans - Professional

Enable Payment For Your Form

Zoho Creator provides payment feature as an extension to its form. Once payment is configured for a form, users will be taken through the steps for paying when a record is added into the form. The data for payment is taken from the record that is added. Hence payment configuration will consist of the mapping of form-fields to payment fields. For eg, If the form has "Amount" field, then this can be mapped to the payment amount. In this case, whatever the user enters in the amount field, while adding the record, will be used as the payment amount.

Please find the steps given below to enable payment options for your form:

  1. Select the Form and click on Form Settings -> Payment. The Payment Settings page is displayed as shown below.

2. Different configuration options are explained below. Specify the required values and click Save to configure payments for the form.

  • Paypal Email ID: Specify your paypal account's email address. This should be a business account for accepting payments.
  • Use sandbox: Select the Use sandbox, if you want to test your payment form integration using Paypal's sandbox environment. Once you are good to go, you can uncheck it.
  • Currency: Currency refers to the currency in which the payment takes place. The currencies listed in the dropdown are the ones supported by Paypal. Select any one of the listed currencies to accept payments in that currency. 
  • Accept payment on a recurring basis: Check this option if you want your users to pay you at a regular interval. Also specify the recurring interval in terms of days, weeks, months or years. Once configured, Paypal will obtain the authorization from the payer (either a Paypal account or a Credit/Debit card) and debit their account on a recurring basis at the specified interval.
  • Need Payer Address: Choose if your users have to specify their address while checking out at the paypal website.
  • Payment Type: The payment type refers to the different use case scenarios of accepting payments. "Selling Item" type is typically used when you want to sell a single product. It allows a user to buy a product with a given rate, specified by the "Amount" field, and a quantity specified by the "Quantity" field. "Donation" is used when you are collecting donations from your users. Note that when you select "Collect Donation", the "Quantity" field is hidden since quantity does not apply to donations.
  • Language: Choose the language in which the paypal checkout pages will be displayed.

If you want to disable payment for the form later and make it behave like an ordinary form, you can do so by disabling the Enable Payment check box from the Form settings -> Payments page.

Payment Fields

Payment Fields refers to the individual field mapping so that the requisite field-data from the added record is sent to Paypal.

  1. Amount - Refers to the amount that is paid in the case of "Donation" and price of an item in the case of "Selling Items". It can be one of the numerical field types (Number, Decimal, Currency). If a currency field is chosen, then the final currency that is sent for payment follows the currency resolution logic. Otherwise whatever currency that is configured above will be used.
  2. Item - Useful for referring to the payment made. It can be used as the product name, payment remarks etc., It can be one of the string field types (Single Line, Multi Line etc.,).
  3. Quantity - Refers to the quantity of items in an order. It can be one of the "Number" fields in the form. If this field is left, the quantity value defaults to 1.

Currency Resolution Logic

If a currency field is used for the "amount" field, it might present a conflict between the currency configured in payment settings and the field's currency, for eg, a USD as the payment setting's currency and rupee as field's currency. In such cases, the following logic is used for resolving the currency that is sent to paypal. No exchange rate calculations are performed. The original amount value is itself used, but the appropriate currency is resolved before sending to paypal.

  • If the field's currency is a valid paypal currency, then the field's currency is sent to paypal.
  • If the field's currency is not a valid paypal currency, the currency that is configured in payment settings is used.

Making the Non-Recurring Payment

  1. In the form live mode, when the form is submitted, all form-add processing takes place except the "On Success" action. 
  2. Once the data is validated and added, the user is redirected to the paypal site for payment. 
  3. Payment takes place only when a record is newly added. It is not done when a record is edited through reports. Payment also does not take place when records are added through script/import or any other methods.
  4. In the paypal site, after the payment is done the user can click the "Return" button to return back to the creator site. The user will then be presented with the results of the "On Success" action and taken through other pages. 
  5. When the payment is made, paypal sends all the payment details to Zoho Creator separately. Zoho Creator processes the information, store the payment details, and map them to the added record. To achieve this, Zoho Creator adds a Subform system field when payment is configured for the form. Besides storing the payment details, the "On Success" action is performed. This will help you to specify any order-fulfillment logic in the "On Success" action.
  6. As specified above, the form will have a subform system field for the sake of payments. This field will refer to the payment history details present in a form in a hidden app. Each record will map to the respective payment records in the history form. To check the payment details of a record, you can extend the form's view to include the payment related fields. This can be achieved through the Report Edit mode. 

Making the Recurring Payment

  1. In the form live mode, when the form is submitted, all form-add processing takes place except the "On Success" action.
  2. Once the data is validated and added, the user is redirected to the paypal site for subscription purchase.
  3. In the Paypal site, after the user purchases the subscription, they can click the "Return" button to return back to the creator site. The user will then be presented with the results of the "On Success" action and taken through other pages. When the user purchases the subscription, the subscription sign-up details will be sent to Zoho Creator. Zoho Creator will store the subscription sign-up details, and map them to the added record. Besides storing these subscription sign-up details, it will perform "On Success" action.
  4. Paypal will henceforth take care of debiting their account on a recurring basis as per the specified interval. Each time the recurring payment takes place, Paypal will send the payment details. As in the Non-Recurring process, Zoho Creator will store the payment details, and map them to the added record. Besides storing these payment details, it will perform "On Success" action.

Note:

  • Lookup, formula fields can also be used for field mapping if their values are of appropriate type. For eg, if a formula resolves to a numerical value, it can be used for "Amount" field (the formula field will be listed in the dropdown). Similarly if the form contains a Lookup which refers to a "Number" field, it can be used for "Quantity". These extensions help in implementing complex scenarios.
  • Even if dropdown fields are filled with numbers, they resolve only to string type. Hence they cannot be used for "Amount" or "Quantity" field, but can be used for "Description" field.
  • If a form is embedded in a webpage using Iframe, then payment redirection will take place only through the main window and not through the Iframe. Paypal does not allow payments to take place in an Iframe for the sake of security.
  • For the entire flow to go smoothly, please check the following settings in your paypal profile.
    • Set Auto-return to "Off".
    • Set Payment Data Transfer to "Off"

 FAQ's

1. I want to accept payments from my users. What are the prerequisites?

You need a Paypal business account to accept payments from your users. Please check https://www.paypal.com/cgi-bin/webscr?cmd=p/gen/personal_vs_business-outside for more details.

2. Is it possible to test my payment form with virtual currency before I expose it to the users?

Yes. It is possible to test your payment form with virtual currency through Paypal Sandbox site. To create a test setup, follow the steps below.

  • Signup for a Paypal developer account at https://developer.paypal.com/
  • Create atleast one business account and personal account. Please check https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_Sandbox_UserGuide.pdf for more details.
  • Use the business account created above while configuring the payment settings in Zoho Creator. Ensure that “Use Sandbox” option is selected. Else, it will assume it is a live account.
  • Use the personal account created above during checkout.

3. I already have a Paypal account. Can I use it in Sandbox?

No. Paypal maintains separate setup for Live and Sandbox. Hence a Live Paypal account cannot be used in Sandbox or vice versa.

4. Can a stateless form be used to submit payment and in the on success script can we write code to manipulate data in the records of another form?

No. Currently, we support payments only through stateful forms.

5. I see a new field labeled “Payment” in my view. What is it useful for?

The “Payment” field maintains a list of transactions that have taken place for a particular record. While it will have one transaction for a non-recurring transaction, it will maintain a list of transactions for recurring transactions.

6. I embed the Payment form in my website. But it leaves my website and gets redirected to Paypal.

The payment forms are embedded using Iframes in your website. For security reasons, Paypal does not allow payments through Iframe. Hence the behavior.

7. What happens if the return button is not clicked? Will the On-Success script run in such a case?

Yes. Even if the users do not click the “Return” button in the Paypal website, the On-Success script will run. This is achieved through a background handshake between Zoho Creator and Paypal, wherein Paypal sends the transaction details to Zoho Creator.

8. Can you elaborate the recurring payment process? How payments are obtained from users at a periodical interval?

Zoho Creator forms can be configured to accept recurring payments. When users add a record to such a form, they will be redirected to Paypal sending along with, the recurring amount and duration details. Once they authorize the payment, a subscription profile will be created. After this profile is created in Paypal, aka “subscription signup”, Paypal will take care of obtaining the recurring payments on a regular interval based on the recurring duration setup in the payment configuration, till the profile is canceled by the user. Please check https://merchant.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=merchant/erp_overview for more details.

9. How do users cancel subscription? In case they contact us, how do we cancel their subscription?

Users can cancel subscription through the Profile pages in their account. Please check https://www.paypal.com/helpcenter/main.jsp?cmd=_help&solutionId=27715&t=solutionTab for more details. 
Please check https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/howto_admin_recurringpayments#admin to understand how to administer all recurring payment profiles that your users have created and cancel any profile based on your user's request

10. Will we get intimated whenever users pay?

Yes. Whenever any payment takes place, the details are sent by Paypal to Zoho Creator. Zoho Creator processes those transactions, stores them and links them to the record in the Payment form that initiated the payment, through the “Payment” field.

11. If a user's payment fails for a particular period, will we be intimated about it? In case we need to check manually, what should we do?

Yes. Any events taking place in Paypal will be intimated to Zoho Creator. Zoho Creator will process, store and link those details to the record in the Payment form that initiated the payment through the “Payment” field.

12. I see only “Selling Items” and “Donation” as payment types. What should I do if I want to create a registration form, fee collection form etc ?

As long as the form contains a string field to map as a payment item name/remark/description and a decimal/currency field to map as the payment amount, any stateful form can be can be configured for payment. To achieve this, create the form with the required fields. Open the “Payment” dialog from the Form Edit. Configure your Paypal settings, select “Selling Items” type and then map the Payment fields. If you want the payments to be marked as donation, select “Donations” type instead.

13. I want my users to choose a donation amount from a dropdown of present donation amounts. Is it possible?

Yes. Follow the steps given below.

  • Create a Single-Item selling form through the Create Form flow.
  • Go to the edit mode of the payment form.
  • Click the “Payment” link to open the “Payment Settings” dialog.
  • Change the payment type to “Donations” and save.

14. I want to send Emails (in general, any post-payment processing) to my user confirming their payment. How do I do?

You can achieve any post-payment processing through the On-Add On-Success script. You can use the following code template to perform any post-payment processing.

Non-Recurring Payment

//ZC_Payment is a subform field present in the form. It will contain a list of transactions related to the current record
//Loop through all records in ZC_Payment subform field.
for each rec in input.ZC_Payment
{

//payment_processing_status will be "" for records that are not processed.
//Once the On-Success script finishes successfully, its value will be "Completed". Skip them here.
//If the On-Success script finishes unsuccessfully, its value will be "On Success Error". Skip them here.

if(rec.payment_processing_status == "")
{

//Check if it is payment transaction.

if (rec.txn_type.equalsIgnoreCase("web_accept"))

{

//payment_status is valid only for payment transactions
//Make sure the payment_status is "Completed".

if(rec.payment_status == "Completed")
{
//related code
}
else
{
//handle all other payment_status values
}
}
else
{
//handle all other txn_type values
}
}
}

Recurring Payment

//ZC_Payment is a subform field present in the form. It will contain a list of transactions related to the current record
//Loop through all records in ZC_Payment subform field.

for each rec in input.ZC_Payment
{

//payment_processing_status will be "" for records that are not processed.
//Once the On-Success script finishes successfully, its value will be "Completed". Skip them here.
//If the On-Success script finishes unsuccessfully, its value will be "On Success Error". Skip them here

if(rec.payment_processing_status == "")
{

//Check if it is a subscription signup.

if (rec.txn_type.equalsIgnoreCase("subscr_signup"))
{

//related code
}
//Check if it is a subscription cancellation.
else if (rec.txn_type.equalsIgnoreCase("subscr_cancel"))
{
//related code
}

//Check if it is recurring payment transaction.
else if (rec.txn_type.equalsIgnoreCase("subscr_payment"))

{
//payment_status is valid only for payment transactions
//Make sure the payment_status is "Completed".

if(rec.payment_status == "Completed")
{
//related code
}
else
{
//handle all other payment_status values
}
}
else
{
//handle all other txn_type values
}
}
}

15. What payment fields can I use in my On-Success logic?

The following fields can be used through the ZC_Payment subform.

Fields internal to Zoho Creator: 
payment_id - Unique value to identify the payment in Zoho Creator. It has the format Paypal-WPS-<transaction id>
environment - Sandbox or Live
all_params - The consolidated value of all parameters received from Paypal, delimited by "&"
payment_processing_status - The processing status of this record.

Fields whose values are obtained from Paypal:
payment_type - The funding sources for the payment.
payment_date - The time when the payment took place. It is empty for non-payment transactions, like subscription signup/cancel.
payment_status - The status of the payment transaction.
address_status - The address status of the payer.
payer_status - The status of the payer.
first_name - The first name of the payer.
last_name - The last name of the payer.
payer_email - The email id of the payer.
payer_id - A unique value to identify the payer in Paypal.
business - The Paypal business Email Id to which payments are made.
receiver_email - The primary Email Id of the receiver.
receiver_id - A unique value to identify the receiver in Paypal.
mc_currency - The currency in which the payment is made. It is empty for non-payment transactions, like subscription signup/cancel.
mc_fee - The fee taken by Paypal for the transaction. It is empty for non-payment transactions, like subscription signup/cancel.
mc_gross - The total amount paid by the payer. It is empty for non-payment transactions, like subscription signup/cancel.
txn_type - The transaction type. It can be web accept, subscription signup, subscription payment etc.,
txn_id - A unique transaction id generated by Paypal for the transaction. It is empty for non-payment transactions, like subscription signup/cancel.
mc_amount3 - The regular subscription amount setup in Paypal. This has a value only when txn_type is “subscr_signup”.
Period3 - The regular subscription interval setup in Paypal. This has a value only when txn_type is “subscr_signup”.

16. Once the user finishes payment, I want to redirect them to a different page instead of the payment form. How do I do that?

Use one the of following options to specify the next url

  • Configure the url in the Edit Form – More Options – Form Properties dialog.
  • Configure the next url while embedding. More details..
  • Use the OpenUrl task in On-Success script. More details..

Top