The report content is focusing on transactional data, like sales and refunds. If a third party sends additional transfers within their report, we will forward this too. We are not consuming any additional reports outside of transaction reports. See supported processors to see which report we are consuming per processor.
Available values
| Field and data type | Description |
|---|---|
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. |
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 typeFEE.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.