Payments API Integration Configuration

In order to use any of Keap’s payment processors the API developer will be required to use Keap’s hosted Payment component, which is provided through a Javascript bundle.

STEP 1: Retrieve a session key to render the component

The component will require a session-based key which to render the payment fields on page. That token may be obtained via backend REST API call. 

Example in cURL 

curl --location 'https://api.infusionsoft.com/crm/rest/v2/paymentMethodConfigs' \
  --header 'Authorization: Bearer API_KEY_HERE' \ 
  --header 'Content-Type: application/json' \ 
  --data '{ "contact_id": CONTACT_ID_HERE }'

On success, a session key will be returned in the response. 

Example response:

{
"session_key":"eyJjb250YWN0X2lkIjoiMzciR1Z1WVc1MElqb2ljR1Z1WjJ4cGJTSjkuSFNUeDh0OXZTaUlhSFZSNDNvbnVwU29Cc0hmWUZYZlZDb1dZT2dIOFhwOCJ9" 
}

Note: Session keys expire in one hour. Perform Step 1 again to retrieve a new session key

STEP 2: Embed the payment component

Load the Keap payment JavaScript bundle onto your page so that you can render the payment component.

<script src="https://payments.keap.page/lib/payment-method-embed.js"></script>

To render, add the code-snippet below to your web page where you want the component to appear. Use the previously-created session_key as attribute for ‘key’:

<keap-payment-method data-key="YOUR_SESSION_KEY">
</keap-payment-method>

STEP 3: Setup submission of payment method details

Supply any component of your choosing on your page (button, link, etc.) in order to trigger a submisson of the data that was entered in the payment component. 

Example for a button:

<button onclick="submitKeapForm()"> 
Submit  
</button>

Trigger the submission via the provided JS bundle’s submit() function:

function submitKeapForm() { 
   document.querySelector(`keap-payment-method[data-key="${YOUR_SESSION_KEY}"]`).submit(); 
}

STEP 4: Add an event listener for responses

Add an event listener to obtain the paymentMethodId from the response after submission:

window.addEventListener('message', ({ data }) => { 
  if (data.error) {
       // Handle error (error is an object with { message, code })
  } else if (data.success) {  
    // Handle success  
  } else {  
    // Handle error  
  }  
});

Example response:

{ 
    paymentMethodId: 1719,   
    creditCardId: 1232, 
    success: true  
}


A ‘success’ event by the listener indicates the payment method was saved successfully. The  response will contain paymentMethodId and creditCardId in the payload, which can be used for making subsequent calls via Keap’s API to charge payments.

FAQ  

1. Why Do I Need to Create a Contact First?

  • Question: Why is a contact required before processing a payment?
  • Scenario: Users encounter errors when processing payments without a contact ID.
  • Answer: A contact ID securely links payment details to a specific user, ensuring compliance and preventing misattribution. Use the POST /contacts endpoint to create a contact before adding cards. Then use the payment method id from the result of the JS package to process payments as usual.
  • Recommendation: Call POST /contacts to generate a contact ID and include it in payment method requests.
  • Example: Create a contact with POST /contacts { “email”: “carson.bond@gmail.com” } to get contact ID 12, then use the JS package to create the payment method for the contact ID 12 for the default processor set in the app, to get credit Card ID 10, then use both the results in POST /payments { “contact_id”: “12”, “creditCardId”:”10” } to process the payment.

2. How Can I Avoid Duplicate Contacts?

  • Question: How do I prevent duplicate contacts during checkout?
  • Scenario: On the checkout form, a user enters a misspelled email (e.g., John.Doz@gmail.com) and proceeds to the credit card form. They correct it to John.Doe@gmail.com, but the system creates a new contact for each email.
  • Answer: Before creating a contact, search for existing ones using GET /contacts with email or phone number. Update existing contacts with PATCH /contacts/{contact_id} or delete temporary contacts with DELETE /contacts/{contact_id}.
  • Recommendations:
    • Search First: Use GET /contacts?email=<email> to check for existing contacts.
    • Create Contact (Only when needing to create): Create via POST /contacts
    • Update Contact: Update via PATCH /contacts/{contact_id} if a contact exists.
    • Delete Temporary Contacts: Remove incorrect contacts with DELETE /contacts/{contact_id}.
  • Examples:
    • Brand New User:
      • User enters carson.bond@gmail.com, creating contact ID 12.
      • User corrects to carson.love@gmail.com.
      • Update with PATCH /contacts/12 { “email”: “carson.love@gmail.com” } to correct contact ID 12.
    • Existing User:
      • System has carson.love@gmail.com as contact ID 10.
      • User enters carson.bond@gmail.com, creating contact ID 12.
      • User corrects to carson.love@gmail.com.
      • Search with GET /contacts?email=carson.love@gmail.com to find ID 10.
      • Use ID 10 for future calls and delete temporary contact with DELETE /contacts/12.

3. What Happens If a Contact Is Created with a Bad Email?

  • Question: How do I handle contacts created with incorrect emails?
  • Scenario: A user enters carson.bond@gmail.com, creating a contact, then corrects it to carson.love@gmail.com.
  • Answer: Perform a lookup for the correct email with GET /contacts. If a match exists, use its ID and delete the temporary contact. If no match, update the existing contact’s email with PATCH /contacts/{contact_id}.
  • Recommendation: Implement a look-up with GET /contacts and use PATCH /contacts/{contact_id} or DELETE /contacts/{contact_id} as needed.
  • Example: For a bad email carson.bond@gmail.com (ID 12), lookup GET /contacts?email=carson.love@gmail.com. If ID 10 is found, use it and call DELETE /contacts/12 to remove the temporary contact.

4. Can I Choose a Payment Processor?

  • Question: Can customers select their preferred payment processor?
  • Answer: The JS Package uses the app’s default processor (e.g., Stripe) with no user selection. The v2 POST /setDefaultMerchant endpoint allows setting processors like Stripe or PayPal as the app default processor. Check the v2 rest API guide for details.
  • Recommendation: inform users that processor selection in JS package is unavailable. Use POST /setDefaultMerchant to configure the default processor for the app.
  • Example: In v2, set up the default processor with POST /setDefaultMerchant  merchant ID 2 and start using JS Package.

5. What Is the Primary Goal of the v2 /paymentMethodConfigs Endpoint?

  • Question: What does the v2 /paymentMethodConfigs endpoint do?
  • Answer: It allows developer partners to get their JWT (session Key) which authorizes them to use the JS package. This secures the JS package and the customer PII data.
  • Example: Get the session Key with POST /paymentMethodConfigs and use JS Package to create a payment method for the specific contact and the default processor set for the app.

Additional Resources

API Documentation: Find all endpoints (e.g., POST /contacts, PATCH /contacts/{contact_id}, GET /contacts, POST /payments) at https://developer.keap.com/docs/restv2/