Stripe Deposit Imports

Last Updated: 2026-07-17

Version: 1.1

Use one Stripe payout as the boundary for one VRPlatform deposit. The payout's settled balance activity becomes the deposit lines; Stripe fee details become separate negative lines.

This guide covers only the Stripe data transformation, matching hints, amount validation, and transaction batch request.

Result

For each Stripe payout with balance activity, submit one VRPlatform transaction with:

• type: deposit
• the Stripe payout ID as the transaction uniqueRef
• the payout creation date as the transaction date
• the lowercase payout currency
• the destination bank account's last four digits, when available
• one main line for each payout balance transaction
• one negative line for each grouped Stripe fee detail

All amounts remain integer minor units. For USD, 10000 means $100.00. Before submission, require this exact invariant:

sum(deposit line amounts) = Stripe payout.amount

Do not add an adjustment line to hide a difference.

Stripe Data to Load

Start with the Stripe Payout and load:

• every BalanceTransaction assigned to the payout
• each balance transaction's expanded source, source.charge, and source.payment_intent
• PaymentIntent metadata for each Stripe customer
• the payout's expanded destination when bank-account matching is required

The payout-filtered balance history is the settlement source of truth. A standalone charge list does not define which activity settled in this payout.

Join Map

Resolve the Settled Balance Activity

For an automatic payout, collect all balance transactions filtered by payout.id.

For a manual payout, require payout.balance_transaction, retrieve that balance transaction directly, and replace its amount with:

balanceTransaction.net * -1

This normally produces one coarse deposit line and may not contain enough charge or customer detail for reservation matching.

Some automatic payout histories include the payout movement itself. Treat a balance transaction as the payout self-transaction when both conditions hold:

• transaction.amount === -payout.amount
• one of these references matches:
  • transaction.id equals the payout balance-transaction ID
  • transaction.source.id === payout.id
  • transaction.description === "STRIPE PAYOUT"

If other balance transactions exist, remove the self-transaction. If it is the only transaction, retain it and invert its amount so it reconciles to the payout.

Map Main and Fee Lines

Create one main line for every normalized balance transaction:

When the expanded source contains a charge ID, append - ch_... to the description unless it already contains that charge ID.

When the classification is stripe_fee and the description begins with Radar , use stripe_radarFee.

For every balanceTransaction.fee_details entry, create a separate fee line:

Build the fee line reference as:

${transaction.id}-${fee.type}-${fee.application}

Omit the final segment when fee.application is absent. Group fee lines with the same reference and sum their amounts.

For exact compatibility, the current formula maps Stripe fee type stripe_fee to classification stripe_stripeFee.

VRPlatform resolves each classification through its configured transaction line mapping.

Add Reservation Match Hints

VRPlatform resolves the final reservation. The Stripe mapper only supplies these line-level hints:

• matchReservationConfirmationCode
• matchReservationStripeGuestRef

Read the Stripe customer ID from the first available location:

1. balanceTransaction.source.charge.customer
2. balanceTransaction.source.customer

Send it as matchReservationStripeGuestRef on the main line and its fee lines.

Merge booking metadata from lowest to highest precedence:

1. PaymentIntents for the Stripe customer
2. payout metadata
3. expanded charge metadata
4. expanded balance transaction source metadata

Resolve matchReservationConfirmationCode from the first available value:

1. confirmationCode
2. confirmation_code
3. reservationNumber
4. reservationId
5. enso_pms_booking_id
6. Lodgify BookingId
7. Guesty or Booking Automation Booking ID
8. Hospitable reservation_code
9. Reservation UID
10. Reservation ID

When metadata does not contain a reference, the current integration recognizes these formats for the active PMS:

• OwnerRez ORB..., with the ORB prefix removed
• BookingSync five-character alphanumeric references beginning with 0
• Avantio ID A<agency>-<reservation>-<suffix>
• Avantio ID <reservation>-<suffix>
• Hostaway Reservation Id: <number>
• Uplisting Uplisting booking ID: <number>
• Uplisting Uplisting booking: <number>

For fee lines, parse the parent balance transaction description. This lets a processing fee carry the same reservation hint as its charge.

Match the Destination Bank Account

When payout.destination is an expanded Stripe bank account, send destination.last4 as matchBankAccountLast4.

Omit the field when the destination is absent, unexpanded, deleted, or a different destination type. Do not use guest card digits: the match identifies the bank account receiving the payout.

Validate and Submit

Sum every main line and fee line, then compare the result with payout.amount. Do not submit the payout when the required balance transaction is missing, no lines can be created, or the amounts differ.

charge amount:       10000
Stripe fee:           -320
deposit total:        9680
Stripe payout.amount: 9680

Submit the deposit through the normal transaction batch operation:

POST https://api.vrplatform.app/transactions/batch
Content-Type: application/json

Use the payout ID as the transaction uniqueRef. Reusing that value for the same payout updates the connection-scoped transaction instead of creating a second deposit.

The end-to-end example shows the shortened Stripe input, generated transaction batch request, and expected response.

Implementation Checklist

• Use the Stripe payout as the deposit boundary.
• Collect every balance transaction assigned to that payout.
• Remove or normalize the payout self-transaction.
• Create gross transaction lines and separate negative fee lines.
• Preserve Stripe integer minor units.
• Populate reservation match hints only when Stripe contains the required data.
• Use destination bank account last four digits only for an expanded bank account.
• Require the deposit lines to equal the payout amount exactly.
• Use the payout ID as the transaction uniqueRef.

Related

• Batch imports
• Transaction batch reference
• Transactions

End-to-End Example

This example combines the relevant fields returned by the Stripe payout, balance-transaction, and PaymentIntent calls. Unused Stripe fields are omitted.

Shortened Stripe Input

{
  "payout": {
    "id": "po_123",
    "object": "payout",
    "amount": 9680,
    "created": 1784194200,
    "currency": "usd",
    "description": "Stripe payout",
    "automatic": true,
    "balance_transaction": "txn_payout",
    "metadata": {},
    "destination": {
      "id": "ba_123",
      "object": "bank_account",
      "bank_name": "Stripe Test Bank",
      "currency": "usd",
      "last4": "6789"
    }
  },
  "balanceTransactions": [
    {
      "id": "txn_123",
      "object": "balance_transaction",
      "amount": 10000,
      "fee": 320,
      "net": 9680,
      "currency": "usd",
      "description": "Booking payment",
      "reporting_category": "charge",
      "type": "charge",
      "fee_details": [
        {
          "amount": 320,
          "currency": "usd",
          "description": "Stripe processing fee",
          "type": "stripe_fee",
          "application": null
        }
      ],
      "source": {
        "id": "py_123",
        "customer": "cus_123",
        "payment_intent": "pi_123",
        "metadata": {},
        "charge": {
          "id": "ch_123",
          "customer": "cus_123",
          "metadata": {
            "confirmationCode": "ABC123"
          }
        }
      }
    },
    {
      "id": "txn_payout",
      "object": "balance_transaction",
      "amount": -9680,
      "net": -9680,
      "currency": "usd",
      "description": "STRIPE PAYOUT",
      "reporting_category": "payout",
      "type": "payout",
      "fee_details": [],
      "source": {
        "id": "po_123"
      }
    }
  ],
  "paymentIntentsForCustomer": [
    {
      "id": "pi_123",
      "customer": "cus_123",
      "metadata": {
        "confirmationCode": "ABC123"
      }
    }
  ]
}

The mapper removes txn_payout because it is the payout self-transaction. It then creates a 10000-cent main line and a -320-cent fee line. Their sum is 9680, which exactly matches payout.amount.

Generated VRPlatform Request

POST https://api.vrplatform.app/transactions/batch
Content-Type: application/json

{
  "connectionId": "00000000-0000-0000-0000-000000000002",
  "data": [
    {
      "type": "deposit",
      "currency": "usd",
      "date": "2026-07-16",
      "description": "Stripe payout",
      "uniqueRef": "po_123",
      "matchBankAccountLast4": "6789",
      "lines": [
        {
          "uniqueRef": "txn_123",
          "amount": 10000,
          "description": "Booking payment - ch_123",
          "matchReservationConfirmationCode": "ABC123",
          "matchReservationStripeGuestRef": "cus_123",
          "matchLineTypeClassification": "stripe_charge"
        },
        {
          "uniqueRef": "txn_123-stripe_fee",
          "amount": -320,
          "description": "Stripe processing fee - ch_123",
          "matchReservationConfirmationCode": "ABC123",
          "matchReservationStripeGuestRef": "cus_123",
          "matchLineTypeClassification": "stripe_stripeFee"
        }
      ]
    }
  ]
}

Expected API Response

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "uniqueRef": "po_123",
      "sourceId": null
    }
  ],
  "issues": []
}