An ACH pull transaction allows you to debit funds from a bank account and credit them into your account within the system, using the ACH (Automated Clearing House) network. This method is commonly used to collect fees, commissions, or to fund accounts directly from external bank accounts.

PCE supports multiple source types, allowing you to pull funds from pre-linked accounts or one-time bank accounts.

Use ACH pull when you need to collect funds directly from a bank account.

• Account Funding: Add funds to your account from your own or a customer’s bank account
• Fee Collection: Automatically debit platform fees, subscriptions, or commissions
• Recurring Payments: Collect scheduled payments from pre-linked accounts
• Invoice Payments: Pull funds from customers for outstanding invoices

How it works

Processing an ACH pull transaction involves sending bank account details to the API and tracking the transaction lifecycle.

1. Make a POST request to /v1/customer/id/{id}/transaction (or externalId) API endpoint with required parameters:

   Parameter	Required	Description
   method	✓	Set to ACH
   source	✓	Defines the bank account to be debited. Refer to the Source Types section below for supported options.
   destination.account.id (or externalId)	✓	The account within the system, to be credited
   amount	✓	Amount to debit (in USD)

   Source Types

   Pull from a Linked External Account

   Use when the bank account is already linked to Priority.

   Parameter	Required	Description
   source.externalAccount.id or externalId	✓	Identifier of the linked external account

   Best for:

   • Recurring collections
   • Funding your own accounts

   ---

   Pull from a One-Time Bank Account

   Use when debiting a bank account that is not pre-linked.

   Only available for Business Customers
   Requires enabling One-Time ACH Pull at the Program Manager level

   Parameter	Required	Description
   accountNumber	✓	Bank account number
   routingNumber	✓	9-digit routing number
   holderName	✓	Name of account holder
   type	✓	SAVING or CHECKING
   holderType	✓	CONSUMER or CORPORATE

2. You can also pass, the processingDetail object which carries additional processing instructions for your transaction. While optional as a whole, certain fields within it may be required depending on your Program Manager configuration. 

   Parameter	Required	Description
   processingDetail.processingMode	Recommended	Processing mode for the transaction. Possible values: - FORWARD (default) – Settles next business day (end-of-day batch) - SAME_DAY – Settles same day if before cutoff, else next business day
   processingDetail.companyName	Recommended	The payee name populated in the NACHA file. Defaults to Program Manager configuration if not provided.
   processingDetail.companyDescription	Recommended	Short description shown on the bank statement. Common examples include Gas bill, Reg. Salary, PURCHASE. If not provided, the default configured value is used.
   processingDetail.authType	Conditional	Authorization type used for the debit. Possible values: - WRITTEN – Signed authorization - PHONE – Recorded call authorization - ONLINE – Digital/web authorization
   processingDetail.addenda	Recommended	Additional reference data for reconciliation. Examples: - Invoice number - Customer reference ID - Order ID

3. Once the payment request is submitted, our system performs a series of system-level validations before sending the transaction to the card network. These validations check for:

   1. Missing or invalid required fields
   2. Incorrect parameter formats or values If any validation fails, the request is rejected immediately, and an error response is returned. You must correct the issue and resubmit the request. For a complete list of validation errors and how to resolve them, refer to the Error Codes & Messages section. 

4. If all validations pass, the transaction is submitted for processing. You can track the outcome by: 

   1. Retrieving the transaction via GET /v1/customer/id/{id}/transaction/id/{id} (or externalId) API endpoint
   2. Subscribing to Transaction webhooks Check the status field to understand the current state of the transaction.

5. For every successfully created transaction, store: 

   1. id – Unique transaction identifier
   2. externalId – Your reference identifier (if provided) These are required for tracking, reconciliation, and support.

Transaction Statuses

The table below describes the possible statuses of a Transaction wherein funds are pulled via ACH, and the reasons associated with each.

Best Practices