Page de paiement hébergée (HPP)

La page de paiement hébergée (HPP) est le formulaire de paiement conforme PCI DSS de Cost+. Elle vous permet d'accepter des paiements sans manipuler de données de carte sensibles sur vos propres serveurs. Vous créez une commande via l'API, redirigez le client vers la page hébergée, et il revient sur votre site après le paiement.

Fonctionnement

Votre serveur crée une commande en appelant POST /v1/orders/.
L'API renvoie une URL pointant vers la page de paiement hébergée.
Vous redirigez le client vers la page de paiement.
Le client finalise le paiement sur la page hébergée Cost+.
Le client est redirigé vers votre return_url (ou failure_url en cas d'échec du paiement).
Cost+ envoie une notification webhook à votre webhook_url avec le statut de la commande.

La page de paiement hébergée est entièrement conforme PCI DSS. Vous n'avez jamais besoin de manipuler des numéros de carte bruts ou des données de paiement sensibles sur vos serveurs.

Créer une commande

Il existe deux approches pour utiliser la HPP :

Approche 1 : Afficher toutes les méthodes de paiement (la plus simple)

Créez une commande sans spécifier transactions. La réponse inclut une order_url — le client y est redirigé et voit toutes les méthodes de paiement activées pour votre compte :

Requête

{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

Réponse

{
  "id": "43114fde-da30-4115-8004-b7f808f9b25c",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "order_url": "https://api.costplus.online/pay/43114fde.../select-payment-method/",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

Redirigez le client vers l'order_url. Sur la page hébergée, toutes les méthodes de paiement activées sont affichées.

Approche 2 : Présélectionner les méthodes de paiement

Créez une commande avec un tableau transactions pour contrôler quelles méthodes de paiement apparaissent et dans quel ordre. Chaque transaction inclut un payment_method, et la réponse renvoie un payment_url dans l'objet transaction :

Requête

{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    { "payment_method": "credit-card" }
  ]
}

Réponse

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "payment_url": "https://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f.../"
    }
  ]
}

Redirigez le client vers le payment_url de la transaction.

Si vous fournissez une seule entrée dans le tableau transactions, le client est dirigé directement vers cette méthode de paiement sans voir d'écran de sélection. Le tableau flags contient "is-test" lors de l'utilisation d'une clé API sandbox.

Champs de la requête

Champ	Obligatoire	Description
`currency`	Oui	Code devise ISO 4217 (ex. `EUR`, `GBP`, `SEK`)
`amount`	Oui	Montant dans l'unité mineure ISO 4217 de la devise. Par exemple, 12,95 EUR est représenté par `1295`.
`merchant_order_id`	Non	Votre propre identifiant de référence pour la commande
`return_url`	Non	URL de redirection du client après le paiement (par défaut pour tous les statuts)
`failure_url`	Non	URL de redirection du client en cas de statut `cancelled`, `expired` ou `error` (voir URLs de retour ci-dessous)
`locale`	Non	Langue de la page de paiement. Valeurs supportées : `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Non	Description de la commande, affichée au client
`payment_methods`	Non	Filtrez sur un seul mode de paiement (par exemple `["credit-card"]`). Omettre pour afficher toutes les méthodes activées. Pour plusieurs méthodes spécifiques, utilisez plutôt le tableau `transactions`
`webhook_url`	Non	URL pour recevoir les notifications de changement de statut
`expiration_period`	Non	Durée ISO 8601 pour l'expiration de la commande. Par défaut `PT30M` (30 minutes)

Le champ amount est toujours un entier dans l'unité mineure ISO 4217 de la devise. Pour EUR, 1295 signifie 12,95 EUR ; Les devises à zéro et à trois décimales utilisent leur propre exposant ISO 4217. La transmission d'une valeur décimale telle que 1295.00 ou 12.95 entraînera une erreur ou une charge incorrecte.

Méthodes de paiement multiples

Il existe deux manières de contrôler les modes de paiement qui apparaissent sur la page hébergée :

Option A — payment_methods (filtre unique). Transmettez un tableau à un seul élément pour limiter la commande à un seul mode de paiement. Omettez entièrement le champ pour afficher toutes les méthodes activées pour votre compte.

Option B — Tableau transactions (recommandé pour plusieurs méthodes). Ajoutez une entrée par mode de paiement. Chaque transaction obtient son propre payment_url et les méthodes apparaissent par ordre de tableau sur la page hébergée :

"transactions": [
  { "payment_method": "credit-card" },
  { "payment_method": "apple-pay" }
]

Le champ payment_methods sur les commandes accepte au plus une valeur. Pour proposer plusieurs méthodes spécifiques, utilisez toujours le tableau transactions. Si vous avez besoin d'un lien réutilisable avec plusieurs méthodes de paiement, envisagez plutôt Liens de paiement, qui prennent en charge un véritable tableau payment_methods.

URLs de retour

Après le paiement, le client est redirigé en fonction du statut de la commande et des URLs fournies :

Lorsque return_url et failure_url sont définis :
- cancelled, expired ou error → le client est redirigé vers failure_url
- Tous les autres statuts → le client est redirigé vers return_url
Lorsque seul return_url est défini :
- Tous les statuts → le client est redirigé vers return_url

Utilisez failure_url pour afficher une page de nouvelle tentative ou de support en cas d'échec du paiement, tandis que return_url affiche une confirmation de commande. Si vous n'avez besoin que d'une seule destination, return_url seul suffit.

Comportement du bouton d'annulation

La page de paiement hébergée inclut un bouton d'annulation. Lorsque le client clique dessus, il est redirigé vers failure_url (si fourni) ou return_url. Le statut de la commande passera à cancelled. Vérifiez toujours le statut de la commande via l'API ou les webhooks plutôt que de vous fier uniquement à la redirection.

Points d'accès associés

Créer une commande — créer une commande de paiement et recevoir le payment_url
Obtenir une commande — vérifier le statut de la commande après le paiement

Page de paiement hébergée (HPP)

On this page