Booking Payment Instructions

Payment instructions enables you to seamlessly pay on behalf of guests for bookings where payment is due at the hotel. A payment instruction is used to convey to the hotel card details, authorisation of what can be charged to the card, and where to send the invoice for a completed stay.

Schema

approved_charges
object

Describes what kinds of charges are approved for this payment instruction.

The accommodation should charge the provided card for all approved charges, and charge the guest for the rest.

booking_id
string

The id of the booking the payment instruction applies to

Example: "bok_0000AS0NZdKjjnnHZmSUbI"
card_id
string

The id of the payment card to use for payment.

The card must be a lodged card (created with multi_use set to true).

Example: "tcd_0000AS0NZdKjjnnHZmSUbI"
invoice
object

Describes where to send the invoice for this charge.

limit_amount
string

The limit of the approved amount. The accommodation should not charge the provided card more than this amount.

Example: "1437.55"
limit_currency
string

The currency of the limit_amount, as an ISO 4217 currency code.

Example: "USD"

Creating a booking payment instruction

Preview

This is not yet finalised. It may change, or be removed or be not yet accessible.

A payment instruction can be made for any booking where the rate has payment_instruction_allowed set to true. To create a payment instruction, you will need:

  • The booking ID of the stays booking you intend to pay for,

  • The amount and charges that the cardholder has authorised to be charged.

  • The ID for the card you wish to be used to pay for all or a portion of the stay. The card provided must be a lodged card (created with multi_use set to true).

  • The contact details for who the invoice should be issued to

Body parameters

approved_charges
objectrequired

Describes what kinds of charges are approved for this payment instruction.

The accommodation should charge the provided card for all approved charges, and charge the guest for the rest.

card_id
stringrequired

The id of the payment card to use for payment.

The card must be a lodged card (created with multi_use set to true).

Example: "tcd_0000AS0NZdKjjnnHZmSUbI"
invoice
objectrequired

Describes where to send the invoice for this charge.

limit_amount
stringrequired

The limit of the approved amount. The accommodation should not charge the provided card more than this amount.

Example: "1437.55"
limit_currency
stringrequired

The currency of the limit_amount, as an ISO 4217 currency code.

Example: "USD"

Preview

This is not yet finalised. It may change, or be removed or be not yet accessible.

Endpoint

POST https://api.duffel.com/stays/bookings/{booking_id}/payment_instructions

Request

curl -X POST --compressed "https://api.duffel.com/stays/bookings/{booking_id}/payment_instructions" \
  -H "Accept-Encoding: gzip" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Duffel-Version: v2" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
  "data": {
    "limit_currency": "USD",
    "limit_amount": "1437.55",
    "invoice": {
      "send_to": "invoice@merchant.io",
      "company_name": "Merchant",
      "address_region": "London",
      "address_postal_code": "SW1A 2AA",
      "address_line_2": "Westminster",
      "address_line_1": "10 Downing St",
      "address_country_code": "GB",
      "address_city": "London"
    },
    "card_id": "tcd_0000AS0NZdKjjnnHZmSUbI",
    "approved_charges": {
      "taxes": true,
      "other": "Parking up to $50. Food up to $20",
      "fees": true,
      "base": true
    }
  }
}'

Response

{
  "data": {
    "limit_currency": "USD",
    "limit_amount": "1437.55",
    "invoice": {
      "send_to": "invoice@merchant.io",
      "company_name": "Merchant",
      "address_region": "London",
      "address_postal_code": "SW1A 2AA",
      "address_line_2": "Westminster",
      "address_line_1": "10 Downing St",
      "address_country_code": "GB",
      "address_city": "London"
    },
    "card_id": "tcd_0000AS0NZdKjjnnHZmSUbI",
    "booking_id": "bok_0000AS0NZdKjjnnHZmSUbI",
    "approved_charges": {
      "taxes": true,
      "other": "Parking up to $50. Food up to $20",
      "fees": true,
      "base": true
    }
  }
}