Developer APIs

Introduction

We have two different types of APIs, Apex and Rest. What's the difference between the Apex and REST APIs?

REST API

Provides you an HTTP endpoint. Sending your data (which can be CC tokens obtained from Stripe, Transaction data, etc.) and receive a JSON response.

The objects are recorded in Salesforce, and it's your responsibility to process and handle the results on the client side. You can use the REST API in any environment where you can make HTTP calls (website, mobile app, outer space).

Apex API

It is a global Apex class, which you can access in your Salesforce Org or an Experience Cloud. You can initialize Blackthorn | Payments entities (like Stripe Customer, Payment Methods and Transactions) and do actions (like send data to Stripe, update, capture, authorize, delete, etc).You can integrate these actions into your custom Apex code, and it is your responsibility to handle the customer data.

Use Cases

• Apex API: Visualforce website form
• Apex API: Salesforce Community
• Apex API: Your Salesforce internal app.
• REST API: Non-Visualforce website form
• REST API: Non-Salesforce custom portal
• REST API: Mobile (Native or Hybrid) Application

Business Applications

Payment Form

Create and validate a Payment Method (credit/debit/ACH), create and capture (charge) for a Transaction, display success and failure messages to the user.

Payment Method Management from an Experience Cloud or Custom Portal

Display "cards on file'"(or ACH accounts), allow users to create new cards, update cards, and delete cards.

Historical and Future Transactions

Display all prior or future scheduled Transactions related to the user.

Portal or Experience Cloud

Because you already know who the authenticated user is (even from a single payment), you can create (or update) an Account and/or Contact, create or update an Opportunity, and manage the payment process.

View our FAQ for additional information.

Credit Card Verification

REST API

• Here's how you can tokenize a card with Stripe's javascript file (Stripe.js).See https://stripe.com/docs/js
• You can use Stripe.js, which returns an error if the card is bad, and can be processed on the front-end.See https://stripe.com/docs/custom-form and https://stripe.com/docs/stripe.js?

Apex API

• The class returns the credit card status after committing it to Stripe. Data is pushed to the Apex back-end, which returns the result to the back-end, then you display it to the user.

Test credit card calls

• Visit https://stripe.com/docs/testing for test codes. Make sure you have your Payment Gateway connected in Test Mode. You can do this by creating a Payment Gateway in test mode. Once you authenticate, your Payment Gateway will accept test cards (and only test cards).

Sample test code for unit tests that mock HTTP callouts

The below code example is for Stripe payment gateway. It includes valid Stripe JSON responses at the top.

Unit Tests with our Web Services

You'll likely run into issues with unit tests. We're working on a more comprehensive method to solution this, but for now, please use:

bt_stripe__Stripe_Settings__c settings = bt_stripe__Stripe_Settings__c.getOrgDefaults();
settings.bt_stripe__Disable_All_Triggers__c = true;
upsert settings;

This will stop any callouts being made on Payment Method insertion and your unit tests will go through.

Creating Triggers with Payments objects

Blackthorn | Payments does HTTP callouts to the Stripe API endpoint.

A callout can be started in several ways, including:

• Button pressed on the standard layout
• Lightning Virtual Terminal
• Batch processing (daily automatic payment collection)
• REST API (incoming calls)
• Invocable method started a Transaction processing
• APEX API

This has several consequences:

• Before a callout DML operations are not allowed
• Before callouts, no asynchronous apex is allowed (batch, future)
• Before callouts, no emails are allowed
• These HTTP callouts count towards the HTTP callout limits (callout numbers and cumulative timeout)

Best Practices

Apex API

Payments Apex API takes care of the DML operations; all you need to do is to run a commit() method when you finished your business with the provided Customer, PM and Transaction objects. However, keep in mind that Apex API makes HTTP callouts, so the limitations listed above apply (no DML statements, asynchronous Apex...) before the commit() method.

Triggers

Your triggers can interact with Blackthorn | Payments app objects in two ways.

1. Listening to Payments Objects
You can bundle your triggers to insert / update / delete operations on Payments objects. Some of the most common use cases are:

• Bundling a trigger to an insert of a Payment Method / Customer
  Always look for the Stripe Id fields on the objects. A Customer / PM is inserted fully when there is a Stripe Id in the database. When this Id is updated, there was a HTTP callout before; so keep in mind that you are in this context.

• Bundling a trigger to a Transaction
  When inserting an Open status Transaction, you are safe, because there are no callouts. Callouts happen when a Transaction is processed. When it is successfully processed, the Transaction Status and Payment Status are changed and a Transaction Id is added. Before this, an HTTP callout happened.

There is a use case when a user captures a Transaction using the "Capture" button, it fires a trigger which starts the processing asynchronously (in future). This means that you should not start other future operations from triggers bundled to Transaction status / id changes; or if you are doing so, always check your context, and start a future method only if you are in synchronous context.

2. Your triggers start Transaction processing

If you want to interact with Payments objects, always use the provided APEX API. It cannot process Transactions in a trigger context because HTTP callouts are not allowed.Move all your Transaction processing operations to future context.

• REST API
  Incoming REST API calls can create or process Payments objects. If you are using REST API and bundling triggers to Payments objects, keep in mind that the REST API user has other access rights than a regular Salesforce user.

Troubleshooting/FAQ

If you run into any errors with our REST API, open up Developer Tools in your browser, and recreate your scenario. There is an Error Message field under response that should provide insight into your issue.

If you a received an error or have a question, please view our API Troubleshooting/FAQ.

If you still have API questions, please contact Blackthorn Support. We're happy to help!