API Resources

Quick Start

Senest redigeret:

Make your first API Call

Retrieve Payment API URL and Key from Settings in OnlineFundraising.

Variable Value
PAYMENT_API_URL Payment API URL
PAYMENT_API_KEY Payment API Key specific to your organisation
CONTACT_GUID A Contact GUID from an existing record in OnlineFundraising

 

Postman

cURL

Run this in your terminal:

curl --location --request GET 'PAYMENT_API_URL/contact/CONTACT_GUID' \
--header 'Content-Type:  application/json; charset=utf-8' \
--header 'Authorization: PAYMENT_API_KEY'

Please note that you may have to use " instead of '.

C#

Compile and debug the following code:

var client = new RestClient("PAYMENT_API_URL/contact/CONTACT_GUID");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Content-Type", " application/json; charset=utf-8");
request.AddHeader("Authorization", "PAYMENT_API_KEY");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Send your First Webhook

Configuration of webhooks is currently performed by the OnlineFundraising-team. Please contact support@onlinefundraising.dk to request webhook configuration. Provide an endpoint, as this is required to setup webhooks.

Once your webhook setup is done, perform the event in OnlineFundraising to trigger the webhook. Read on for a walk-through guide of sending your first webhook.

Walk-through of sending your first webhook

Follow this example to send your first webhook when a Payment is created as a result of a submitted form.

Step 1. Configure Webhook

To start off, you have to ensure that a webhook is setup for Payments.

Step 2. Create and configure a Form

Create and configure a form like the picture below. It is important that you learn how to build forms from scratch. Once you have completed this guide we recommend that you get to know the FormBuilder more in-depth.

mceclip0.png

Configure Purpose

  • Purpose (Will be hidden in the form):
    • Accounting code: test
    • Payments are tax deductible: True (Checked)

Configure fields

  • Configure default field: Amount
    • Input type: Radio
    • Save as: Amount
    • Options: 50, 100 and 150 
    • Reference: amount
  • Add another field: Phone Number
    • Input type: Number
    • Save as: Phone
    • Reference: phone
  • Add another field: Select Payment Method
    • Input type: Radio
    • Save as: Payment method type
    • Reference: paymentMethodType
  • Add another field: Payment type
    • Input type: Radio
    • Save as: Payment type
    • Reference: paymentType
    • Attributes
      • Read only: True (Checked)
      • Hide: True (Checked)
  • Add another button: Donate
    • Input type: Button
    • Save as: Custom field
    • Reference: button

Transactional settings

The transactional settings are found in the right column of the FormBuilder. The settings should fulfil:

  • Payment types: Payment
  • Payment method types: Test gateway by SMS

Publish form

Scroll up and select Publish. Once the form is published, you can view the form. It should look like the form in the picture above. Note that purpose and payment type are hidden for the end-user.

Step 3. Test Form

Once the form is published, you can view the form. To test the form:

  1. Select an amount
  2. Fill out a phone number (valid for testing)
  3. Click Donate
  4. Select link: Open Payment Session (see image below)
  5. Select an action: Charge, Reject or Fail
    1. Option: Abandon the session. The result is a DataSet with result Not completed.
Important: The action Fail is only available for the Payment Method for testing. Never configure the Payment Method for testing in forms that are available to end-users.

The payment session opens in a new window and looks like this:

mceclip0.png

Once the action is performed, the payment session ends.

Step 4. Receive Webhook

As a result of the form being submitted, the following records are created and stored in OnlineFundraising:

  • Contact
  • Payment - Triggers webhook!
  • Payment method
  • DataSet (points to all of the above records)

The webhook will look something like this:

{ 
"merchantId": "your-organisation",
"webhookEventGuid": "22ce6765-461f-4dd2-a3eb-xxxxxxxxxxxx",
"webhookGuid": "592d0752-dfda-46b8-aeec-xxxxxxxxxxxx",
"webhookAttemptGuid": "029b8cb0-9825-466d-a9db-xxxxxxxxxxxx",
"entityGuid": "b1123c69-cb84-4adf-98cf-xxxxxxxxxxxx",
"entityType": "payment",
"eventType": "created"
}

You have now received your first webhook! Parse the webhook payload and determine how to handle it in your integration.

Example - Check for Contact Duplicates based on Payment State

Often the organisation wishes to execute logic based on the outcome of a Payment. Upon receiving a Payment webhook, it is possible to fetch the Payment via the API and check if certain conditions are met.

GET {{payment-api-uri}}/payment/{guid}

For instance, if a Payment was successfully charged (state), the organisation may wish to ensure the Contact is unique. The Payment object looks something like this (truncated object):

{
  "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "createdTs": "2019-01-01 00:00:00 +0100",
  "paymentType": "single",
  "contactGuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "paymentMethodGuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "paymentSessionGuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "dataSetGuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "amount": 100.0,
  "taxDeductable": true,
  "state": "Charged",
  "chargedTs": "2019-01-01 00:00:00 +0100",
  "...": "...",
  "metaData": {
     "...": "..."
  }
}

Use the contactGuid to fetch the Contact via the API. The resulting Contact object contains all the Contact data which is stored in OnlineFundraising.

GET {{contact-api-uri}}/contact/{guid}

Use the Contact data to check for duplicates in an external system such as a CRM-system. In case you identify one or more duplicates, you may wish to merge the duplicate Contacts in OnlineFundraising (and your CRM-system).

POST {{contact-api-uri}}/contact/{guid}/Merge
Important: Webhooks are dispatched asynchronously, meaning you may not receive the webhooks in the order in which records are created. As a result, in this example, the Contact my not exist at the point in time you are trying to fetch it via the API; Meaning you have to try again a later point in time (a matter of seconds). Make sure that the integration is geared to handle asynchronous webhooks.

Was this article helpful?

0 out of 0 found this helpful