Payment records
Payment records describe what happened when Paypercut attempted to move money. They are the primary resource for reconciliation, payment outcome review, and transaction-level details.
Use Payment Intents to control the lifecycle of a payment attempt. Use Payments to inspect the resulting money movement.
Payment Intent versus Payment
| Resource | Use it for |
|---|---|
| Payment Intent | Creating, confirming, capturing, canceling, and tracking the lifecycle of a payment attempt. |
| Payment | Inspecting the payment result, payment method details, outcome, fees, refunds, and reconciliation fields. |
A Payment Intent can create a Payment when confirmation starts. Before confirmation, latest_payment can be null. After confirmation, use the Payment Intent status to decide what lifecycle action is next, and use the Payment record to inspect the transaction details.
When to retrieve a Payment
Retrieve a Payment when you need to:
- show payment status in an internal dashboard;
- reconcile payments against orders, invoices, or settlements;
- inspect failure details and outcome information;
- confirm whether a manual-capture payment was captured;
- inspect card, wallet, and 3D Secure details;
- review fees, refund state, or dispute state.
The Payments API also supports listing payments with filters such as customer, status, currency, payment method, operation, date range, and client_reference_id.
Important fields
| Field | Meaning |
|---|---|
id |
Unique Payment ID. |
amount |
Payment amount in the smallest currency unit. |
currency |
Currency used for the payment. |
status |
High-level payment status, such as succeeded, pending, or failed. |
latest_status |
Latest provider or processing status known for the payment. |
captured |
Whether an authorized payment has been captured. |
paid |
Whether the charge succeeded or was authorized for later capture. |
payment_method |
Payment method type used for the payment. |
payment_method_details |
Snapshot of card, wallet, and authentication details used for this payment. |
payment_intent |
Payment Intent associated with this Payment. |
checkout_id |
Checkout Session that created the payment, if applicable. |
client_reference_id |
Your reference copied from the Checkout Session when available. |
outcome |
Decision and result information for the payment. |
failure_code and failure_message |
Failure information when the payment fails. |
fee and fee_details |
Fees assessed for the transaction. |
metadata |
Merchant-defined key-value context attached to the Payment. |
Payment method details
payment_method_details is a snapshot of the instrument and authentication details used at payment time. It can include card brand, last four digits, wallet details, network transaction identifiers, and 3D Secure details.
3D Secure details are exposed under:
payment.payment_method_details.card.three_d_secure
Use this field when you need to debug authentication outcomes or show transaction-level evidence in back-office tooling.
Reconciliation
Use these identifiers to connect a Payment back to your system:
| Identifier | Where it comes from |
|---|---|
payment_intent |
Payment Intent that created the Payment. |
checkout_id |
Checkout Session that created the Payment. |
client_reference_id |
Your own order, cart, customer, or session reference. |
customer |
Paypercut Customer associated with the payment, if one exists. |
For hosted checkout flows, pass client_reference_id when creating the Checkout Session. Later, list or retrieve Payments and use this field to reconcile the payment to your internal order.
When Paypercut creates the first Payment from a Payment Intent, the Payment receives an initial snapshot of the Payment Intent metadata. For Checkout-created payments, pass payment_intent_data.metadata when you want metadata to follow the underlying Payment Intent and the resulting Payment. If the Payment Intent does not have metadata, Paypercut uses the checkout context available at Payment creation time.
Update reconciliation fields
You can update a Payment to attach reconciliation fields after the payment has been created.
Use client_reference_id for your main order, cart, customer, or session reference. The field is write-once on a Payment: setting it when empty is allowed, retrying the same value is allowed, and changing it to a different value is rejected.
Use metadata for additional key-value context. Metadata updates merge into the existing Payment metadata. Provided keys overwrite existing values for those keys, and omitted keys are left unchanged.
Payment webhook events, such as payment.succeeded and payment.captured, include the Payment metadata snapshot in data.object.metadata.
