@idonatedev/idonate-sdk v1.0.16

What's this?

Javascript libraries for integrating with iDonate services.

A rough usage example can be found below the Changelog.

Changes

1.0.16

• Adding checkbox recaptcha type, few corrections for error handling
• Added tributeType property

1.0.7

• Add new optional transaction property show_name_to_fundraiser for allowing fundraiser to see the name of the anonymous donor in certain scenarios.

1.0.5

• Further internal refinements around Spreedly tokenization

1.0.4

• Mitigations for Spreedly tokenization outage

1.0.3

• Configure apple_pay_url from environment and sandbox configuration, fixing Apple Pay sandbox issues introduced in 1.0.1

1.0.1

• Compatibility fixes for Apple's onvalidatemerchant changes.

1.0.0

• Support Google Pay (GPay)
• Support UTM data
• Always request unique token from CardConnect
• Expand CreateDonationResult with donation details
  • Schedule
  • Donor
  • Designation
  • Campaign
• Preliminary support for Offsite Transactions (PayPal)

0.0.5-beta.0

Breaking Changes:

• tokenizeCardConnectBankAccount now expects a single ACHAccount object as its parameter and will resolve with the resulting token instead of a response object.
  • ACHAccount expects accountNumber, routingNumber, accountHolderType ("personal" or "business") and accountType ("checking" or "savings"). Before this change, "personal" and "checking" were assumed.
• tokenizeCardConnectBankAccount will throw a ClientError on error. The raw result can still be obtained from the error payload as _rawResult.
• mark createTransaction as deprecated - still supported, but should be replaced with createDonation, taking the same input but capable of returning schedule data and handling schedules that do not result in an immediate transaction.
• createPaymentMethod and createDonation take an additional required option: recaptchaType - for most Organization use cases, the value of recaptchaType should be "organization".

Other Notable Changes:

• support Apple Pay when creating PaymentMethods and purchasing with CardConnect
  • introduce tokenizeCardConnectApplePay method on Client
• implement createDonation - a Donation may result in a Transaction and/or a Schedule. When scheduled for a future time, the Donation result will not contain a Transaction at all. If createTransaction is used in these cases, the entire result will be empty.
• detect and throw ClientErrors in many more cases.
• accept Double The Donation Company IDs directly, as corporateMatchingId (internal mappings are no longer supported)\
• internal support for Spreedly tokenization
• very rough internal support for styling CardConnect tokenizer iframes
• support for all Transaction parameters (tributes, gifts, and more)

0.0.4-alpha.13

• always create a unique token when calling tokenizeCardConnectBankAccount

0.0.4-alpha.12

• update sandbox configuration to prefer boltgw-uat environment.

0.0.4-alpha.2 through 0.0.4-alpha.11

• adjustments for internal applications
• public features diverted to v0.0.5

0.0.4-alpha.1

• rename idonate.client to idonate.Client to fit style guidelines
  • idonate.client compatibility will be maintained until 0.0.6 (or equivalent) is released.
• Implement support for (and default to) using the Production environment for API calls.
• Add an options parameter to the Client constructor, initially with only one option: enableSandboxMode
  • if enableSandboxMode is true, API calls will be made against the Staging environment.
• Add corporateMatchingId to the createTransaction payload.
• Enable support for 'bring-your-own reCAPTCHA', adding the recaptchaToken parameter to createPaymentMethod and createTransaction methods.
  • reCAPTCHA results are valid for two minutes and the same token can be re-used within this timeframe.
• Update example in README to include reCAPTCHA support, trigger with a button instead of on load (example results continue to only show in the console)

0.0.3-alpha.3

• adjust README.

0.0.3-alpha.2

• start really writing this README
• remove organizationId from createTransaction method (determine from client)
• pass customerMeta to backend
• map transactionId in CreateTransactionResult
• Add CardConnect ACH tokenization helper, update demos with ACH features.

Example: Low Level Transaction API, with reCAPTCHA

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>createTransaction demo, with reCaptcha</title>
    <script src="https://www.google.com/recaptcha/api.js" async defer></script>
    <script src="https://unpkg.com/@idonatedev/idonate-sdk@1.0.7"></script>
  </head>
  <body>
    <button type="button" onclick="grecaptcha.execute()">Submit</button>
    <!--
      This reCAPTCHA site key will never report a bot user:
        https://developers.google.com/recaptcha/docs/faq#id-like-to-run-automated-tests-with-recaptcha.-what-should-i-do

      Replace this with your own site key. The corresponding private key must also be configured on your Organization in
      the environment you are targeting.
    -->
    <div
      class="g-recaptcha"
      data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
      data-callback="recaptchaCallback"
      data-size="invisible"
    ></div>
  </body>
  <script>
    // config will usually be supplied statically, at the page level.
    const config = {
      organizationId: '2aa2e362-51aa-483d-bedd-645ae18cc1f3',
      paymentGatewayId: '12344321-e605-429e-b9a9-4516738635db',
      enableSandboxMode: true, // the SDK client will use Staging resources if true
      recaptchaType: 'v2', // 'v2' and 'invisible' recaptcha types are supported.
    };

    // the rest of this information will typically be entered into forms by donors,
    // but is abstracted here for demo purposes.
    const billingContact = {
      firstName: 'Billing',
      lastName: 'Contact',
      email: 'billing.contact@example.com',
    };

    const billingAddress = {
      address1: '123 Place St.',
      city: 'Hometown',
      state: 'TX',
      zip: '76543',
      country: 'US',
    };

    const bankAccountInput = {
      routingNumber: '123456',
      accountNumber: '123456789',
    }
    
    idonateClient = new idonate.Client(config.organizationId, {
      enableSandboxMode: config.enableSandboxMode,
    });

    function recaptchaCallback(recaptchaToken) {
      /**
       * Everything happens after the reCaptcha callback:
       * - tokenize payment details with the payment service
       * - associate that token with a PaymentMethod within iDonate
       * - use the new PaymentMethod to charge a payment and create a new Transaction
       *
       * createPaymentMethod and createTransaction are both secured using reCaptcha.
       *
       * A reCaptcha result is valid for two minutes, the same result can be used in both calls as long as the result
       * remains valid.
       */
      idonateClient
        .tokenizeCardConnectBankAccount({
          routingNumber: bankPaymentInput.routingNumber,
          accountNumber: bankPaymentInput.accountNumber
        })
        .then((tokenResult) => {
          console.log('received tokenResult', tokenResult);

          return idonateClient.createPaymentMethod({
            paymentGatewayId: config.paymentGatewayId,
            paymentMethodType: 'bank_account',
            paymentMethodToken: tokenResult.token,
            recaptchaToken: recaptchaToken,

            contact: billingContact,
            address: billingAddress
          });
        })
        .then((paymentMethodResult) => {
          console.log('received paymentMethodResult: ', paymentMethodResult);

          return idonateClient.createTransaction({
            paymentGatewayId: config.paymentGatewayId,
            paymentMethodId: paymentMethodResult.paymentMethodId,
            recurringFrequency: 'once',

            paymentAmount: 5.0,
            currency: 'USD',

            billingContact: billingContact,
            billingAddress: billingAddress,

            customerMeta: {
              'up to 80 chars': 'up to 800 chars',
              is_demo: true,
            },

            recaptchaToken: recaptchaToken,
            corporateMatchingId: -1
          });
        })
        .then((createTransactionResult) => {
          console.log(
            'received createTransactionResult: ',
            createTransactionResult
          );
        });
    }
  </script>
</html>