Transactions
A transaction is the core entity for all payments-related interactions with the PublicSquare API. PublicSquare leverages double entry account to track all transactions. Payments are saved as a debit transaction and payouts, refunds, transfers, and settlements are saved as a credit transaction.
Types
PublicSquare uses different transaction types to track the flow of money for different use cases.
| Type | Description |
|---|---|
payment | Payments are used to collect funds from customers. Payments are recorded in PublicSquare as a debit transaction type. |
refund | Refunds enable you to return funds to a payment method associated with a payment. PublicSquare will attempt to cancel the payment if the payment has not been settled, and if unable to cancel, will create a refund. |
payout | Payouts are used to send funds to customers, merchants, and vendors. |
settlement | Settlements are batches created during end of day reconciliation processes and are associated with payments, refunds, and payouts. This represents money being deposited or withdrawn from your primary bank account. |
transfer | Transfers are used to send funds to connected sellers when creating a payment. For instance, if you charge a customer $300, you can transfer $100 to three different sellers as part of the same payment. |
Statuses
PublicSquare uses a status field on every transaction and transaction type to specify the state the transaction is in.
| Status | Description |
|---|---|
requires_capture | Used for authorized payments that still require capture. This places an authorization on the card. The transaction either needs to be captured or cancelled. |
successful | When a payment, payout, or refund has been successfully processed. For ACH payments and payouts, this will be set 2-3 days after the transaction was processed. |
pending | Used for ACH payments and payouts. Once the funds have cleared the bank account, the status will be updated to successful usually 2-3 days after the transaction was processed. |
rejected | Set when the fraud_details.decision field on a payment is marked as reject. This is set when your fraud decision rules trigger a reject decision. |
declined | Set when the bank rejects the payment or payout. Usually due to AVS or CVV2 checks failing or the payment method being declined such as invalid card or bank account details. |
cancelled | Set when a payment, payout, or refund has been successfully cancelled before being settled. |
error | The payment, payout, or refund attempt failed due to an unexpected system or integration issue, such as an invalid response from the processor, network errors, or a missing required parameter. |
Processing Schedules
Transactions can take different amounts of times to settle and appear in the merchant or customer's bank accounts. Card can be processed same or next day, but can take 2-3 business days for the funds to appear in the bank account after settlement. ACH requires an extra 2-3 business days for the funds to be withdrawn from the source bank account.
| Transaction Type | Payment Method Type | Processing Time |
|---|---|---|
payment | card | 2 to 3 business days |
payout | card | 2 to 3 business days |
payment | bank_account | 5 to 7 business days |
payout | bank_account | 5 to 7 business days |