SDK
      Back to home
      1. Resources and Documentation
      2. SDK

      Getting Started with the iDonate SDK

      Square one of the road to a working SDK implementation.

      The iDonate SDK gives advanced users even more control over the way iDonate interacts with users.

      This article is a primer for users that are new to the iDonate SDK. Knowledge of HTML and JavaScript is recommended.

      View on NPM

      Configure HTML Head Section

      To begin, create a blank HTML document.

      Once created, configure the <head> as shown. This will link both the iDonate SDK and ReCaptcha's API to your document.

      <head>
           <!-- Script: ReCaptcha -->
           <script src="https://www.google.com/recaptcha/api.js" async defer></script>

           <!-- Script: iDonate -->
           <script src="https://unpkg.com/@idonatedev/idonate-sdk@1.0.0"></script>
      </head>

      Body Section

      Add a <button> element and set its onclick to "grecaptcha.execute()".

      Next, add the ReCaptcha by creating a <div> and setting the following parameters:

      • class: "g-recaptcha"
      • data-sitekey: This ReCaptcha data-sitekey will never report a bot user. Instead, use your own data-sitekey. The corresponding private key must also be configured on your Organization in the environment you are targeting.
      • data-callback: "recaptchaCallback", the function that will be defined further along in the document.
      • data-size: "invisible"
      <body>
           <!--Button that you press after completing ReCaptcha-->
           <button type="button" onclick="grecaptcha.execute()">Submit</button>

           <!--ReCaptcha-->
           <div 
              class="g-recaptcha" 
              data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI" 
              data-callback="recaptchaCallback" 
              data-size="invisible"></div>
      </body>

      Set Initial Configuration

      To begin using the SDK in earnest, we head to our <script> section and create our config as shown. We will use this object as our initial data at runtime.

      • organizationId: Your iDonate Organization ID.
      • paymentGatewayId: Your payment gateway ID.
      • spreedlyEnvironmentKey: Your Spreedly environment key.  This value is organization-agnostic, so the same key is used for each implementation:
        • Staging: 

          KCE4DaaycL92NvslhfVUNbWgioC

        • Production: 

          5DeiEKz3bAzl2urQyBTc9tLKoRv

      • enableSandboxMode: If true, the SDK client will use Staging resources.

      Important: To obtain your paymentGatewayId and spreedlyEnvironmentKey, contact your iDonate account manager.

      const config = {
           organizationId:'2aa2e362-51aa-483d-bedd-645ae18cc1f3',
           paymentGatewayId:'12344321-e605-429e-b9a9-4516738635db',
           spreedlyEnvironmentKey: 'KCE4DaaycL92NvslhfVUNbWgioC',
           enableSandboxMode:true,
           recaptchaType:'organization'
      };

      Optional Configuration

      For demonstration purposes, we are setting the information that is usually entered by the user. In this case, we'll create data for our family friend, Old Bill from Palo Alto.

      Note that at this time, nothing happens with the data. It's set aside for later use.

      const billingContact = {
           firstName:'old',
           lastName:'bill',
           email:'ya@hoo.com'
      };

      const billingAddress = {
           address1:'1 Fakery Way',
           city:'Palo Alto',
           state:'CA',
           zip:'90210',
           country:'US'
      };

      const bankAccountInput = {
           routingNumber:'#', //user-populated
           accountNumber:'#' //user-populated
      };

      Create the iDonate Client

      Create a new iDonate Client. Note that we are referring to parameters contained in config to initialize our client.

      idonateClient = new idonate.Client(config.organizationId, {
          enableSandboxMode:config.enableSandboxMode});

      The Callback Function

      Here is where we begin "the good stuff." Shown here is the basic structure of how a payment is completed using the iDonate SDK.

      You may recall that our function name, recaptchaCallback, was defined at the beginning of the document as the callback value for our ReCaptcha <div> element. This is where our parameter, recaptchaToken comes from.

      The process goes:

      • Using data from ReCaptcha, tokenize the bank account information.
      • Using that tokenized information, create a payment method.
      • Using that payment method, create a transaction.
      function recaptchaCallback(recaptchaToken){
           idonateClient.tokenizeCardConnectBankAccount({
                //Create Token (tokenResult)
           }).then((tokenResult)=>{
                //Create Payment Method (paymentMethodResult)
           }).then((paymentMethodResult)=>{
                //Create Transaction (createTransactionResult)
           }).then((createTransactionResult)=>{
                //Transaction Complete
           });
      }

      Let's go into the details of each step.

      Create Token

      First, we create our token using bank data provided by the user, passing it to idonateClient.tokenizeCardConnectBankAccount() as a parameter object.

      The return of the function idonateClient.tokenizeCardConnectBankAccount() using our parameters is then passed as tokenResult to the next step in the process.

      idonateClient.tokenizeCardConnectBankAccount({
           routingNumber: bankPaymentInput.routingNumber,
           accountNumber: bankPaymentInput.accountNumber
      }).then((tokenResult) => {}

      Create Payment Method

      In this section, we'll create a payment method to pass to the next step. We will do so using idonateClient.createPaymentMethod(), using an object as the parameter. The object is defined as follows:

      • paymentGatewayId: config.paymentGateWayId
      • paymentMethodType: 'bank_account'
      • paymentMethodToken: tokenResult.token
      • recaptchaToken: recaptchaToken
      • contact: billingContact
      • address: billingAddress

      Note that we are referring to data we set up before, such as tokenResult, recaptchaToken, and billingContact.

      We will use the return value of idonateClient.createPaymentMethod() using our object as a parameter to pass to the next step as paymentMethodResult.

      }).then((tokenResult) => {
           return idonateClient.createPaymentMethod({
                paymentGatewayId: config.paymentGatewayId,
                paymentMethodType: 'bank_account',
                paymentMethodToken: tokenResult.token,
                recaptchaToken: recaptchaToken,
                contact: billingContact,
                address: billingAddress
           });
      }).then((paymentMethodResult) => {}

      Create Transaction

      The final step looks a lot like the previous one, in that we use a return value of a function to pass to the next step.

      We pass an object to idonateClient.createTransaction():

      • paymentGatewayId: config.paymentGatewayId
      • paymentMethodId: paymentMethodResult.paymentMethodId
      • recurringFrequency: 'once'
      • paymentAmount: 5.0 (A custom donation amount of 5.00)
      • currency: 'USD' (If this were CAD, the donation would be for 5.00 CAD)
      • billingContact: billingContact
      • billingAddress: billingAddress
      • recaptchaToken: recaptchaToken
      • corporateMatchingId: -1 (This would be your organization's corporate matching ID)

      At this point the transaction is complete. We pass the result of the function to the next step as createTransactionResult for the SDK user to see.

      }).then((paymentMethodResult) => {
           return idonateClient.createTransaction({
                paymentGatewayId: config.paymentGatewayId,
                paymentMethodId: paymentMethodResult.paymentMethodId,
                recurringFrequency: 'once',
                paymentAmount: 5.0,
                currency: 'USD',
                billingContact: billingContact,
                billingAddress: billingAddress,
                recaptchaToken: recaptchaToken,
                corporateMatchingId: -1
           });
      }).then((createTransactionResult) => {}

      Transaction Complete

      Now, we simply inform the SDK user of the result of the overall function with a handy console.log() statement containing createTransactionResult.

      }).then((createTransactionResult) => {
           console.log("received createTransactionResult: ", createTransactionResult);
      });

      Bringing it All Together

      Wonder what it all looks like when all these parts come together? View the Readme on NPM or take a look here.

      <!DOCTYPE html>
      <html lang="en">

           <head>
                <script src="https://www.google.com/recaptcha/api.js" async defer></script>
                <script src="https://unpkg.com/@idonatedev/idonate-sdk@1.0.0"></script>
           </head>

           <body>
                <button type="button" onclick="grecaptcha.execute()">Submit</button>
                <div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI" data-callback="recaptchaCallback" data-size="invisible"></div>
           </body>
           <script>
                const config = {
                     organizationId:'2aa2e362-51aa-483d-bedd-645ae18cc1f3', //your iDonate organization ID
                     paymentGatewayId:'12344321-e605-429e-b9a9-4516738635db', //your payment gateway id, e.g. cardconnect
                     enableSandboxMode:true, // the SDK client will use Staging resources if true
                     recaptchaType:'v2' //recaptcha type
                };

                const billingContact = {
                     firstName:'old',
                     lastName:'bill',
                     email:'ya@hoo.com'
                };

                const billingAddress = {
                     address1:'1 Fakery Way',
                     city:'Palo Alto',
                     state:'CA',
                     zip:'90210',
                     country:'US'
                };

                const bankAccountInput = {
                     routingNumber:'#', //user-populated
                     accountNumber:'#' //user-populated
                };

                idonateClient = new idonate.Client(config.organizationId, {enableSandboxMode:config.enableSandboxMode});

                function recaptchaCallback(recaptchaToken){
                     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,
                                recaptchaToken: recaptchaToken,
                                corporateMatchingId: -1
                           });
                     }).then((createTransactionResult) => { //createTransactionResult is the return of idonateClient.createTransaction({});
                           console.log("received createTransactionResult: ", createTransactionResult);
                     });
                }
           </script>
      </html>                       

      A Working Example

      A helpful resource when building your implementation: A working implementation of the iDonate SDK, with exposed source code.

      Child Hunger Fund - Example Form