Card Payments

Take card payments through the API

To use this capability, add octo/cardPayments to your Octo-Capabilities header.

This capability allows you to accept card payments via the API.

Gateway IDs returned/accepted in source are:

• adyen

• external

Endpoints

All paths below are under /octo.

This capability extends booking/order/gift write flows and related read flows documented in:

• Bookings

• Multi-Booking Cart

• Gift Vouchers

List routes intentionally omit cardPayment/returnUrl.

Get Card Payment

get

Returns the cached card payment payload for a previously created card payment object.

Path parameters

cardPaymentIdstringRequired

Card payment identifier returned in booking/order/gift responses.

Example: cp_20260514_42ad10

Responses

200

Successful response

application/json

From capability octo/cardPayments.

idstring · uuidOptional

Unique identifier for this resource.

Example: 3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7

cardPaymentIdstringOptional

Card payment identifier.

Example: cp_20260514_42ad10

gatewaystring · enumOptional

Gateway identifier.

Example: adyenPossible values:

sourcestring · enumOptional

Source value.

Example: POSPossible values:

paidintegerOptional

Paid numeric value.

Example: 2

totalPaidintegerOptional

Total paid numeric value.

Example: 2

totalRefundedintegerOptional

Total refunded numeric value.

Example: 2

paidSurchargeintegerOptional

Paid surcharge numeric value.

Example: 2

balanceintegerOptional

Balance numeric value.

Example: 2

surchargeintegerOptional

Surcharge numeric value.

Example: 2

outstandingBalanceintegerOptional

Outstanding balance numeric value.

Example: 2

amountnumber · floatOptional

Amount numeric value.

Example: 220

currencystringOptional

ISO 4217 currency code.

Example: USD

currencyPrecisionintegerOptional

Number of decimal places for currency amounts.

Example: 2

statusstringRequired

Current status value.

Example: CONFIRMED

externalobjectOptional

External object.

providerstring · enum · nullableOptional

Provider value.

Example: adyenPossible values:

providerReferencestring · nullableOptional

Provider reference value.

Example: PROV-REF-2026-001

createdAtstring · date-time · nullableOptional

Created at timestamp in ISO 8601 format.

Example: 2026-05-14T13:00:00Z

get

/card_payments/{cardPaymentId}

HTTPcURLJavaScriptPython

GET /octo/card_payments/{cardPaymentId} HTTP/1.1
Host: api.ventrata.com
Accept: */*

200

Successful response

{
  "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
  "cardPaymentId": "cp_20260514_42ad10",
  "gateway": "adyen",
  "source": "POS",
  "paid": 2,
  "totalPaid": 2,
  "totalRefunded": 2,
  "paidSurcharge": 2,
  "balance": 2,
  "surcharge": 2,
  "outstandingBalance": 2,
  "amount": 220,
  "currency": "USD",
  "currencyPrecision": 2,
  "status": "CONFIRMED",
  "reusableCards": [
    {
      "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "brand": "visa",
      "bin": "411111",
      "last4": "1111",
      "expMonth": 2,
      "expYear": 2
    }
  ],
  "adyen": {
    "environment": "test",
    "clientKey": "test_client_key_123",
    "session": {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "sessionData": "session_data_payload"
    },
    "countryCode": "US",
    "paymentMethodsConfiguration": {}
  },
  "external": {},
  "provider": "adyen",
  "providerReference": "PROV-REF-2026-001",
  "createdAt": "2026-05-14T13:00:00Z"
}

Validation rules from source:

• cardPayment.source must be one of POS, ECOM, MOTO (GATEWAY_INVALID_SOURCE otherwise).

• cardPayment.currency must match the order currency (GATEWAY_CURRENCY_MISMATCH otherwise).

• If cardPayment.cardId is supplied it must reference a reusable card on the selected gateway (INVALID_CARD_ID otherwise).

• If an explicit gateway is supplied and does not match the resolved gateway, source raises GATEWAY_MISMATCH.

Response Fields

All card payment request/response fields (including reusableCards[] and gateway payloads) are included on the card payment schemas in this page.

Notes:

• adyen can return {} when amount <= 0.

• The card payment lookup endpoint returns cached card payment JSON (up to 1 hour) and is only available when the card payment object was created with a returnUrl.

Adyen Gateway

Build your integration | Adyen Docsdocs.adyen.com

Adyen Drop-in Integration Docs

session is null until you set a returnUrl (for ECOM payments).

When you confirm/replay payment, source accepts:

• adyen.sessionId

• adyen.sessionResult (optional with sessionId)

• adyen.pspReference

• adyen.paymentMethod

• adyen.channel

For Adyen session creation, channel is resolved from the adyen-channel request header first, then cardPayment.adyen.channel, then defaults to Web.

Most integrations send this payload on the booking/order/gift confirm route that finalizes payment.

If Ventrata has not yet received the webhook notification from Adyen then you may receive a PAYMENT_PENDING error code. Repeat the request. If the payment is refused, you get a BAD_REQUEST error with the reason in errorMessage.

External Gateway

The external gateway lets you register a virtual card payment taken on an external processor.

external.approved defaults to true when omitted. For external payload processing, source requires at least one of notes, amount, currency, or cancel to be present.

Reusable Cards

Reusable card fields are included in the ReusableCard schema.

Schema Additions (JSON)

These are additive fragments showing only fields introduced by this capability.

Booking

{
  "// ...rest of booking object": "...",
  "cardPayment": {
    "status": "CONFIRMED",
    "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
    "cardPaymentId": "cp_20260514_42ad10",
    "gateway": "adyen",
    "source": "POS",
    "paid": 2200,
    "totalPaid": 2200,
    "totalRefunded": 0,
    "paidSurcharge": 0,
    "balance": 0,
    "surcharge": 0,
    "outstandingBalance": 0,
    "amount": 2200,
    "currency": "USD",
    "currencyPrecision": 2,
    "reusableCards": [
      {
        "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
        "brand": "visa",
        "bin": "411111",
        "last4": "1111"
      }
    ],
    "adyen": {
      "environment": "test",
      "clientKey": "test_client_key_123",
      "session": {
        "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
        "sessionData": "session_data_payload"
      },
      "countryCode": "US"
    },
    "external": {},
    "provider": "adyen",
    "providerReference": "PROV-REF-2026-001",
    "createdAt": "2026-05-14T13:00:00Z"
  },
  "returnUrl": "https://checkout.city-sightseeing.com/return"
}

BookingWriteRequest

{
  "// ...rest of booking write request object": "...",
  "cardPayment": {
    "gateway": "adyen"
  },
  "returnUrl": "https://checkout.city-sightseeing.com/return"
}

Error

{
  "// ...rest of error object": "...",
  "cardPaymentId": "cp_20260514_42ad10"
}

Gift

{
  "// ...rest of gift object": "...",
  "cardPayment": {
    "id": "f1a5d2e8-8d57-4f0b-9c3f-6a12d7a8bc90",
    "gateway": "external",
    "status": "PENDING"
  },
  "returnUrl": "https://checkout.city-sightseeing.com/return"
}

GiftCreateRequest

{
  "// ...rest of gift create request object": "...",
  "cardPayment": {
    "gateway": "external",
    "external": {
      "approved": true
    }
  },
  "returnUrl": "https://checkout.city-sightseeing.com/return"
}

Order

{
  "// ...rest of order object": "...",
  "cardPayment": {
    "id": "f1a5d2e8-8d57-4f0b-9c3f-6a12d7a8bc90",
    "gateway": "adyen",
    "status": "PENDING"
  },
  "returnUrl": "https://checkout.city-sightseeing.com/return"
}

OrderCreateRequest

{
  "// ...rest of order create request object": "...",
  "cardPayment": {
    "gateway": "adyen"
  },
  "returnUrl": "https://checkout.city-sightseeing.com/return"
}

OrderUpdateRequest

{
  "// ...rest of order update request object": "...",
  "cardPayment": {
    "gateway": "adyen"
  },
  "returnUrl": "https://checkout.city-sightseeing.com/return"
}