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://pay.costplus.online/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://pay.costplus.online/4851e31c.../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 en centimes. 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	Filter to a single payment method (e.g. `["credit-card"]`). Omit to show all enabled methods. For multiple specific methods, use the `transactions` array instead
`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 exprimé dans la plus petite unité monétaire (centimes). Passer 1295 signifie 12,95 dans la devise donnée. Passer 1295.00 ou 12.95 entraînera une erreur ou un montant incorrect.

Méthodes de paiement multiples

Pour proposer plusieurs méthodes de paiement spécifiques, ajoutez plusieurs entrées au tableau transactions. L'ordre sur la page hébergée correspond à l'ordre du tableau :

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

The payment_methods field on orders accepts at most one value. To offer multiple specific methods, always use the transactions array. If you need a reusable link with multiple payment methods, consider Payment Links instead, which support a true payment_methods array.

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

On this page