Pre-auth and Tokenisation in OHIP

Overview

• The card token, written to the reservation's payment methods in OPERA with cardOrToken set to Token, the masked card number (12 X characters followed by the last 4 digits), the expiration date, and the card type code you mapped in your connection settings.
• The pre-authorization approval code, registered in OPERA as a manual authorization for the amount Duve already authorized at the PSP.

Use cases

• A guest completes online check-in in Duve and pays for the stay. The front desk needs the card on the OPERA reservation so the remaining balance or incidentals can be settled at the desk.
• You take a pre-authorization hold for incidentals in Duve before arrival, and you want that hold to appear in OPERA as a registered authorization instead of the property placing a duplicate hold on the same card.
• You sell upsells such as early check-in, late check-out, or room upgrades in Duve, and want the card that paid for them available in OPERA.
• A hold you placed before arrival expires or is reversed by the PSP, and the front desk needs to know before check-in that the card is no longer authorized.

Before you start

• Confirm your payment provider in Duve is one of the seven supported providers listed above.
• Confirm the guest folio window number in the OHIP connection settings. The token and the authorization are attached to that folio window, and window 1 is used if the field is left empty.

How to set it up

1. Open the PMS connection settings for the OHIP source in Duve.
2. Scroll to the OHIP configuration fields. These options only appear after the connection has been created, so if you are creating the source right now, save it first and come back.
3. Turn on Push CC token via API. This is the master switch for sending the card token and the pre-authorization approval code to OPERA. It is off by default.
4. Optionally turn on Push additional hold if you also want Duve to register additional incidental holds in OPERA as manual authorizations.
5. Check that the card type identifier fields and the guest folio window number are filled in as described above.
6. Save the connection settings.

Host experience

• If you collect payment immediately, the card that paid is tokenized and pushed to the OPERA reservation, along with the masked card number, expiration date, card type code, folio window, and the authorized amount and currency.
• If you use "Authorize & hold payment", the hold Duve takes at your payment provider is the pre-authorization that gets registered in OPERA against that card, rather than the property placing its own hold.
• If you request an additional hold for incidentals "With zero amount", the guest's card is tokenized without being charged. That token is still pushed, and the payload simply carries no amount, which is why a hold order with no amount is allowed through.
• If you request an additional hold for a specific amount, turning on Push additional hold registers that authorization in OPERA too.

• In Duve, the reservation/order logs whether the token push succeeded or failed, with the last 4 digits of the card.
• In OPERA, the card appears as a payment method on the reservation, attached to the guest folio window configured on the connection, with the authorization registered against it.
• If the hold later ends at the payment provider, a comment and an AUTHORIZATION alert appear on the OPERA reservation so the desk knows before the guest arrives.

Guest experience

• The guest enters their card once, on the billing step of online check-in, exactly as before.
• The guest is never asked to consent to a card being sent to the PMS separately, because no card number leaves Duve. Only a token, the last 4 digits, the expiration date, and the card brand are sent.
• For a zero-amount hold, the guest sees their card saved without a charge. For "Authorize & hold payment", they see the hold amount on the billing step.
• Because the card is already on the OPERA reservation, the guest is not asked for it again at the desk, and they are not charged twice or held twice for the same amount.
• The one case where a guest may still be asked for a card at check-in is when the pre-authorization expired or was reversed at the payment provider before arrival. Duve flags this in OPERA, but the hold itself is gone, and the desk needs a live card.

Troubleshooting

• Nothing arrives in OPERA, and the timeline shows no token push entry: The most common causes are the switch being off for that source, the reservation's payment having been taken by an unsupported provider, or OPI not being active at the property. Check all three in that order.
• You just activated OPI, but Duve still skips the push: Duve caches a negative OPI result for 15 minutes. Wait and retry.
• The timeline shows a failed token push: Duve retries the call to OPERA three times with an expanding interval starting at one minute before giving up. A persistent failure usually points to the OPERA side: an invalid card type code, a folio window that does not exist on the reservation, or a rejected amount. Verify the card type identifier mapping first.
• The card reaches OPERA, but no authorization is registered against it: The authorization step needs an approval code from the PSP. Each provider reports it under a different field, and Duve reads the one belonging to the provider that processed the order. If your PSP did not return an approval code for that transaction, the token is still pushed, but no manual authorization is registered.
• The front desk sees an authorization for a hold that is no longer live: Look for the "Pre-authorization expired at payment provider" or "Pre-authorization cancelled at payment provider" comment and AUTHORIZATION alert on the OPERA reservation. Duve writes these as soon as the PSP reports the hold has ended.

Restrictions & Limitations

• The token must be a string of 30 characters or fewer. Anything longer is rejected before it is sent, which is a safeguard so a raw card number can never be pushed. For Worldline, whose own token is a 36-character UUID, Duve sends the Duve order ID as the token instead so the push fits inside the limit.
• Only Adyen, Global Blue, Stripe, Planet, Pelecard, Worldline, and Elavon are supported. An order processed by any other provider is skipped, even when the switch is on.
• A charge amount of zero, or a broken amount, blocks the push. An order with no amount at all is allowed through, because hold orders can legitimately have no amount and OPERA accepts the payload without it.
• The push happens per order and is marked as done once it succeeds, so it does not repeat on resync. The token push and the manual authorization registration are marked separately.
• The feature is per connection. If you run several OHIP sources, turn it on for each one you want it on for.
• This is a one-way push. Cards or authorizations added directly in OPERA are not pulled back into Duve.
• The pre-auth ended comment and alert are only sent for "payment for stay" and "additional hold" orders.

Tips & Tricks

• Test on a single property first. The switch is per connection, so you can validate the card type mapping and folio window on one hotel before rolling out.
• Get the card type codes from your OPERA administrator. A wrong code is the single most common reason a technically successful integration produces a rejected push.
• Use the Duve reservation/order logs as your first diagnostic. It tells you whether Duve attempted the push at all and whether OPERA accepted it, which narrows the problem to either the Duve side or the OPERA side immediately.
• If you use incidental holds, turn on Push additional hold at the same time as the token switch, so front desk staff sees the full authorization picture in OPERA rather than only the stay payment.

FAQs

Related articles: