Transactions

New Feature Alert!

Stripe Payouts will now automatically relate to the Charges and Transfers included within them. This helps you reconcile which Charges are included in which bank transfers you receive. Click here for more information.

Introduction

The Transaction object is used to authorize, capture, and refund charges, as well as serve other functions (see below). There are four record types on the Transaction object:

  • Charge (formerly called "Stripe"): Charging a payment method, refunding a charge, or logging a "Non-Gateway" Transaction (monies that transferred outside of Stripe but you want to keep track of in Salesforce, such as a wire transfer).

  • Payouts: Auto-created by Stripe webhooks for stand-alone accounts (ordinary/common accounts). These can be manually created and processed if you're using Stripe Connect to initiate the "paying out" of funds from a Stripe account to an External Account (bank account or debit card).

  • Transfer (Stripe Connect only): Moves funds between Stripe accounts.

  • Adjustment: This Transaction type is used by Stripe as a way for Stripe to send money to your account or debit your account (such as with a dispute's fee).

Transactions can relate to any object defined in the Blackthorn | Payments Setup Wizard. A lookup relationship is automatically created between the Transaction object and the parent object(s) you select.

Transactions can also process in any currency that Stripe supports. Each currency has a record in Custom Metadata for the Transaction to reference based on the value from the Currency ISO field.


Process Flow

With all four record types, the most important part of Transactions is understanding the process flow. There are two fields on this object that provide the most information, Transaction Status and Payment Status. These fields have picklist options (the majority of them are set automatically) that provide insight into what your Transactions have done.

Transaction Status

  • Open (set automatically): A Transaction that has not yet been processed or authorized.

  • On-Hold (set manually): A Transaction that's set to auto-process but is on hold for whatever reason. This will remove the Transaction from the daily auto capture job. Change the status back to "Open" when it should automatically process.
    Manually add the picklist value to the Transaction Status field in the Charge Record Type.

  • Process (set automatically): This is a technical field and you'll only see it after capturing or authorizing a Transaction. Once you refresh your page, it will automatically change to the next status.

  • Pending (set automatically): This status is only shown when a Transaction has a related ACH Payment Method and is in the 3-4 day waiting period or if your platform's account/connected account balance is sufficiently negative, then refund transaction is set to a status of pending.
    ACH Transactions can take up to four days before reaching a "Completed" or "Failed" status.

  • Needs Review (set automatically): This status is shown when an error within Salesforce impacted the Transaction from completing successfully.
    View the Error Message field or Blackthorn Logs for additional information. The Transaction may need to be set back to "Open" and recaptured if it was not sent to Stripe.

  • Completed (set automatically): When the Transaction has fully completed. Reference the Payment Status as the result of the completed Transaction.

  • Canceled (set manually): If the Transaction was created by mistake or needs to be canceled for any reason while still in the "Open" status, it can be manually switched to "Canceled".
    Transactions with a status other than "Open" cannot be switched to "Canceled" unless you disable the Transaction validations in Custom Settings.

  • Failed (set automatically): The Transaction tried to complete but failed. The reason for why it failed to complete may be located in the To Fix field or a Stripe error message populated.

Payment Status

The Payment Status field is automatically populated when the Transaction Status = "Completed".

  • Authorized: This status means the amount of the Transaction has been guaranteed by the card issuer and the amount is held for up to 7 days unless it's released early.

  • Captured: The full amount was captured and the funds were taken out from the associated Payment Method.

  • Partially Captured: The original amount was authorized, but then a lesser amount was "Captured".

  • Refunded: The original amount was fully refunded back to the associated Payment Method.

  • Partially Refunded: Part of the original amount was refunded back to the associated Payment Method.

  • Disputed: This Transaction was "Captured" but is now "Disputed" by your customer and will stay at this status until the Dispute has been won or lost. See more on Disputes.
    The Transaction will automatically update to this status if webhooks are enabled.

  • Uncaptured: If an "Authorized" Transaction has not been "Captured" in 7 days or refunded, the Transaction will automatically update to this status if webhooks are enabled._


Charge Transaction Record Type

When creating a charge Transaction record, there are several fields that automatically update:

  • Retained Revenue Amount: When a Transaction has been successfully completed, this field's amount is the same as the Transaction amount. If any refunds are made against this Transaction, the Retained Revenue Amount will show the remaining amount.

  • Transaction Type: "Normal" is the default value, but if there is a full refund or a negative balance, this type will automatically update to "Refund".

  • PayLink: If you have purchased this paid add-on, this is the link you can send out to customers for capturing the payment. For additional information, click here.

  • To Fix: This field automatically displays a message about the Transaction if it was not captured correctly. See the below table for more information.

Criteria
To Fix (Output)

Auto-Capture is checked and Due date and Date To Process is blank

If Auto-Process is checked, a Due Date or Date to Process is needed to automatically capture this transaction.

Invalid Payment Method is checked

The related Payment Method is not valid to capture this transaction.

Auto Capture is checked and Payment Method is blank and Record Type is Charge

If Auto-Process is checked, a Payment Method is needed to automatically capture this transaction.

Auto Capture is checked and Connected Account is blank and Record Type is Transfer

If Auto-Process is checked, a Connected Account is needed to automatically process this transaction.

Auto Capture is checked and Connected Account is blank and Payout Method is blank and Record Type is Payout

If Auto-Process is checked, a Connected Account/Payment Method is needed to automatically process this transaction.

  • Payment Gateway: Set automatically under a few scenarios. 1) If blank and a Payment Method is related, the Payment Gateway will automatically set to the value of the Payment Method's Payment Gateway after Transaction processing. 2) If blank and a PayLink is sent to your customer, the Payment Gateway will automatically set after the Transaction is Completed to your org's default Payment Gateway. Alternatively, you can set the value of the Payment Gateway prior to processing (if there is no related Payment Method) to 'tell' PayLink which Payment Gateway to process through.

  • Contact and Account: If both of these fields are null and the related Payment Method's Account and Contact have a value, the Transaction's Account and Contact will be updated with those values.

  • Payment Method Billing Email: Will be set automatically from the related Payment Method's Email when a Payment Method is added to the record and saved.

  • Original Transaction (If Refund): If this is a refund type Transaction, this field will automatically populate a lookup to the original Transaction.

  • Original Transaction (If Reattempt): If this is the reattempted Transaction, this field will automatically populate a lookup to the original "Failed" Transaction.

  • Available On: This field provides the date that this amount is available in your Stripe account.

  • Balance Status: This field lets you know if the amount is part of your Pending or Available balance in Stripe.

Processing Transactions

Below are instructions for processing each type of Transaction

Authorized Transaction

  • Navigate to the Transactions object.

Lightning: Click on the App Launcher | Under "All Items" | Click on Transactions.

Classic: Click on "All Tabs" ("+" icon in the top right) | Click on Transactions.

  • Click "New".

  • Select "Charge" Record Type then "Next".

  • Required Fields:

Amount: The Transaction amount.

Currency ISO: The currency to process this Transaction in.

Payment Method: The Payment Method used to process this Transaction.
The Payment Method must be valid to authorize a Transaction.

These are the only fields needed to successfully authorize a Transaction.

  • Click "Save".

  • Click the "Authorize" button.

Lightning: Click the down arrow (top right corner) | Click "Authorize".

Classic: Click the "Authorize" button at the top.

If the Transaction was successful, the Transaction Status will update to "Completed" and Payment Status will update to "Authorized".

If the Transaction is not captured within 7 days, the Payment Status will update to "Uncaptured" when webhooks is enabled.
The Transaction can no longer be captured and you will need to clone this Transaction or create a new one.

If you'd like to capture or partially capture the amount of the authorized Transaction, click the Capture button to charge the full amount or update the amount to a lesser amount then click Capture (see below for more information).

Captured Transaction

  • Navigate to the Transactions object.

Lightning: Click on the App Launcher | Under "All Items" | Click on Transactions.

Classic: Click on "All Tabs" ("+" icon in the top right) | Click on Transactions.

  • Click "New".

  • Select "Charge" Record Type then "Next".

  • Required Fields:

Amount: The Transaction amount.

Currency ISO: The currency to process this Transaction in.

Payment Method: The Payment Method used to process this Transaction.
The Payment Method must be valid to capture a Transaction.

These are the only fields needed to successfully capture a Transaction.

  • Click "Save".

  • Click the "Capture" button.

Lightning: Click the down arrow (top right corner) | Click "Capture".

Classic: Click the "Capture" button at the top.

If Transaction was successful, the Transaction Status will update to "Completed" and Payment Status will update to "Captured".

Partially Captured Transaction

Once a Transaction has successfully authorized, and you decide to capture less than the original amount, the Payment Status updates to "Partially Captured."

  • Navigate to the Transactions object.

Lightning: Click on the App Launcher | Under "All Items" | Click on Transactions.

Classic: Click on "All Tabs" ("+" icon in the top right) | Click on Transactions.

  • Select an existing "Authorized" Transaction.

  • Update the Amount field to a lesser amount.

  • Required Fields:

Currency ISO: The currency to process this Transaction in.

Payment Method: The Payment Method used to process this Transaction.
The Payment Method must be valid to capture a Transaction.

These are the only fields needed to successfully capture a Transaction.

  • Click "Save".

  • Click the "Capture" button.

Lightning: Click the down arrow (top right corner) | Click "Capture".

Classic: Click the "Capture" button at the top.

If the Transaction was successful, the Transaction Status will update to "Completed" and Payment Status will update to "Partially Captured".

Refunded/Partially Refunded Transaction

To refund a Transaction in full, click on the "Refund" button. To partially refund a Transaction, click on the "Partial Refund" button, enter the amount to be partially refunded and click refund.

Both refunds and partial refunds will create Transactions related to the original, parent Transaction. The Retained Revenue Amount field captures the amount of the Transaction left after all refund(s). Ex. If the original Transaction was 100 and two partial refunds of 35 each (70 total) were processed, the Retained Revenue Amount field will read 30.

You can also fully refund or partially refund Non-Gateway Transactions (see: Non-Gateway Transactions).

  • Navigate to the Transactions object.

Lightning: Click on the App Launcher | Under "All Items" | Click on Transactions.

Classic: Click on "All Tabs" ("+" icon in the top right) | Click on Transactions.

  • Select an existing "Captured", "Partially Captured" or "Partially Refunded" Transaction.

  • Click "Refund" or "Partial Refund".

  • If Partial Refund, enter the amount.

  • Click "Refund".

If the Transaction was a full refund, the Transaction Status will update to "Completed" and Payment Status will update to "Refunded". If it was a partial refund, Transaction Status will update to "Completed" and Payment Status will update to "Partial Refund".

Releasing Authorized Transactions

In Payments versions 4.43 and later...

The Uncaptured Method is now defined on the related refund transaction in addition to the original authorized transaction. Upgrade to the latest version, here.

There is a new field called, Uncaptured Method that tells you if an authorized Transaction was released (refunded) before the 7 days.

  • Manual: This means the authorized transaction was manually released from the user.
  • Automatic: This means the authorized transaction was automatically released by Stripe after 7 days.

When you need to release an authorized Transaction before 7 days.

  • Navigate to the authorized Transaction

  • Select the Refund button

    The authorized Transaction has been released in Stripe and the Payment Status updates to "Refunded".

`

Releasing a Transaction from Stripe will follow the same process as above.

In Payments version 4.54 and later..

When you release an authorized transaction by clicking the Refund button, there are no refund transaction created and the Payment Status updates to "Uncaptured".

Non-Gateway Transaction

Recording a Non-Gateway Transaction is similar to creating a charge Transaction with the exception that a Non-Gateway Transaction is not subject to the validations and processes that a charge Transaction is subject to.

However, you can refund and partially refund Non-Gateway transactions; you can use the Refund buttons and checkboxes the same way you'd use it with normal Transactions.

  • Navigate to the Transactions object.

Lightning: Click on the App Launcher | Under "All Items" | Click on Transactions.

Classic: Click on "All Tabs" ("+" icon in the top right) | Click on Transactions.

  • Click "New".

  • Select "Charge" Record Type then "Next".

  • Required Fields:

Amount: The Transaction amount.

Currency ISO: The currency of this Transaction.

Non-Gateway: Checking this indicates the Transaction is a "Non-Gateway Transaction" and you can manually set any of the fields. IE Transaction for cash or a mailed-in check.
Non-Gateway Transactions are not processed or captured like charge Transactions.

  • Click "Save".

Failed Transactions

Transactions that fail to process, such as for card declines, cannot be retried. The Transaction must be cloned then reattempted. The app is built this way because Stripe maintains IDs, even for failed Transactions.


Deleting Transactions

By default, once a Transaction has any Stripe fields populated (such as the Error Message or Transaction ID), you will not be able to delete it. If you do need to delete a Transaction, you can disable the Transaction validations in custom settings. This is done because Blackthorn | Payments is built to be a mirror of your Stripe database.


Auto-Process/Scheduled Transactions

There is a scheduled process that will automatically process Transactions. Those Transactions have to meet certain criteria in order to be processed. Click here for additional information.

Need to configure reattempt logic for your scheduled Transactions? If you would like a new Transaction automatically created and queued for auto-process when the original Transaction fails, click here.


Capturing Multiple Transactions In List View

Transactions can be manually processed in batch, up to 200 at a time through a Salesforce list view.

To capture multiple Transactions at one time:

  • Click on the Transactions object tab.

  • Click on the packaged list view called "Scheduled for Auto-Process (Future)".

  • Select which records to process by using the checkboxes.

  • Click the "Capture" button. (If the Capture button is not available in your ListView, navigate to the Transaction object in Setup and add the button to your available List View buttons.)

  • On the next screen, verify the Transactions to process and click "Capture".


Payout Transaction

Stripe makes deposits (payouts) from your available account balance into your bank account. This account balance is comprised of different types of transactions (e.g., payments, refunds, etc.).

Payout transactions are created in Salesforce via webhook by Stripe.
They cannot be manually created in Salesforce.

  • Once a payout transaction has been created with a Payment Status = Paid, all charge transactions are related to the Payout through the Payout field on Charge Transactions during the daily charges batch job.

It is important that payouts relate to original charges, refunds, and transfers so that you can successfully prove and document that account balances are in agreement.

In addition to relating a payout record to all original charges, refunds, and transfers we provide an out-of-the-box report on payouts and related transactions.

Batch job process

  • All payout transactions with a RecordType = Payout, Transaction Status = Completed and Payment Status = Paid.

    ** The Payout Transaction record then sets the Payout Processed Date field with a timestamp of when it was processed so the batch job knows not to process it again.

  • This batch job can be triggered manually by going to the Blackthorn | Payments Settings tab, clicking on the Batch Jobs link and then clicking the Process Payout Balance History button.


Adjustment Transaction

This transaction is created via webhook by Stripe, they should not be manually created.


Parent Object Roll-up Fields

There are roll-up fields that get automatically created on the parent object(s) you define in Blackthorn | Payments Setup Wizard on the Relationship(s) Step. Every time you create or edit a Transaction, an apex job called, "TransactionRollupToParentService" fires to update these balances.

Charge Transaction Fields

"Charge" Transaction roll-up fields are automatically placed on the parent object's page layout through the install wizard.
If you upgraded your org, these new fields will need to be manually added to your page layout.

These roll-up fields provide insight into all open, captured, refunded, retained, and non-gateway charges related to the parent object, like an Opportunity record.

  • Navigate to a parent object record. I.E. Opportunity record.

Lightning: Click on the App Launcher | Under "All Items" | Click on Opportunity.

Classic: Click on "All Tabs" ("+" icon in the top right) | Click on Opportunity.

  • Scroll down to "Charge Totals".
    This section provides all your roll-up fields for the "Charge" Transaction Record Type.

Checkboxes for Declarative Automation

In addition to the "Capture, Authorize, and Refund" buttons to process charge Transactions, we have provided checkbox fields that mirror the button functions. These checkboxes allow you to process Transactions automatically without the button. When Auto-Process runs, if Authorize or Refund are checked, the Transaction will be authorized or refunded instead of being captured. Checking each checkbox will perform the same process as if you were clicking the "Capture" or "Authorize" button.

These two fields are on the Transaction object but not placed on the Charge Record Type Page Layout.


Transaction Fees

There are several fields that calculate certain fees for Charge Transactions.

  • Stripe Fee: This is the fee from Stripe for successful Transactions.
    The fee amount is based on your plan with Stripe.

  • Refunded Stripe Fee: This is the refunded Stripe fee amount if your Transaction was fully or partially refunded.
    As of November 2017, Stripe stopped refunding Stripe fees for new customers.

  • Net Stripe Fee: This is the sum of the Stripe Fee minus the Refunded Stripe Fee.

  • Application Fee: (Stripe Connect Only) The platform's application fee for direct charges from a Connect Account.

  • Refunded Application Fee: (Stripe Connect Only) This is the refunded application fee amount if your Transaction was fully or partially refunded.

  • Net Application Fee: (Stripe Connect Only) This is the sum of the Application Fee minus the Refunded Application Fee.

  • Net Amount: This is the amount you receive after subtracting Stripe and Application Fees.

  • Retained Net Amount: This is the amount you receive after subtracting Stripe and Application fees and any refunds.
    This amount may be negative if you performed a full refund and the Stripe fees were not refunded.


Roll-up/Roll-down Features

Payment Method

When a Contact's or Account's default Payment Method (a lookup field on each respective object) is updated, all "Open" Transactions' Payment Methods related to that customer update automatically.
If you don't want a certain Transaction's Payment Method to change, check the Don't Auto-Update Payment Method checkbox on the Transaction record. If you don't want any Transactions to automatically update, check the "Disable Update PM Related Transactions" Custom Setting record.

Contact and Account

When a Payment Method is defined on a Transaction, the related Contact and/or Account from the Payment Method will get added to the Transaction unless the Transaction already had those fields defined.


Removing the Transaction Parent Object

  • Navigate to Setup
  • In the Quick find, type in and search for "Custom Settings"
  • Click "Manage" next to Transaction Parents.
  • Click delete next to the object you want to remove
  • Delete the lookup fields on both the Transaction object and your object.

Next Steps


Troubleshooting/FAQ

If you have received an error with any of your Transactions or have a question, please view our Troubleshooting and Frequently Asked Questions. If you still have questions regarding your Transactions, please contact Blackthorn Support. We're happy to help!

Transactions


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.