Payment providers

Payments & billing › Payment providers lists every provider instance. An instance is one configured account of a provider in one environment (test or live) — for example a FastSpring test store and a FastSpring live store are two instances. The form of each instance is generated from the provider's own definition, with English and Arabic labels and help for every field. Configuring needs providers.manage, a step-up and a reason.

What needs merchant credentials#

The issuer profile, billing settings, routing, price mappings and discounts need no external credentials.

Configure an instance#

To run test and live side by side, add an instance (provider, a new instance key, environment, reason). It starts disabled.

FastSpring (card)#

In FastSpring, create a webhook with the URL shown on the instance card (the product API host followed by /api/v1/webhooks/payments/fastspring), set its HMAC SHA256 Secret, turn on webhook expansion so events carry full subscription, order and account objects, and select the events listed on the card: order.completed, order.failed, subscription.activated, subscription.charge.completed, subscription.charge.failed, subscription.payment.overdue, subscription.updated, subscription.canceled, subscription.uncanceled, subscription.deactivated, subscription.paused, subscription.resumed, return.created, payoutEntry.created.

Give each instance its own webhook secret. Webhooks are checked against every instance of the provider; with a shared secret a live event could be matched to the test instance and then ignored as an environment mismatch.

PayPal (PayPal balance, bank or card inside PayPal)#

A buyer approves the subscription on PayPal; HyoNova activates it from BILLING.SUBSCRIPTION.ACTIVATED and records each charge from PAYMENT.SALE.COMPLETED. Every webhook is verified with PayPal's signing certificate (fetched only from PayPal's API hosts) against the configured webhook ID; anything else is refused with 401. PayPal does not prorate: a plan change on a PayPal subscription is scheduled for the end of the paid period. A cancelled PayPal subscription keeps access to the end of that period, and HyoNova closes it a day later because PayPal sends no final event.

Triple-A (crypto)#

No webhook is set up in the Triple-A dashboard: HyoNova sends the notification URL and the signing secret with every payment request. The test environment uses Triple-A's sandbox.

Bank transfer (built into HyoNova)#

There is no API and no webhook: payments are confirmed by an operator (see Refunds and bank confirmations).

Stripe (disabled)#

Stripe is a complete integration kept Disabled, role available, with no route. Leave it so unless HyoNova decides to use it. If it is ever configured, its secret key must match the instance environment (test keys for test, live keys for live).

Price and discount mappings#

Card prices are sold through the provider's own catalogue. For every HyoNova price sold by card, add a mapping per environment on the price (provider, environment, the provider's product reference — a FastSpring product path or a PayPal billing plan ID). For PayPal the mappings are normally created by Create plans at the provider. A card checkout for an unmapped price is refused, and upgrades need the target price mapped too. Discount codes used with card need the provider's coupon code mapped the same way. Mappings need plans.manage.

Status#