This guide covers everything you need to know to integrate Ping Deposit payments through the Ping Payments API. Ping Deposit is a bank transfer-based payment method where customers pay by transferring funds to a designated bank account using a generated payment reference (OCR or KID number).

How It Works

Unlike card or redirect-based payment methods, Ping Deposit is an asynchronous bank transfer flow:

1. You initiate a payment — the API returns bank account details and a unique payment reference.
2. You present the payment instructions (and optionally a generated invoice) to your customer.
3. The customer makes a bank transfer to the provided account using the reference.
4. The system automatically matches the incoming transfer to the payment and updates its status.

Tenant Setup

Before using Ping Deposit, your tenant must have a deposit account configured for the relevant currency and reference type. This is handled by Ping Payments during onboarding. Each deposit account is backed by a real bank account with an associated bankgiro number.

Initiating a Payment

Use provider: "ping" and method: "deposit" in the initiate payment request.

Required Parameters

Optional Parameters

Supported Currencies

SEK, NOK, EUR, GBP, DKK

Example Request

{
  "currency": "SEK",
  "method": "deposit",
  "order_items": [
    {
      "amount": 10000,
      "merchant_id": "{{merchantId}}",
      "name": "Membership fee",
      "vat_rate": 25.0
    }
  ],
  "provider": "ping",
  "total_amount": 10000,
  "provider_method_parameters": {
    "reference_type": "OCR",
    "complete_when_funded": true
  }
}

Example Response

{
  "id": "15c44587-7ebb-43a3-b437-8d00e5f8df7a",
  "provider_method_response": {
    "reference": "1234567890",
    "deposit_reference_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "bank_account": {
      "iban": "SE1234567890123456789012",
      "bankgiro_number": "123-4567",
      "bban": "12345678901",
      "bic": "SWEDSESS"
    }
  }
}

The response provides:

• reference — the OCR/KID number the customer must include in their bank transfer.
• deposit_reference_id — a UUID for tracking the deposit reference and associated transfers.
• bank_account — the account details (IBAN, bankgiro number, BBAN, BIC) the customer should transfer to.

Payment Status Flow

After initiation, the payment status transitions based on incoming bank transfers:

PENDING
  │
  ├── partial amount received ──► UNDERFUNDED
  │                                    │
  │                                    ├── remaining amount received ──► COMPLETED (or FUNDED)
  │                                    └── excess amount received ───► OVERFUNDED
  │
  ├── exact amount received ────► COMPLETED  (if complete_when_funded: true)
  │                             ► FUNDED     (if complete_when_funded: false)
  │
  └── excess amount received ──► OVERFUNDED

complete_when_funded Behavior

• true (default): The payment automatically moves to COMPLETED when the exact amount is received. This is the simplest integration — no further action is needed after the customer pays.
• false: The payment moves to FUNDED when the exact amount is received, allowing you to perform manual reconciliation before completing the payment. Useful when you need to verify the transfer before fulfilling the order.

Invoice Generation

Ping Deposit supports optional PDF invoice generation with bankgiro QR codes. To use this feature, invoicing must be enabled for your tenant.

Invoice Parameters

When providing the invoice object, the following fields are available:

Required:

Optional:

Customer Object

Invoice Row

Invoice Response

When an invoice is generated, the response includes URLs:

{
  "invoice": {
    "display_url": "https://...",
    "download_url": "https://..."
  }
}

Reusing References

You can reuse a payment reference from a previous Ping Deposit payment by passing it in the reference parameter. This is useful when a previous payment was cancelled and you want to issue a new payment with the same reference. Only one active payment per reference is allowed at a time — all previous payments using that reference must be in a terminal state.

Refunds

Refunds are not supported for Ping Deposit payments.