Skip to main content

​
Available values

Field and data typeDescription
id
string		The unique Primer payment ID returned by Primer’s Payments API when the payment request was made.
amount
decimal, >= 0		The amount the customer was charged, refunded or claimed as a chargeback. This is Primer’s record of the payment.
paymentMethod
string		The payment method or card scheme used to process this payment.
orderId
string		The order ID you send to Primer via Primer’s API when creating the payment.
processor
string		The identifier of the processor.
merchantId
string		The merchant ID registered at the payment processor used for this payment.
transactionType
enum: SALE, FEE, REFUND, TRANSFER, DISPUTE, PAYOUT		Explains the type of transaction that took place but maps the various transactionTypeDetail values to a simplified Primer type.
direction
enum: CREDIT, DEBIT		Whether this is a credit to the settlement or deducted as a debit.
createdDate
date-time		Date and time the payment was created in Primer (ISO-8601).
capturedDate
date-time		Date and time the payment capture was settled in Primer (ISO-8601).
processorTransactionId
string		The processor’s unique identifier for the transaction.
status
enum: PENDING, FAILED, AUTHORIZED, SETTLING, PARTIALLY_SETTLED, SETTLED, DECLINED, CANCELLED		The status of the payment in Primer.
currencyCode
string		The code of the currency you charged the customer. 3-digit currency code in ISO 4217 format. e.g. USD for US dollars. This is Primer’s record of the payment.
metadata
JSON object		Additional data to be used throughout the payment lifecycle. A dictionary of key-value pairs where the values can only be strings or integers. e.g. {"productId": 1001, "merchantId": "a13bsd62s"}. This may be sent to Primer’s API.
reconciliationAmount*
decimal, >= 0		The amount the customer was charged, refunded or claimed as a chargeback. This is the processor’s payment record from the settlement report.
reconciliationCurrencyCode*
string		The code of the currency you charged the customer. It is a 3-digit currency code in ISO 4217 format, e.g., USD for US dollars. This is the processor’s payment record from the settlement report.
payoutGrossAmount*
decimal, >= 0, default: 0		The original transaction amount in the currency of payoutCurrencyCode. This is also known as Gross settlement.
payoutNetAmount*
decimal, default: 0		Original transaction amount, less totalFee, in the currency of payoutCurrencyCode. This is also known as Net settlement. Can be negative when deductions exceed the gross amount.
payoutTotalDeductionsAmount
decimal, default: 0		Total fees incurred and deductions due to this transaction in the currency of payoutCurrencyCode. It is possible for that value to have a negative amount (if it increases the payoutGrossAmount) or positive amount (if it decreases the payoutGrossAmount). Note: This field will not be populated if the processor provides a separate line item fee transaction type.
processorFeeAmount*
decimal, default: 0		This is the fee that the acquiring bank charges when a payment is made. It is possible for that value to have a negative or positive amount. The value for processorFeeAmount is already added to payoutTotalDeductionsAmount. This value is only filled when the upstream source is reporting with that granularity.
interchangeFeeAmount*
decimal, default: 0		This is the fee that the issuing bank charges when a payment is made. It is possible for that value to have a negative or positive amount. The value for interchangeFeeAmount is already added to payoutTotalDeductionsAmount. This value is only filled when the upstream source is reporting with that granularity.
schemeFeeAmount*
decimal, default: 0		This is the fee paid to the scheme/network when a payment is made. It is possible for that value to have a negative or positive amount. The value for schemeFeeAmount is already added to payoutTotalDeductionsAmount. This value is only filled when the upstream source is reporting with that granularity.
reconciliationOrderId*
string		The processor record of the Order ID from the settlement file.
network
string		The card scheme that the payment went through (e.g. Visa, Mastercard, American Express).
payoutDate*
date-time		The date and time at which the payout was submitted in UTC format.
payoutBatchId
string		Shared ID of all transactions contained within this batch of settlement data from the processor.
payoutCurrencyCode*
string		The code of the currency used for this payout. 3-digit currency code in ISO 4217 format. e.g. USD for US dollars. This is also known as settlement currency.
transactionTypeDetail*
string		Raw transaction type provided by the processor.
reconciliationResult
enum: TRUE, FALSE		Indicates whether the transaction content from the processor matches the content stored in Primer.

Note: Transfers, fees, disputes, and payouts will be automatically marked as reconciled because they are not recorded in Primer.
reconciliationResultHistory
string		Gives more information on the reason for the mismatches found, highlighting the values expected and the value received from the processor.
conflictReason
enum: TRANSACTION_UNKNOWN, AMOUNT, TRANSACTION_TYPE, CURRENCY		Identifies the reason for the conflict for transactions that can’t be matched between Primer and the processor’s settlement report.
processorAccountId*
string		An optional account identifier for the processor. This can be helpful to attribute costs to account-level fees, rather than specific to a payment or merchant Id.
transactionEventId
string		An ID referencing the Primer transaction lifecycle to help track individual events against a payment, such as capture, or refunds.
Fields marked with * are taken from the processor’s settlement report, whereas the remaining fields originate from the Primer Payment or from Primer’s Reconciliation batch processing logic.

​
Decimal amounts

We are using decimal amounts in the reports, which is a deviation from how Primer’s Payment API works. This is so that we can accurately reflect the granularity by which third parties report settlement data, like transaction fees, without introducing rounding errors.
Amounts will therefore always come with eight decimal places for consistency, even for currencies like JPY that don’t use minor units.

​
Transaction types

  • SALE: Refers to a settled payment and might include cost/fee information.
  • REFUND: Refers to a refund on a settled payment and might include cost/fee information. This could also refer to blind credits not related to Primer payments.
  • DISPUTE: Refers to payment funds being reversed due to a dispute and might include cost/fee information.
  • FEE: Refers to fees not tied to a settled payment, such as authorization fees or other standalone charges.
  • PAYOUT: Groups any transaction related to the processor balance and bank account funds movement.
  • TRANSFER: Any other money transfer (credit or debit) beyond the specifically mapped ones like Sale or Refund.

​
Using the direction field

The direction field determines how funds flow in or out of your account. Always combine direction with payoutNetAmount to determine the financial effect of a record.
DirectionMeaningGross amountDeductionsNet amount
CREDITFunds to the merchantTotal credited before deductionsSubtracted from grossActual payout to merchant
DEBITFunds from the merchantTotal amount charged or reversedAdded to grossTotal amount deducted from merchant
Formulas:
  • CREDIT: payoutGrossAmount - payoutTotalDeductionsAmount = payoutNetAmount
  • DEBIT: payoutGrossAmount + payoutTotalDeductionsAmount = payoutNetAmount
Examples (all amounts in USD):
directionpayoutGrossAmountpayoutTotalDeductionsAmountpayoutNetAmountMeaning
CREDIT100.002.5097.50A positive credit. Merchant receives 97.50
CREDIT0.000.50-0.50A negative credit. Merchant is charged 0.50 (e.g. a fee correction)
DEBIT0.001.001.00A positive debit. Merchant is charged 1.00
DEBIT50.0010.0060.00A positive debit. Merchant is charged 60.00 (e.g. reversed payout)
DEBIT2.00-5.00-3.00A negative debit. Merchant receives 3.00
Gross amounts can be 0.00, especially in fee-only transactions. direction still clarifies whether the net amount represents funds to or from you.

​
Understanding fees

Fee values use a consistent sign convention across all records. You do not need to rely on direction or transactionType to interpret them:
  • Fee > 0: a deduction from your payout
  • Fee < 0: returned funds (e.g. a fee reversal)
This applies to all fee columns: processorFeeAmount, interchangeFeeAmount, schemeFeeAmount and payoutTotalDeductionsAmount. Fee values can have many decimal places due to fractional reporting from some PSPs.

​
Special case: transactionType = FEE

FEE records appear in the following scenarios:
  • Platform or account-level fees not tied to a specific transaction
  • Fees for non-settled payments: the matching engine only has access to settled payments, so fees for payments that did not settle (e.g. declined authorization fees) cannot be matched and appear as FEE records
  • Delayed fee application: fees such as authorization charges can appear in the report days after the original transaction
  • Fallback: when Primer cannot identify the matching transaction for a fee, it falls back to the FEE type

​
Transaction type tips

  • SALE, REFUND, DISPUTE: can be CREDIT or DEBIT, and can appear with payoutGrossAmount = 0 when only fees are being reported for that day. Always rely on direction and the amount fields rather than the transaction type alone.
  • TRANSFER: represents general fund transfers not tied to a specific transaction. This is also used as a fallback when none of the other specific types apply.

​
Field interpretation tips

FieldTip
directionCREDIT means funds to you; DEBIT means funds from you. Ensure you take into account whether the amount is a negative or a positive
payoutCurrencyCodeYour settlement currency. Used for payoutGrossAmount, payoutNetAmount, payoutTotalDeductionsAmount, processorFeeAmount, interchangeFeeAmount and schemeFeeAmount
payoutGrossAmountAmount before deductions, in settlement currency
payoutNetAmountFinal settled amount, in settlement currency. Can be negative when deductions exceed the gross amount
reconciliationAmountTransaction amount in the presentment (transaction) currency
reconciliationCurrencyCodePresentment (transaction) currency
createdDateTimestamp of the transaction event
reconciliationOrderIdOrder ID from the PSP. On refunds, some PSPs support a separate order ID matching the one you passed on the refund request; others return the same ID as the original authorization. This field reflects whatever the PSP reports.

​
Integration checklist

Before going live with your reconciliation integration, confirm the following:
  • Use direction to determine whether gross and net amounts represent funds to or from you.
  • Handle both positive and negative net amounts correctly for CREDIT and DEBIT records.
  • Use payoutTotalDeductionsAmount as the primary fee value for total deductions.

​
Batches and files

Primer generates one unified file per batch of settlement data received from a processor. All files follow the same structure regardless of processor. To calculate the total net payout for a batch: 
A = sum of payoutNetAmount where direction = CREDIT
B = sum of payoutNetAmount where direction = DEBIT
Total net payout = A - B

​
Conflict reasons

A batch status of Conflict in the dashboard means there could be any number of reasons on why we flagged a particular transaction. The actual available values for conflictReason in the report are as follows:
  • TRANSACTION_UNKNOWN: We don’t have a record of the processor transaction ID to map to a Primer payment. Usually for payments created outside of Primer.
  • AMOUNT: Our record of the amount differs to the amount reported.
  • CURRENCY: Our record of the currency differs to the currency reported.
  • TRANSACTION_TYPE: This could only happen if we recorded a payment as a sale but the settlement report indicates it as a refund, or the other way round.
Depending on the reason and amount of conflicts, you can investigate by looking at the payment within the Primer dashboard, and comparing its state within the processor’s dashboard.

​
Sample report

Download an example CSV file. The file structure will be the same for every processor, but naturally IDs like transaction IDs or merchant IDs, or raw transaction types, will vary from one processor to another.