Transactions Schema
Payment, refund, and transfer transactions with processing details
The Transactions schema defines the structure and properties of transaction objects in the Payload API. This comprehensive reference table shows all available properties, their types, constraints, and requirements.
Transactions Object Properties
Complete reference for all properties available in the Transactions schema
amountnumber (double)Required
The monetary amount for this transaction in the currency of the processing account. This value is always positive and represents the total value being transferred, collected, or refunded. The amount is rounded to two decimal places for display.
attrsobject
Custom object attributes
check_imagesobject
Images of the physical check for check conversion transactions. Both front and back images are required and will be processed using OCR to extract payment details. The front image provides account information while the back image shows endorsements.
backCheckBackobject
The back image of the check being processed. This image is required for check deposit transactions and is used for verification and record-keeping purposes. It must show any endorsements on the back of the check.
Visibility: explicit
frontCheckFrontobject
The front image of the check being processed. This image is used for OCR processing to extract account numbers, routing numbers, check numbers, and amounts. The image must be clear and readable for successful processing.
Visibility: explicit
clearing_timingenum[string]Immutable
The clearing speed for this transaction, determining how quickly funds are made available to the recipient. Instant clearing makes funds available immediately, same_day within the same business day, and next_day by the following business day. Defaults to next_day if not specified. Same-day and instant are only available in certain circumstances.
Values:
instant, same_day, next_daycreated_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
descriptionstring
A human-readable description of what this transaction is for. This text provides context about the purchase, service, or payment purpose and may be displayed to customers on receipts and in transaction histories.
Max length: 128
est_cleared_datestring (date)
The estimated date when this transaction will be cleared and funds will be available or settled. This is an estimate and not guaranteed.
Read-only permissions:
"Undocumented"finalizedbooleanRead-only
Indicates whether this transaction has been finalized for settlement.
funding_delaynumber (double)Read-only
The number of days to delay the funding settlement for this transaction. This value determines how long to hold funds before they are deposited to the merchant or moved to the recipient account. This is typically set based on the processing account settings.
funding_timingenum[string]Immutable
The funding speed for this transaction, determining how quickly the merchant or processing account receives settlement of funds. Standard timing follows normal settlement schedules, while rapid timing accelerates the funding process for faster access to funds. Defaults to standard if not specified. Rapid and instant funding only available in certain circumstances.
Values:
standard, instant, rapididstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: txn)
Pattern:
^txn_[A-Za-z0-9]+$modified_atstring (date-time)Read-only
Timestamp when the resource was last modified. Automatically updated whenever any field changes.
notesstring
Internal notes or comments about this transaction. This field is for record-keeping purposes and can contain any additional information that may be useful for reference, customer service, or accounting purposes.
Max length: 2048
objectenum[string]Read-only
String representing the object type for this resource.
Values:
transactionorder_detailsobjectImmutable
Detailed line-item breakdown of the order including individual product amounts, quantities, descriptions, and tax information. This data is used for Level 2 and Level 3 card processing to qualify for lower interchange rates and must match the transaction amount.
cust_ref_numberstring
Customer reference number or purchase order (PO) number for this transaction. This is a merchant-assigned identifier used for tracking and reconciliation purposes. Provides additional transaction verification information.
incl_costsobject
Additional costs included in the transaction total. Contains tax and other fees that are part of the total transaction amount. Provides complete cost breakdown.
sales_taxnumber (double)
Total amount of sales tax included in the transaction. This is the aggregate tax amount across all line items. Must match the sum of individual line item tax amounts for validation. Used to verify proper tax handling.
line_itemsarray
Array of individual line items in this order. Each line item represents a distinct product or service being purchased. Provides detailed transaction information. Each line item must include commodity code, description, product code, and unit price. The sum of all line items (including their taxes) must equal the total transaction amount for validation.
order_numberstring
Custom order or transaction number for this payment. Use this to link the payment to an order in your system or to provide a customer-facing transaction reference. Providing this value ensures duplicate protection is applied per order; .otherwise, duplicate protection applies across payments without an order reference. For check transactions this field contains the check number.
Max length: 64
receiverobject
Information about the receiver party in this transaction, including the account and payment method to which funds are being sent or credited. For payment transactions, this is the processing account receiving funds. For payout transactions, this is the account receiving funds.
accountAccountobject
The expanded account object for the receiver. When included, this provides the full details of the account receiving funds in this transaction.
Visibility: explicit
account_id ID of AccountstringImmutable
The unique identifier of the account receiving funds for this transaction. This is an optional field that references the account object that owns the receiver payment method. (ID prefix: acct)
Pattern:
^acct_[A-Za-z0-9]+$methodPaymentMethodobject
The expanded payment method object used by the receiver. When included, this provides the full details of the payment method to which funds are being credited.
method_id ID of PaymentMethodstringImmutable
The unique identifier of the payment method used by the receiver. This references the payment method object to which funds are being sent or credited for this transaction. If not provided the account default will be used. (ID prefix: pm)
Pattern:
^pm_[A-Za-z0-9]+$ref_numberstringRead-only
A system-generated human-readable reference number for this transaction. This unique identifier can be used on receipts, customer communications, and for looking up transactions in reports and support inquiries.
Max length: 64
rejected_datestring (date)
The date on which this transaction was rejected. This field is automatically set when a transaction is set to rejected.
Read-only permissions:
"Undocumented"senderobject
Information about the sender party in this transaction, including the account and payment method from which funds are being sent or debited. For payment transactions, this is the account being charged. For payout transactions, this is the processing account sending funds.
accountAccountobject
The expanded account object for the sender. When included, this provides the full details of the account sending funds in this transaction.
Visibility: explicit
account_id ID of AccountstringImmutable
The unique identifier of the account sending or providing funds for this transaction. This is an optional field that references the account object that owns the sender payment method. (ID prefix: acct)
Pattern:
^acct_[A-Za-z0-9]+$methodPaymentMethodobject
The expanded payment method object used by the sender. When included, this provides the full details of the payment method from which funds are being debited.
method_id ID of PaymentMethodstringImmutable
The unique identifier of the payment method used by the sender. This references the payment method objectfrom which funds are being pulled or debited for this transaction. If not provided the account default will be used. (ID prefix: pm)
Pattern:
^pm_[A-Za-z0-9]+$shipping_detailsobjectImmutable
Shipping information for this transaction including the recipient address, shipping method, and costs. This data is used for Level 2 and Level 3 card processing to qualify for lower interchange rates and provide enhanced transaction details.
destobject
Destination shipping information. Contains complete details about where the goods are being shipped to, including recipient name, company, and full delivery address. Provides enhanced transaction data. Postal code is the only required field.
citystring
City or town of the shipping destination. Part of the complete destination address for enhanced transaction data. Combined with state and postal code to identify the delivery location.
country_codestring
Country code of the shipping destination. Must be either a 2-letter (ISO 3166-1 alpha-2) or 3-letter (ISO 3166-1 alpha-3) country code. For example, "US" or "USA" for United States, "CA" or "CAN" for Canada. Used for international transaction data.
postal_codestring
Postal code (ZIP code) of the shipping destination. Required field for the destination address. Used for enhanced transaction data.
Pattern:
^([A-Z][0-9][A-Z] [0-9][A-Z][0-9]|[0-9]{5}|[0-9]{9})$rcpt_companystring
Company or organization name of the recipient. Used when shipping to a business location. Helps identify the receiving organization.
rcpt_first_namestring
First name of the recipient receiving the shipment. Part of the complete recipient information for enhanced transaction data. Helps identify the person receiving the goods at the destination address.
rcpt_last_namestring
Last name (surname) of the recipient receiving the shipment. Part of the complete recipient information for enhanced transaction data. Combined with first name to identify the person receiving the goods.
state_provincestring
State, province, or region of the shipping destination. For US addresses, use the two-letter state code (e.g., CA, NY). For international addresses, use the appropriate province or region code.
street_addressstring
Street address line of the shipping destination. The primary address where goods will be delivered. Part of the complete destination address for enhanced transaction data. Should not include unit numbers (use unit_number field instead).
unit_numberstring
Unit, apartment, suite, or other secondary address information for the shipping destination. Use this for apartment numbers, suite numbers, building numbers, etc. Part of the complete destination address.
srcobject
Source (origin) shipping information. Contains details about where the goods are being shipped from. Provides enhanced transaction data.
postal_codestring
Postal code (ZIP code) of the origin location where the goods are being shipped from. Provides shipping origin information for enhanced transaction data.
Pattern:
^([A-Z][0-9][A-Z] [0-9][A-Z][0-9]|[0-9]{5}|[0-9]{9})$sourceenum[string]Immutable
The method by which this transaction was initiated or captured. This indicates whether the transaction was submitted via API, manually keyed, swiped through a card reader, processed via EMV chip, captured through NFC/contactless, initiated via digital wallets like Google Pay or Apple Pay, or processed as a check conversion.
Values:
api, keyed, swipe, emv, emv_quickchip, nfc, googlepay, applepay, checkstatusobject
The status information for this transaction, including the current state, a detailed status code, and a human-readable message explaining the result.
codeenum[string]
A machine-readable code detailing the specific reason or result for the transaction status. This provides granular information about success, failure reasons, or other status conditions.
Values:
approved, card_expired, duplicate_attempt, exceeded_limit, general_decline, insufficient_bal, invalid_card_code, invalid_card_number, invalid_zip, invalid_address, invalid_account_number, suspicious_activity, too_many_attempts, processing_issue, issue_reading_card, not_supported, general_reject, general_adjustment, payment_stoppedRead-only permissions:
"Undocumented"messagestringRead-only
A human-readable message describing the transaction status and code. This text is suitable for display to users and provides context about the transaction outcome.
valueenum[string]
The current processing status of the transaction, indicating its lifecycle state such as processing, processed, authorized, declined, voided, or rejected.
Values:
processing, authorized, processed, declined, rejected, voided, adjustedtransfer_typeenum[string]Read-only
The direction of funds movement for this transaction from the perspective of the processing account. A debit transaction pulls funds from an account, while a credit transaction pushes funds to an account.
Values:
debit, credittransfersTransferarray
No description
typeenum[string]RequiredImmutable
The type of transaction being processed. This determines the direction and nature of funds movement, such as payment collection, refund issuance, credit disbursement, or account funding operations.
Values:
payment, deposit, withdraw, refund, payout