Partial payments

Partial payments let a customer cover a single order using more than one payment method — for example, a gift card for the balance on file and a credit card for the remainder, or two cards split at checkout. Each method is charged only for its portion; the sum of all captured amounts should equal the order total. Common use cases include gift card redemption at checkout, mixed-method POS tender, and deposit-then-balance payment flows.

How it worksAskCopy

VINR does not have a native "split order" object. Instead, each portion is a standard payment created independently and tied to the same order by a shared reference in metadata. Your backend owns the order total check: VINR processes and settles each payment on its own rail, and your application decides when the collection of payments fully covers the order.

Every partial payment:

• Has its own pay_… identifier and independent lifecycle.
• Carries metadata.orderId (and any other fields you choose) so you can group them server-side.
• Emits its own lifecycle events (payment.completed, payment.failed, etc.).
• Can be refunded independently up to its own captured amount.

The recommended pattern is to store the order total in your own system, create payment objects one at a time, and accumulate amountCaptured across all payments sharing the same orderId until the sum reaches the order total.

Create a partial paymentAskCopy

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const giftCardPayment = await vinr.payments.create({
  amount: 2000,
  currency: 'EUR',
  paymentMethod: giftCardPaymentMethodId,
  description: 'Order #9142 — gift card portion',
  returnUrl: 'https://yoursite.com/orders/9142/confirm',
  metadata: {
    orderId: '9142',
    portion: 'partial',
  },
});

// giftCardPayment.id     → "pay_4Gc7w1b..."
// giftCardPayment.amount → 2000  (€20.00)

const ORDER_TOTAL = 5500; // €55.00 in minor units

const firstCaptured = giftCardPayment.amountCaptured; // 2000

const cardPayment = await vinr.payments.create({
  amount: ORDER_TOTAL - firstCaptured, // 3500 → €35.00
  currency: 'EUR',
  paymentMethod: cardPaymentMethodId,
  description: 'Order #9142 — card remainder',
  returnUrl: 'https://yoursite.com/orders/9142/confirm',
  metadata: {
    orderId: '9142',
    portion: 'final',
  },
});

// cardPayment.id     → "pay_7Hm2n9d..."
// cardPayment.amount → 3500  (€35.00)

const remainder = await vinr.payments.create({
  amount: 3500,
  currency: 'EUR',
  paymentMethod: cardPaymentMethodId,
  metadata: { orderId: '9142', portion: 'final' },
});

curl https://api.vinr.com/v1/payments \
  -H "X-Api-Key: $VINR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 3500,
    "currency": "EUR",
    "paymentMethod": "pm_...",
    "metadata": { "orderId": "9142", "portion": "final" }
  }'

Tracking order completionAskCopy

Listen for payment.completed on each partial payment. In your webhook handler, sum amountCaptured across all payments that share the same orderId and compare the total to the order amount stored in your system.

const event = vinr.webhooks.verify(rawBody, req.headers['x-vinr-signature']);

if (event.type === 'payment.completed') {
  const payment = event.data;
  const orderId = payment.metadata?.orderId;

  if (orderId) {
    await recordPartialCapture(orderId, payment.id, payment.amountCaptured);

    const totalCaptured = await sumCapturedForOrder(orderId);
    const orderTotal = await getOrderTotal(orderId);

    if (totalCaptured >= orderTotal) {
      await markOrderPaid(orderId);
    }
  }
}

Refunds on partial ordersAskCopy

Each partial payment is refunded independently via its own pay_… ID, up to its own captured amount. A full order refund means issuing a separate refund for each payment that contributed to the order.

async function refundOrder(orderId: string): Promise<void> {
  const payments = await getPaymentsForOrder(orderId);

  for (const payment of payments) {
    if (payment.amountCaptured > 0 && payment.amountRefunded < payment.amountCaptured) {
      const refundable = payment.amountCaptured - payment.amountRefunded;

      await vinr.refunds.create({
        payment: payment.id,
        amount: refundable,
        reason: 'requested_by_customer',
        metadata: { orderId },
      });
    }
  }
}

To refund only a portion of the order (e.g. one line item), determine which payment covered that item and issue a targeted refund against that payment's ID. See Refunds for status lifecycle and fee behaviour.

Partial payment fieldsAskCopy

AdvancedAskCopy

Next stepsAskCopy