Skip to main content

Payment Service

Take payments through the partners activated on your OpenHive account: Stripe (card) and Fintecture (bank transfer).

info

No partner activated yet? Contact us.

Two ways to integrate:

  • the Payment Widget, a ready-made front-end component;
  • the Payment API, to create payment requests or build your own form.

Integration steps​

  1. Get your OAuth2 client ID and secret from OpenHive.
  2. From your backend, get an access token (POST /token, client_credentials grant).
  3. Pass the token to the widget, which loads your payment methods.
  4. Create payment requests with the same token.

For a bank transfer, the widget is optional: create the payment from your backend and send your customer the IBAN PDF returned in links.payment_iban_url.

channelWhat happens
emailOpenHive emails the link to customerContact.
smsOpenHive texts the link to customerContact.
linkNothing is sent. You get the link in links.payment_session_url.

customerContact is always required: an email for email, a phone number in E.164 format (+33612345678) for sms, either for link.

Customizing the Stripe page​

With partner: stripe, stripeParams customizes the payment page of one session. Every field is optional; anything left out keeps the Stripe Dashboard settings.

FieldChanges
customText.submitText next to the pay button
customText.afterSubmitText below the pay button
branding.logoUrlLogo at the top
branding.iconUrlSquare icon, also the favicon
branding.backgroundColorPage background, #RRGGBB
branding.buttonColorPay button, #RRGGBB
branding.borderStylepill, rounded or rectangular
branding.displayNameName at the top, instead of the business name
product.descriptionText under the product name
product.imageUrlProduct image

Texts accept **bold** and links. Logo and icon: HTTPS, JPG or PNG, under 512 KB, at least 128 × 128 px (Stripe requirements, rendering).

{
"amount": 1500,
"currency": "EUR",
"method": "credit_card",
"channel": "link",
"partner": "stripe",
"customerContact": "customer@example.com",
"orderReference": "ORD-2024-99",
"locale": "fr",
"productName": "Premium plan",
"stripeParams": {
"customText": { "submit": "By paying, you accept our [terms of sale](https://example.com/terms)." },
"branding": { "logoUrl": "https://example.com/logo.png", "buttonColor": "#FF5A39" },
"product": { "description": "12-month subscription" }
}
}

If Stripe refuses a value, the session comes back failed with Stripe's reason in errorMessage.

Payment statuses​

Read on GET /v1/payment/transactions/{uid} and sent on every webhook.

StatusMeaning
pendingCreated, not paid yet. Every payment starts here.
processingBank transfer being settled.
succeededPaid.
expiredNot paid in time.
canceledAbandoned by the customer, or transfer rejected.
failedFailed at the provider. Final.
unknownNot mapped yet: see rawStatus, and tell us.

A refused card leaves the payment pending: the customer can try another one. rawStatus holds the provider's own wording.