API GuideDashboard
Home
Payments
Automation
Observability
Reconciliation
Payment Methods
Fraud Providers
SDK Reference
Changelog

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 to a simplified Primer type.
direction
enum: CREDIT, DEBIT		Describes whether this field is a credit to the settlement or deducted from the settlement as a debit.
createdDate
date-time		The date and time the payment was created in Primer, in ISO 8601 format
capturedDate
date-time		The date and time the payment capture was settled in Primer, in ISO 8601 format.
processorTransactionId
string		This is the processor's unique identifier for the transaction. We use this ID to match Primer's payments ledger to the settlement report.
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 >= 0, default: 0		Original transaction amount, less totalFee, in the currency of payoutCurrencyCode. This is also known as Net settlement.
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, MC, Amex).
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.

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: If there are any standalone fees reported that are not directly tied to a single payment, these might show up with transaction type FEE.
  • 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.

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 it's state within the processor's dashboard.

Versioning

There are no different versions of the report at this time. If we introduce a breaking change, we will introduce a new version and coordinate it's release with you.

We do not consider adding additional columns as a breaking change, and might do so whenever required.

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.