Skip to main content

Payment Service

The Payment Service allows you to connect to payment partners you activated in your OpenHive account.

info

If you didn't activate any payment partners yet, please join us at https://openhive.eu/contact to get assistance.

We offers different ways to integrate payment functionalities into your applications:

  • Using our Payment Widget component for a quick front-end integration of the available payment methods.
  • Using our Payment API to create a request to pay. You can also use it to build your own custom payment form.

Partners​

We currently support Stripe and Fintecture, but we are onboarding new partners. If you want to see a specific payment provider supported, please contact us.

You choose it on every payment request, with the channel of the payment session.

channelWhat happens
emailOpenHive takes care of getting the link to customerContact by email. links.payment_session_url comes back absent.
smsOpenHive takes care of getting the link to customerContact by SMS. links.payment_session_url comes back absent.
linkNothing is sent to your customer. The link comes back in links.payment_session_url on the create-session response, and you hand it to your customer the way you want.

With Fintecture, links.payment_iban_url comes back whatever the channel.

customerContact is required whatever the channel, link included: an email address for email, an international phone number in E.164 format (+33612345678, no spaces) for sms, either one for link. A contact that does not match its channel is rejected with a 422.

Integration Steps​

  • 1️⃣ Get your OAuth2 client ID and secret from OpenHive
  • 2️⃣ From your backend, obtain a short-lived access token from OpenHive (POST /token, client_credentials grant)
  • 3️⃣ Pass that access token to the Widget so it can load your payment methods
  • 4️⃣ Use the same token to create payment requests using our Payment API

IBAN and banking transfert​

Some partners like Fintecture allows to generate a PDF with a virtual IBAN to receive payments. If you use this payment method, the workflow could be more straightforward as you don't need to necessarily integrate the widget:

  • 1️⃣ Get your OAuth2 client ID and secret from OpenHive
  • 2️⃣ Use it to authenticate and create a payment request using our Payment API as soon as you receive an order in your system
  • 3️⃣ Fintecture will generate a PDF with a virtual IBAN and OpenHive will send it into a response into the links property. You can then send this PDF to your customer to let them proceed with the payment.

Payment statuses​

A payment carries a status, which you read on GET /v1/payment/transactions/{uid} and receive on every webhook.

StatusWhat it means
pendingThe session exists, nobody has paid yet. Every payment starts here.
processingThe bank is settling a transfer.
succeededThe money is in.
expiredNobody paid and the session timed out.
canceledThe payment was cancelled: the customer gave up, or the provider rejected the transfer.
failedThe provider reported the payment as failed.
unknownThe provider reported something OpenHive does not map yet — rawStatus carries its exact wording. Tell us if you run into one.

Every payment starts pending, and nothing follows failed. In between, the path depends on the payment method. A card payment turns succeeded as soon as the customer pays, and expired once the session times out — a card refused on the payment page leaves the payment pending, the customer is free to try another one. A bank transfer sits in processing while the bank settles it, then reaches succeeded, or failed when the bank reports an error.

Next to status, the payment also exposes rawStatus: the provider's own wording for the last update — the event type at Stripe, the status at Fintecture. Use status to drive your code, rawStatus when you need to match what the provider tells you on its side.