Custom questions via API

[Ryan]

We're migrating from using a FaaS built by CnP that includes several 'Custom Questions' as hidden inputs. We're moving instead to posting transactions via the SOAP API.


I've been trying to pass in values for these custom questions using the 'CustomParameter' tags inside the API XML. However, as far as I can tell none of that information makes it into Salesforce at all.


My CustomParameters XML looks like this:


<CustomParameters>
<Parameter>
<Field>FieldValue2</Field>
<Value>{{ sf_campaign_name }}</Value>
</Parameter>
<Parameter>
<Field>FieldValue3</Field>
<Value>{{ entity }}</Value>
</Parameter>
<Parameter>
<Field>FieldValue4</Field>
<Value>{{ fund }}</Value>
</Parameter>
<Parameter>
<Field>FieldValue5</Field>
<Value>{{ community }}</Value>
</Parameter>
</CustomParameters>


We have triggers inside Salesforce that run on the custom questions we've been getting from our current iframed form, so it would be easiest if I could pass values in to the custom questions, but I'm also okay if it goes into some different field.

I've read through the (pretty threadbare) documentation on the CustomParameters tags, and that didn't clarify things.


On a related note, is there a way for me to get the CnP Transaction ID (in Salesforce) or the Donation/Opportunity ID from the API? There are other fields we would like to set as well, and the response from the API doesn't point to any Salesforce records.


Thank you!

[CnP.Support]

Ryan,

The manual for SOAP has all nodes discussed and various examples showing how to use it. I am not sure how much more documentation you need. We can gladly add more text in there but other than description and examples on how to use what else can one do?

Questions:

1: Does the transaction post to Salesforce?
2: Do you see the transaction posted to "C&P Data" tab?
3: Please post the Order Number for a transaction that you have posted so I can review the XML

Once I have more information I will go ahead and review the information.

[Ryan]

Thanks for your response.

The good news is that I figured it out: I needed to use the <CustomFieldList> tags (under <CardHolder>) instead of <CustomParameters> (under <OrderItem>). So, I can now confirm that my custom information is showing up in Salesforce under the C&P Transaction section titled "Custom Questions".

As far as documentation, thanks for asking for some feedback, I'm eager to help. Here are some areas that were confusing or unclear to me:

1. What's the difference between CustomParameters and CustomFieldList? Which should I use, and why?
2. Where do fields go in Salesforce?
3. From my testing, putting Salesforce info in the ThirdParty.CRMs section has absolutely no effect; I assume this is because our CnP account is linked up to a Salesforce sandbox separately? This should be documented.
4. The order of tags is apparently important (e.g. CardHolder.CustomFieldList can't come before PaymentMethod), but the documentation doesn't specify this, and the resulting API error is literally incorrect (it claims that CustomFieldList can't be a child of CardHolder, when it should specify that CustomFieldList needs to come before PaymentMethod). This came up for some other tags I was trying to use, and I had to use trial and error to figure it out.
5. Does Request.Operation.IPAddress allow IPv6? I sure hope so, but the documentation suggests it doesn't.
6. Request.Operation.UrlReferrer needs some sort of escaping (e.g. URL query parameters, with ? and &), but the docs don't specify what things need to be escaped.
7. Recurring.Periodicity documentation states "Credit card expiration date will be checked for validity based on the period and installments." This is not true. If I set Installments to 999, and Periodicity to Month, my card that expires next year is approved just fine.

The biggest difficulty I've had with the documentation is actually this: the docs specify each node available in the SOAP XML, and there are some examples of XML, but there's very little guidance or tutorial on how to use the API and what it does. Context. For example, when will the transaction be posted into Salesforce, and how can I access that data? I think there's a missing step when the "Getting Started" section jumps right into example XML.

I must applaud your team for the thorough documentation and clean organization of response error codes, as well as the fact that you've covered every node available in the XML. I'm just trying to share some areas I struggled with while working with the documentation. I hope you don't mind the list.

Thanks!
Ryan

[CnP.Support]

Hi Ryan,

Reply to your questions:

Question: What's the difference between CustomParameters and CustomFieldList? Which should I use, and why?
Answer: Custom Questions show in the receipt and and is exposed to the end user whereas Custom Parameters are the parameters that are passed on internally as part of the XML response. For example- in Salesforce we pass the Salesforce ContactID as a custom parameter when interacting with the Virtual Terminal.

Question: Where do fields go in Salesforce?
Answer: Custom questions are posted as a related list in Salesforce. Custom Parameters don't post to anything and are part of the XML only. The XML may be parsed for the fields and the values. Again an example is ContactID that we pass from the Virtual Terminal to the API and parse it to determine the Contact which was used to make the payment.

Question: From my testing, putting Salesforce info in the ThirdParty.CRMs section has absolutely no effect; I assume this is because our CnP account is linked up to a Salesforce sandbox separately? This should be documented.
Answer: No- connection of the Salesforce in the Portal allows for donation forms developed in the portal to post to your Salesforce instance. In the absence of that information it won't know to what account to post. Sandbox or Production has no relevance since payments using the payment forms will post to the Sandbox or Production instance of Salesforce. If you are ONLY using Salesforce and developing in Salesforce then it is not needed since all those parameters are passed on through the API.

Question: The order of tags is apparently important (e.g. CardHolder.CustomFieldList can't come before PaymentMethod), but the documentation doesn't specify this, and the resulting API error is literally incorrect (it claims that CustomFieldList can't be a child of CardHolder, when it should specify that CustomFieldList needs to come before PaymentMethod). This came up for some other tags I was trying to use, and I had to use trial and error to figure it out.
Answer: I am not sure what you are referring to. Are you using the SOAP API or are you using the API Class Library app in appExchange? I am not sure what you are using. Our examples should also show you the order. Any XML has an order of parent and child nodes and they cannot be mixed.

Question: Request.Operation.UrlReferrer needs some sort of escaping (e.g. URL query parameters, with ? and &), but the docs don't specify what things need to be escaped.
Answer: That node is not needed. The minimum requirements are in an example. The URL referrer is used and posted as part of the XML so you know where the payment or order came from. In the Transaction object you see the URL referrer but it is not required.

Question: Recurring.Periodicity documentation states "Credit card expiration date will be checked for validity based on the period and installments." This is not true. If I set Installments to 999, and Periodicity to Month, my card that expires next year is approved just fine.
Answer: No- we only check for validity of the credit card number and that the expiration date is not in the past. If we were to use the expiration date validation no indefinite processing would be possible since no card is valid for 999 months / year. The idea is to simply provide the means for our clients to contact the client when the card expires.

I hope the above helps with the questions you had. We will work on the manual and add more examples. Please note that this is a new product and is a prerequisite for all of our applications moving forward. It is being used by a number of companies building payment applications on our API platform. As questions come up we will answer and add to the manual.

I look forward to hearing about your application and what you are doing. We will add to the manual based on your questions.

[Ryan]

Great, thanks for your responses. Sorry for my delay, I've been head-down working on our new online donation functionality.

I'm glad you're open to making some improvements to the docs, so future devs might have a faster time in some areas than I did. I'm always eager to help.

My biggest new question: you mention passing Salesforce ContactID as a CustomParameter; is that something I can do as well? Or is that only available to your internal apps like Virtual Terminal? If it's possible, I'd love to do it! This would be very helpful, since by the time I call the CnP API, I've already created or found a contact in Salesforce, so it would be better to reference that contact precisely.



Our project:

I'm building a new set of advanced functionality around our donation process on our website (stand.org). We're giving our marketers/fundraisers lots of control over the content on donation pages, implementing A/B testing for giving amounts and ask copy, and integrating it into a full process that lets supporters easily engage in many ways. We're scheduled to launch the new features to stand.org on Wednesday Oct 17th, so you can check it out then!

[CnP.Support]

Ryan,

Yes- you can pass any parameter as part of the CustomParameter.

If you look at the eVT settings:

http://manual.clickandpledge.com/Salesforce-Embedded-Virtual-Terminal.html

you can see that we pass SFContactID to the XML and then act on it through the posted XML in C&P Data.

So naturally once you use it you can take advantage of it by reading it in the XML.

Good to know of the launch. Perhaps we can review it and come up with a case study.