Payment Service
Take payments through the partners activated on your OpenHive account: Stripe (card) and Fintecture (bank transfer).
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
- Get your OAuth2 client ID and secret from OpenHive.
- From your backend, get an access token (
POST /token,client_credentialsgrant). - Pass the token to the widget, which loads your payment methods.
- 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.
Sending the payment link
channel | What happens |
|---|---|
email | OpenHive emails the link to customerContact. |
sms | OpenHive texts the link to customerContact. |
link | Nothing 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.
| Field | Changes |
|---|---|
customText.submit | Text next to the pay button |
customText.afterSubmit | Text below the pay button |
branding.logoUrl | Logo at the top |
branding.iconUrl | Square icon, also the favicon |
branding.backgroundColor | Page background, #RRGGBB |
branding.buttonColor | Pay button, #RRGGBB |
branding.borderStyle | pill, rounded or rectangular |
branding.displayName | Name at the top, instead of the business name |
product.description | Text under the product name |
product.imageUrl | Product 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.
| Status | Meaning |
|---|---|
pending | Created, not paid yet. Every payment starts here. |
processing | Bank transfer being settled. |
succeeded | Paid. |
expired | Not paid in time. |
canceled | Abandoned by the customer, or transfer rejected. |
failed | Failed at the provider. Final. |
unknown | Not 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.