API Fee Connectivity Processes

All clients worldwide (except Guam until further notice) were notified about the fee coming for any API bookings even if they have not received an API booking. The steps below outline how to handle a client who starts to work with an API Partner for the first time after API fees have been launched in their region. If a request comes through for a client within a week of going live and they do not have a billing method added, please notify the OB 04.

New API Connection Request – Channel or External API (excluding GTTD)

Receiving team: Connectivity

1. First, check that the paywall is present (in Advanced Company Settings, “Enable API Booking Creation” is present) and enabled (“Enable API Booking Creation” is checked and there is an API fee rate greater than 0%).
   • If “Enable API Booking Creation” is not present and the dashboard primary location is in a monetized region, use the “Enable API Paywall” workflow in the #api-fee-global room. Apiary will be notified to enable the paywall.
2. Check that a billing method is added to the dashboard (either SEPA, ACH Debits or a card on file) and for USA/PR only, that the client accepted the API Fee (USA/PR only – “Allow API Bookings to be charged an API Fee” is checked). If not, send “Billing Method not enabled” macro in Zendesk and update status to “Requested”. Issue status – “API Fee”.
3. Make sure there is an API fee rate > 0% listed and request PayOps to update it by using the workflow “API Fee Rate Change Request” in the #payment_operations Slack channel. While the standard rate is 2%, exceptions can be granted:
   • In the US/PR, specific fees are set for clients with Paid Legacy FHS T2&3 and Hawaii T3+. See specifics here.
   • Find an exception in AppSheet, under “Approved Exceptions”. If several approved exceptions are present (look at submission date), the last submitted one is the accurate one. Example below: the latest submission will be the one to follow.
   • If no exception is present, you can expect the lead to be at the 2% standard rate.
4. If the client was connected to the API before, verify that all outstanding API Fee invoices are settled in the Payment Processing Documents section of their Dashboard.
5. Once the above is confirmed, continue with the normal process to map the company to the requested API.
6. If the client refuses to add a Billing Method, you can add the affiliate and let them know they can manually tag bookings. Make sure to NOT add API permissions to the affiliate. Mark as disabled in AT and follow the normal disable process per API.
7. If the client becomes escalated, please escalate to their AM through the #account-management channel.

Please follow the steps below to disable API integrations. DO NOT TOUCH GOOGLE, BOOKING.COM, FHDN/FHDN API AFFILIATES, AL-DESK and NON-API permissions.

• For any External API partner, Expedia, or GetYourGuide:
  • Remove permissions on the affiliate
• For Viator:
  • Log in to Viator and disconnect all products in the product connection tab.
  • Remove the connection to FH under Account -> Connectivity –> Connectivity details. Mark the disconnection reason as “Unhappy with connection.”
• Follow all the API opt out steps outlined here or use the macro “Offboard/Opt-out Check” as a checklist. For AT, use the issue status – API fee opt out.
• Uncheck Enable API Booking Creation in Advanced Company Settings. This will block API bookings and disable the Billing setup nag.
• To update the API Fee rate in Advanced Company Settings, ping the payops team using the #payment_operations room and Connectivity – API Fee Rate Change Request workflow. This workflow is only enabled for the Connectivity team, if you do not have access please ask your manager:
  • If you are processing the deactivation on the API fee effective date (Deactivation Day) and the client only used API Connectivity when it was free, the API fee rate will have been set to 0% by the Apiary team. No need to escalate to payops in this case.
  • If the client used API Connectivity while it was paid (i.e. is being deactivated for failed debits), leave the rate as is. This will ensure any outstanding fees are invoiced.
• Email the client to let them know we’ve disabled their API connections. You can use the “No Billing Method – API Disabled” macro for deactivation deadlines. At any point in time the client can check the “Allow API Bookings to be charged an API Fee” box and email us to reactivate the connection.
• Update Close to remove relevant APIs from the Connectivity – Live field.
• Update relevant Airtable record(s) with the status “Disabled” and issue status “API Fee opt out”.
  • If the client is being disconnected due to unpaid API fees, please check the Deactivation (Unpaid Invoices) column for visibility.

On the deactivation day for each region, if a client has not checked the box, we will be automatically disabling all their API connections.

Clients who previously did not enable API Connectivity, or did not add a billing method, may decide to activate the feature after we disabled their dashboard. Follow the steps below to reactivate API Connectivity.

• For Europe and APAC, navigate to the Bank & Payments > Billing section of the dashboard and confirm they have added a Billing Method (SEPA, ACH Debits or card on file). If they have not, email them asking to do so using the “Billing Method not enabled” macro in Zendesk.
• For USA and Puerto Rico, navigate to the Advanced Company Settings of the dashboard and confirm that the client accepted the new API Fee by checking the box “Allow API Bookings to be charged an API Fee”. If they have not, email them asking to do so using the “Connectivity::API Connectivity – API fee not enabled – API disabled (EN)” macro in Zendesk.
• Check that all outstanding API Fee invoices are settled in the Payment Processing Documents section of their Dashboard. Example – there should be no outstanding invoices.
  • If there are unpaid invoices, please notify the client and suggest a manual debit for outstanding fees before reconnecting. This can be requested in the #payment_operations channel using the Manual API Fee Debit Request.
  • To track the communications payops has potentially had with clients already, please search Zendesk or refer to this tracking doc. Can be escalated to AM/payops if there are ongoing and unresolved payment issues.
• Once confirmed all invoices are settled, select “Enable API Booking Creation” in advanced company settings.
  • Exceptions can be made for clients using SEPA debits as those can take up to 10 days to process. If the client is in EMEA and using SEPA, we can reconnect while there are “pending” payments to avoid further downtime.
• Make sure there is an API fee rate > 0% listed in the Advanced Company Settings. See below for steps on finding the correct fee percentage. Ping the payops team in the #payment_operations channel using the Connectivity – API Fee Rate Change Request workflow and provide the percentage for future billing.
  • If the rate in the dashboard is 0, find the correct rate as described in the New Connection Request section.

To Reconnect APIs:

• External API:
  • Re-add External API permissions on affiliates
  • The client can email their partner(s) asking them to check on the connection or reconnect the API. A list of current API Partners can be found here.
• Channel API:
  • Re-add API permissions on affiliates
    • The New Connections team will reestablish the API connection following the normal process. These connections should be reconnected on the same day or as soon as the API allows, within 24hrs.
  • Viator: send the “connect now” macro if we don’t have account access.
  • GYG: resend codes to connect to “availability only” or “availability and price”.
  • Expedia: The client can then email Expedia to get reconnected if needed.
• Submit to check if major mapping updates are made (new products added, resources changed etc.).
• No need to resubmit to check if no updates are needed in the mapping file.
• Record keeping:
  • Update Close
  • Mark client as live in AirTable
  • Remove API fee opt-out issue status
  • Update live date
  • Mark as reactivated in the Deactivation doc
• Be sure to email the client notifying them that Channel APIs are being reconnected and External APIs can be contacted to reconnect as well.

• Automatic invoices are generated on the 1st day of each month. On the 6th of each month we will debit the bank account. If the debit fails, we try again a week later up to two times per month, indefinitely until an invoice is settled.
• If a debit fails, PayOps will receive the notification and send the “API Fee Failed Bank Debit” macro to the client to inform of upcoming 2nd payment.
• Failed debit 2: PayOps receives notification, PayOps reaches out to Client as above to inform of upcoming 3rd attempt + for T3+ only, reaches out to AM in #account-management using workflow 2nd failed debit AM flag (T3-4-5 only) to get help raising the issue to the client.
• Failed debit 3: PayOps receives notification, PayOps reaches out to Client as above to inform of upcoming 4th attempt.
• Failed debit 4: PayOps receives notification but doesn’t communicate with client; instead PayOps requests disconnection to Connectivity using Workflow + tags AM.
• Connectivity disconnects client from the API following the disconnecting steps and sends macro “Connectivity::API Connectivity – API disabled – API fee debit failed”.
• If Client contacts Connectivity via email to reconnect:
• Connectivity requests Manual Debit to PayOps using the “Manual Debit Request” workflow in #payment_operations and:
  • Debit instantly successful: PayOps clicks on button “Debit Successful”, which tags Connectivity agent to reconnect client + posts a request to link debit to invoice in #payments-experience-public.
  • Debit instantly failed: PayOps clicks on button “Debit Failed”, which tags Connectivity agent to deny the request to reconnect. PayOps reaches out to client for resolution using macro “Failed Debit after API Disconnection”.
  • Debit status needs more time to update: PayOps clicks on button “Debit Pending”, which tags Connectivity agent to reconnect + inform client. PayOps to monitor status and:
    • If debit succeeds: PayOps clicks on “Debit Succeeded” in original request which will tag the Connectivity agent and post the debit ID in #payments-experience-public.
    • If debit fails: PayOps clicks on “Debit Failed”, which tags Connectivity agent to disconnect the client. PayOps reaches out to client for resolution using macro “Payment Operations:: Failed Debit after API Disconnection”.
• Further communication with client re: failed debits to be managed by PayOps.