Reconciling Payments

This guide explains how to use the Reconcile Payment Funding endpoint to manually complete a payment that is in the UNDERFUNDED, OVERFUNDED, or FUNDED status.

Before reconciling an UNDERFUNDED payment, read the OVERFUNDED and UNDERFUNDED Payments guide — we recommend waiting before reconciling, as a second deposit often arrives shortly after the first.

Endpoint

PUT /api/v1/payment_orders/{payment_order_id}/payments/{payment_id}/funding/reconcile

Headers

Request Body

{
  "order_items": [
    {
      "name": "Item description",
      "amount": 8500,
      "vat_rate": 25.0,
      "merchant_id": "a3453a44-69bf-47eb-bb1a-ae7b1a6ff51d"
    }
  ]
}

The order_items array replaces the original order items with new items that reflect the actual received amount.

Note: The sum of all order_items amounts must equal the total received funds. The total received funds is the sum of all received_funds.

Scenarios

UNDERFUNDED Payment

A payment was created for 100 SEK but the customer only transferred 85 SEK

Status callback received:

{
  "status": "UNDERFUNDED",
  "received_funds": 8500
}

After waiting and confirming no further deposits will arrive, reconcile with adjusted items that sum to the received amount:

PUT /api/v1/payment_orders/{po_id}/payments/{p_id}/funding/reconcile

{
  "order_items": [
    {
      "name": "Membership fee (adjusted)",
      "amount": 8500,
      "vat_rate": 25.0,
      "merchant_id": "a3453a44-69bf-47eb-bb1a-ae7b1a6ff51d"
    }
  ]
}

The payment transitions to COMPLETED.

OVERFUNDED Payment

A payment was created for 100 SEK, but the customer transferred 120 SEK

Status callback received:

{
  "status": "OVERFUNDED",
  "received_funds": 12000
}

Reconcile with items totaling the full received amount:

PUT /api/v1/payment_orders/{po_id}/payments/{p_id}/funding/reconcile

{
  "order_items": [
    {
      "name": "Membership fee",
      "amount": 10000,
      "vat_rate": 25.0,
      "merchant_id": "a3453a44-69bf-47eb-bb1a-ae7b1a6ff51d"
    },
    {
      "name": "Overpayment",
      "amount": 2000,
      "vat_rate": 0,
      "merchant_id": "a3453a44-69bf-47eb-bb1a-ae7b1a6ff51d"
    }
  ]
}

The items sum to 120 SEK, matching the received funds. The payment transitions to COMPLETED.

Note: Ping Deposit does not support refunds. If you need to return an overpayment to the customer, this must be handled outside of the payment flow via a separate bank transfer.

FUNDED Payment (complete_when_funded: false)

When a payment was created with complete_when_funded: false and the exact amount was received, the status is FUNDED. You can complete it without changing the original items by passing null:

PUT /api/v1/payment_orders/{po_id}/payments/{p_id}/funding/reconcile

{
  "order_items": null
}

This transitions the payment to COMPLETED using the original order items. Passing null is only valid when the payment status is FUNDED.

Best Practices

• Item amounts are binding. The reconciled items become the source of truth for how funds are distributed among merchants. Ensure amounts, VAT rates, and merchant assignments are correct before submitting.
• Use callbacks to track deposits. Each incoming deposit triggers a status callback containing the received_funds for that deposit. Accumulate these to know the running total.
• Decide on an overpayment policy. For OVERFUNDED payments, determine whether to model the surplus as a separate line item, absorb it into an existing item, or return it out-of-band.