Improve your Skyline experience
You're using a browser that skyline.benevity.org does not support. Try Chrome, Edge, Safari or Firefox for a better experience.

# Make a credit card donation

Benevity utilizes BlueSnap (opens new window) as our payment gateway service in order to process credit card transactions. There are three main stages of creating a card donation:

  1. Get Payment Configuration - here we will obtain a payment token and required identifiers for processing the payment with the payment gateway.
  2. Associate Card Data to the Token - in this step, the user's card data is associated to the payment token.
  3. Capture Payment and Record Donation - finally, we will charge the donor's card and record the donation.

Let's look at each of these stages below in more detail.

# Get Payment Configuration Details

The following attributes must be sent to configure the payment details:

  • adapter - The adapter through which the request will be routed, Always Adapter.General
  • causeId - The ID of the cause you wish to donate to
  • causeType - The type of cause you are donating to
    • can be CAUSE, PROJECT or PORTFOLIO
  • companyCode - The Company ID supplied by Benevity
  • currencyCode - The currency code you are donating in (see our Supported Currencies)

# Sample request:

# Sample response:

{
  "paymentType": "CREDITCARD",
  "companyCode": "test_company_2ZX3D205V6",
  "adapter": "Adapter.General",
  "processor": "BLUESNAP",
  "merchantAccountId": "test_merchant_1M0742D4DP",
  "requiredBillingDetails": {
    "default": {
      "optional": [
        "billingProvince",
        "billingPostalCode"
      ],
      "required": [
        "billingFullName",
        "billingEmail",
        "billingAddress",
        "billingCity",
        "billingCountry"
      ]
    },
    "124": {
      "required": [
        "billingFullName",
        "billingEmail",
        "billingAddress",
        "billingCity",
        "billingProvince",
        "billingPostalCode",
        "billingCountry"
      ]
    },
    "840": {
      "required": [
        "billingFullName",
        "billingEmail",
        "billingAddress",
        "billingCity",
        "billingProvince",
        "billingPostalCode",
        "billingCountry"
      ]
    }
  },
  "token": "eyJhbGciOiJIUzI1NiJ9..."
}

The response above contains payment configuration details we will use to capture card information, charge the card and then record the donation. Below is an explanation of some of these key attributes:

  • merchantAccountId - This is the Id of the merchant account to process under at BlueSnap.
  • token - This is the payment token needed to process the Credit Card on BlueSnap.
  • requiredBillingDetails - You can use this to help determine what fields are required, based on the users billing country.

# Associate Donor Card Details

In this step, we need to associate the donor's card information to the payment token obtained in the previous call. In order to keep PCI compliance requirements to the minimal SAQ-A level, we have the option of utilizing BlueSnap's Hosted Payment Fields (opens new window).

Hosted Payment Fields (opens new window) are iframes that replace sensitive input fields in your user interface, providing a secure way to capture and transmit card data information directly to the payment gateway service. The linked guide above contains a walk-through of how to set up a form on your interface along with some sample forms (opens new window).

To test the flow, you can find a list of test card numbers here (opens new window).

3-D Secure

If you are processing donations to any European Economic Area or United Kingdom cause, you'll need to implement the 3-D Secure check through BlueSnaps HPF in order to validate that the card passes all 3DS checks. To do this, please follow the 3-D Secure for API (opens new window) documentation on BlueSnaps site.

Please see the 3-D Secure (3DS) reference page for more information on what 3-D Secure is.

It's important to note that we are not using the BlueSnap method to capture and process the transaction on Step 5 of the BlueSnap HPF. Where it indicates // submit the form this is where you will make a call to your own backend endpoint in order to make a server to server call when doing the Capture Payment and Record Donation

# Capture Payment and Record Donation

We are now at the final step: capturing payment from the donor and recording the donation. To accomplish both of these tasks, we will call the /payments/card/transactions endpoint.

The following attributes are dynamic pending on the donation and required unless otherwise stated. All others should remain static.

  • companyCode: The ID provided to you by Benevity (not to be mistaken with the Client ID for authentication)
  • total: The total amount being donated to all causes in cents/credits (i.e. 100 = $1.00)
  • currencyCode: The same currency code used in Get Payment Configuration
  • giftAid: (Optional Attribute): See more information about gift aid below in the Gift Aid section
  • paymentConfig:
  • cardHolder: The donor's billing information for processing of the Credit Card and receipting
  • referenceNumber: A unique alphanumeric reference number that can be used to track the donation and connect to any logs and processes on your end.
  • description (Optional Attribute): A description of the donation
  • softDescriptor (Optional Attribute): A description to send to the CC processor that will display on the Credit Card statement
  • payerBusinessName (Optional Attribute): Your company name or name you are transacting under
  • purchaseItems:
    • itemTotalAmountCents: Total amount in cents/credits being allocated to allocate to the specified cause (must equal the total amount specified above)
    • receiptNote (Optional Attribute): An optional note that can be placed on the receipt
    • sharing (Optional Attribute): Default is false. Determines if the donating users information can be shared with the cause. If true, the individual donation amount, donor name, email and address details will be shared with the cause. Otherwise, the shared details are based on the "Charity Info Sharing" preferences set in the platform.
    • sendReceipt (Optional Attribute): Default is true. Determines if Benevity sends out the receipt email to the user. Note: Benevity recommends you use the API to download the receipt, and send in your own branded email.
    • allocations:
      • causeCode: The ID of the cause, project or portfolio you are donating to
      • amountCents: The amount you are donating to this specific cause (total amount for all causes listed must equal total previously specified)
    • comments (Optional Attribute):
      • cause: The cause ID you are associating the comment to
      • commenter: The name of the person or organization who made the comment
      • comment: The comment being sent to the cause
    • tags (Optional Attribute): Any tagging items that you want to use to report on within the Benevity Reporting tool.

NOTE: The required donor information fields vary by foundation partner and are provided above during the Get Payment Configuration step. For example, donations to a Canadian (124) and United States (840) cause require a donor's full name, address and email, whereas a donation to any other cause does not require a postal/zip code or a province/state.

Any other information not listed above as a dynamic field is a static field and will always be sent as is:

  • paymentConfig
    • processor: BLUESNAP
  • adapter: Adapter.General
  • purchaseItems
    • Quantity: 1
    • name: donation
    • action: COMPANYDONATEFORUSER

# Sample request:

# Sample response:

{
    "transactionId": "5KWB476SDV",
    "creditCardId": "5E8NRJGKDU",
    "processorTransactionId": "1071080817",
    "referenceNumber": "test_random_string_3423424",
    "transactionType": "CREDITCARD",
    "softDescriptor": "Benevity",
    "description": "$1.00 Donation to Test",
    "created": 1667859354133,
    "received": 1667859351592,
    "processed": 1667859354131,
    "backend": 1667859354307,
    "processor": "BLUESNAP",
    "payerBusinessName": "My Company Name",
    "purchaseItems": [
        {
            "name": "donation",
            "action": "COMPANYDONATEFORUSER",
            "quantity": 1,
            "itemTotalAmountCents": 100,
            "matchCap": 0,
            "matchAmount": 0,
            "receiptNote": "Note",
            "sharing": false,
            "created": 1667859354136,
            "sendReceipt": false,
            "allocations": [
                {
                    "causeCode": "cause.840-275219467",
                    "amountCents": 100
                }
            ],
            "comments": [
                {
                    "cause": "cause.840-275219467",
                    "commenter": "Test User",
                    "comment": "Goodness matters"
                }
            ],
            "tags": [
                "calgary_store",
                "client_specific_tag"
            ]
        }
    ],
    "merchantAccountId": "test_merchant_1M0742D4DP",
    "amount": {
        "totalAmountCents": 100,
        "currencyCode": "USD"
    },
    "refunds": [],
    "subscriptionTemplate": false,
    "adapter": "Adapter.General",
    "backendTransactionId": "2DXZRFSYP1",
    "backendReceiptId": "21AB9BXULZ",
    "backendReceiptSent": 1667859354772,
    "transactionFee": 3,
    "refunded": 0,
    "companyCode": "test_company_2ZX3D205V6",
    "recurring": false
}

NOTE: The above example is for a guest/anonymous donation that does not require a donor to have a user account on the Benevity platform. The same flow applies to registered users, with some slight adjustments to the attributes that are passed.

The attribute for a registered user is "userAccessId": "". The user access ID is created and obtained using our SOAP XML API endpoints.

If registered users is a requirement for your project, please reach out to api-support@benevity.com, and we can assist.

# Gift Aid

For further information on what Gift Aid is, please see the reference material here.

To enable Gift Aid for a credit card donation you will need to supply the attribute "giftAid": true in the root of the /payments/card/transactions request. If you set the attribute to true, and the conditions are not met, Gift Aid will not be applied to the donation.

# 🚀 ☀️ ⭐️ Congratulations! ⭐️ ☀️ 🚀

Amazing! You just helped someone change the world.

← Get Donation Receipt →