# Invoice Operations (/developers/invoices)



Invoices represent outstanding balances on bookings -- for example, when a customer paid a deposit at checkout and owes a remaining balance. The invoice API lets you retrieve invoice details and process payments.

getInvoice [#getinvoice]

Retrieve invoice details including the amount due, associated cart summary, and booking information.

```javascript
const result = await api.invoice.getInvoice('invoice-uuid');

if (result.success) {
  console.log('Invoice:', result.invoice.uuid);
  console.log('Due now:', result.invoice.dueNowCents, 'cents');
  console.log('Activity:', result.activity);
  console.log('Date:', result.date);
  console.log('Time:', result.start, '-', result.end);
}
```

**Parameters**

| Parameter     | Type     | Required | Description  |
| ------------- | -------- | -------- | ------------ |
| `invoiceUuid` | `string` | Yes      | Invoice UUID |

GetInvoiceResponse [#getinvoiceresponse]

| Field      | Type                         | Description                                    |
| ---------- | ---------------------------- | ---------------------------------------------- |
| `success`  | `boolean`                    | Whether the request succeeded                  |
| `invoice`  | `ServerInvoice`              | Invoice details                                |
| `cart`     | `ServerShoppingCartOverview` | Cart summary with line items, fees, and totals |
| `activity` | `string`                     | Activity name                                  |
| `date`     | `string`                     | Booking date                                   |
| `start`    | `string`                     | Start time                                     |
| `end`      | `string`                     | End time                                       |
| `endDate`  | `string`                     | End date (for multi-day bookings)              |

ServerInvoice [#serverinvoice]

| Field         | Type     | Description               |
| ------------- | -------- | ------------------------- |
| `uuid`        | `string` | Invoice unique identifier |
| `dueNowCents` | `number` | Amount due in cents       |

The `cart` field contains the full `ServerShoppingCartOverview` with all line items, fees, discounts, and payment history. See the [Cart & Checkout](/developers/cart-and-checkout) page for the full type reference.

***

payInvoice [#payinvoice]

Pay an outstanding invoice. Like checkout, this requires a Stripe confirmation token and any required agreement acceptances.

```javascript
const result = await api.invoice.payInvoice('invoice-uuid', {
  stripeConfirmationToken: 'tok_xxx',
  agreements: ['agreement-uuid-1']
});

if (result.success) {
  console.log('Payment confirmed:', result.confirmation);
} else if (result.clientSecret) {
  // Stripe requires additional action (3D Secure, etc.)
  console.log('Additional verification needed');
}
```

**Parameters**

| Parameter     | Type                | Required | Description     |
| ------------- | ------------------- | -------- | --------------- |
| `invoiceUuid` | `string`            | Yes      | Invoice UUID    |
| `request`     | `PayInvoiceRequest` | Yes      | Payment details |

PayInvoiceRequest [#payinvoicerequest]

| Field                     | Type       | Required | Description                                      |
| ------------------------- | ---------- | -------- | ------------------------------------------------ |
| `stripeConfirmationToken` | `string`   | No       | Stripe confirmation token from Stripe.js         |
| `agreements`              | `string[]` | No       | UUIDs of accepted agreements                     |
| `handledNextAction`       | `string`   | No       | Stripe PaymentIntent ID after handling 3D Secure |

PayInvoiceResponse [#payinvoiceresponse]

| Field          | Type      | Description                                             |
| -------------- | --------- | ------------------------------------------------------- |
| `success`      | `boolean` | Whether payment succeeded                               |
| `confirmation` | `string`  | Payment confirmation number                             |
| `clientSecret` | `string`  | Stripe client secret (if additional action is required) |

***

Invoice Payment Flow [#invoice-payment-flow]

A typical invoice payment follows this sequence:

1. **Retrieve the invoice** to display the amount due and booking details.
2. **Collect payment** using Stripe Elements or your payment form.
3. **Submit payment** with the Stripe token.
4. **Handle 3D Secure** if the response includes a `clientSecret` instead of a `confirmation`.

```
getInvoice(uuid)
    |
    v
Display amount, booking details
    |
    v
Collect Stripe payment token
    |
    v
payInvoice(uuid, { stripeConfirmationToken })
    |
    +---> success + confirmation  --> Done
    |
    +---> clientSecret returned   --> Handle 3D Secure with Stripe.js
                                       |
                                       v
                                  payInvoice(uuid, { handledNextAction: paymentIntentId })
                                       |
                                       v
                                  success + confirmation --> Done
```

***

Full Example [#full-example]

```javascript
const api = new ResytechApi();
await api.initialization.initialize({ identifier: 'invoice-payment' });

// Invoice UUID typically comes from an email link or dashboard
const invoiceUuid = 'inv-abc-123';

// 1. Load invoice details
const invoiceResult = await api.invoice.getInvoice(invoiceUuid);

if (!invoiceResult.success) {
  console.error('Invoice not found:', invoiceResult.message);
  return;
}

const { invoice, cart, activity, date, start, end } = invoiceResult;

// Display to customer
console.log(`Invoice for: ${activity}`);
console.log(`Booking: ${date} ${start} - ${end}`);
console.log(`Amount due: $${(invoice.dueNowCents / 100).toFixed(2)}`);

if (cart) {
  console.log('Line items:');
  cart.lineItems?.forEach(item => {
    console.log(`  ${item.name}: $${item.price}`);
  });
  console.log('Fees:');
  cart.fees?.forEach(fee => {
    console.log(`  ${fee.name}: $${fee.amount}`);
  });
}

// 2. Collect payment via Stripe.js (in your UI)
//    const { token } = await stripe.createToken(cardElement);

// 3. Pay the invoice
const payResult = await api.invoice.payInvoice(invoiceUuid, {
  stripeConfirmationToken: 'tok_from_stripe_js',
  agreements: [] // include any required agreement UUIDs
});

if (payResult.success) {
  console.log('Payment complete! Confirmation:', payResult.confirmation);
} else if (payResult.clientSecret) {
  // 4. Handle 3D Secure
  //    const { paymentIntent } = await stripe.handleNextAction({
  //      clientSecret: payResult.clientSecret
  //    });

  // 5. Retry with handled action
  const retryResult = await api.invoice.payInvoice(invoiceUuid, {
    handledNextAction: 'pi_payment_intent_id'
  });

  if (retryResult.success) {
    console.log('Payment verified! Confirmation:', retryResult.confirmation);
  } else {
    console.error('Payment failed:', retryResult.message);
  }
} else {
  console.error('Payment failed:', payResult.message);
}
```