API

createPayment

C'est la mutation principale du flux de paiement. Elle est utile pour créer un paiement chez Hero.

Exemple

mutation {
  createPayment(
    payment: {
      amount: 5000
      redirectUri: "https://shop.hero.fr?shop-payment-id=abc567"
      type: Pay1X
      issuer: {
        address: {
          line1: "10 Something Street"
          line2: "2nd door on the left"
          city: "Paris"
          zipCode: "75001"
        }
        deliveryAddress: {
          line1: "2 High Street"
          line2: "Apartment 2"
          city: "Paris"
          zipCode: "75010"
        }
        name: "Super Corp"
        contactEmail: "laura@example.com"
        contactPhone: "+330600000000"
        customerReference: "<Votre identifiant client>"
      }
    }
  ) {
    id
  }
}

Arguments

La mutation createPayment prend un argument de type NewPayment

Argument	Type	Description	Obligatoire
amount	Int	Le montant total du paiement. Il doit être en centimes d'euros. ex: 5000 pour un paiement de 50€.	oui
redirectUri	String	L'URI où hero notifiera votre système. C'est aussi l'URI où Hero redirigera votre client lorsque le paiement est terminé. Cette URI ne doit pas être protégée par un système d'authentification. Il est recommandé d'inclure l'ID unique de la commande dedans.	oui
comebackUri	String	L'URI permettant au client de retourner à votre sélection de méthode de paiement. Si vous ne la fournissez pas, le client sera redirigé vers la dernière page visitée en cliquant sur le bouton "Revenir au site marchand" (en bas de la page de paiement Hero).	non
type	Enum	Le type de paiement choisi. Veuillez renvoyer la valeur reçue par avalaiblePaymentTypes.	oui
issuer	Object	Informations sur votre client.	oui
issuer.address	Object	Adresse de facturation du client	oui
issuer.address.line1	String	Adresse de facturation du client - Première ligne	oui
issuer.address.line2	String	Adresse de facturation du client - Deuxième ligne	non
issuer.address.city	String	Adresse de facturation du client - Ville	oui
issuer.address.zipCode	String	Adresse de facturation du client - Code postal	oui
issuer.deliveryAddress	Object	Adresse de livraison du client	non
issuer.deliveryAddress.line1	String	Adresse de livraison du client - Première ligne	oui
issuer.deliveryAddress.line2	String	Adresse de livraison du client - Deuxième ligne	non
issuer.deliveryAddress.city	String	Adresse de livraison du client - Ville	oui
issuer.deliveryAddress.zipCode	String	Adresse de livraison du client - Code postal	oui
issuer.name	String	Nom de l'entreprise du client	oui
issuer.contactEmail	String	Email du client	oui
issuer.contactPhone	String	Numéro de téléphone du client	oui
issuer.customerReference	String	L'identifiant unique que vous utilisez pour ce client.	non

Réponse

Lorsque le paiement est créé, l'API renvoie l'identifiant du paiement. Vous devriez sauvegarder cet ID quelque part pour pouvoir rediriger le client vers la page de paiement Hero à cette URL : https://pay.heropay.eu/checkout/XXXXX où XXX est le payment_id (en production). En environnement de staging, l'URL serait https://staging.pay.heropay.eu/checkout/XXX

Erreurs

createPayment peut échouer pour plusieurs raisons. Voici la liste des erreurs les plus courantes et leurs explications.

errorCode	Type d'erreur	Description
NOT_LOGGED	Error	L'Api-Key est manquante ou invalide.
MERCHANT_PRODUCT_DISABLED	Error	Le compte que vous utilisez n'est pas autorisé à être payé. Contactez votre administrateur Hero.
INVALID_PAYMENT_TYPE	Error	Le type de paiement est invalide. Vérifiez votre requête et assurez-vous que votre compte Hero est correctement configuré par notre équipe.
Amount XX is smaller than paymentMin YY	Error	Le montant est inférieur à votre montant de paiement minimum autorisé. Si vous pensez que ce n'est pas le cas, contactez votre administrateur Hero.
Amount XX is bigger than paymentMax YY	Error	Le montant est supérieur à votre montant de paiement maximum autorisé. Si vous pensez que ce n'est pas le cas, contactez votre administrateur Hero.

getPaymentsInfos

Vous pouvez appeler ce point de terminaison lorsque vous avez besoin de connaître les dernières informations d'un ou plusieurs paiements, comme savoir si le paiement a été finalisé ou le montant remboursé du paiement.

Exemple

query {
  getPaymentsInfos(paymentIds: ["payment_id_1", "payment_id_2"]) {
    ... on GetPaymentsInfosResult {
      result {
        paymentId
        isSuccess
        error
        reviewStatus
        reason
        initialPaymentAmount
        pendingRefundAmount
        refundedAmount
      }
    }
    ... on ValidationErrors {
      validationErrors {
        path
        validationError
      }
    }
  }
}

Arguments

Ce point de terminaison prend un argument. L'ID ou les IDs du/des paiement(s) dont vous souhaitez obtenir les informations.

Argument	Type	Description	Obligatoire
paymentIds	Array de chaînes	Le(s) `payment_id` du/des paiement(s).	oui

Réponse

La réponse sera un tableau d'objets pour chaque payment_id passé. Seuls les payment_id existants seront retournés avec les informations suivantes. Si aucun des payment_id n'existe, le résultat sera un tableau vide.

Veuillez consulter le flux de paiement pour plus d'informations sur chaque statut et sa signification.

Champ	Type	Description	Nullable
paymentId	string	L'identifiant du paiement	non
isSuccess	booléen	Indique si le paiement a été finalisé ou non.	non
error	string	Le paiement n'a pas été finalisé. Ne validez pas la commande.	oui
reviewStatus	entier	Le statut de l'examen des risques. Non utilisé pour notre solution de traitement.	non
reason	entier	La raison du statut d'examen des risques. Non utilisé pour notre solution de traitement.	oui
initialPaymentAmount	entier	Le montant initial du paiement.	non
pendingRefundAmount	entier	La somme des montants de remboursement en cours de traitement.	non
refundedAmount	entier	La somme de tous les montants de remboursement réussis pour ce paiement.	non

Exemple d'une réponse :

Succès :

{
  "result": [
    {
      "paymentId": "payment_id_1",
      "isSuccess": true,
      "error": undefined,
      "reviewStatus": "ACCEPTED",
      "reason": "",
      "initialPaymentAmount": 8000,
      "pendingRefundAmount": 0,
      "refundedAmount": 0
    },
    {
      "paymentId": "payment_id_2",
      "isSuccess": false,
      "error": "PAYMENT_NOT_INITIATED",
      "reviewStatus": "NONE",
      "reason": "None",
      "initialPaymentAmount": 5000,
      "pendingRefundAmount": 0,
      "refundedAmount": 0
    }
  ]
}

Erreur :

{
  "result": []
}

attention

Lorsqu'il y a une erreur la commande ne doit pas être validée ! Le client doit être informé que sa commande a échoué et que le paiement n'a pas été finalisé.

setOrderId

Cette requête vous donne la possibilité de définir l'ID de commande pour un paiement initié.

Exemple

mutation {
  setOrderId(paymentId: "payé123", orderId: "order123")
}

Arguments

Argument	Type	Description	Obligatoire
paymentId	String	Le `payment_id` du paiement.	oui
orderId	String	L'orderId que vous souhaitez lier au paiement. C'est une chaîne qui représente la commande dans votre système.	oui

Réponse

La réponse est toujours true.

refundPaymentCheckout

Lorsque vous devez annuler une transaction, vous pouvez utiliser ce point de terminaison et nous nous occuperons du processus de remboursement pour vous. Cela vous permet de rembourser des transactions spécifiques de paiement checkout.

Exemple

mutation {
  refundPaymentCheckout(
    input: {
      paymentCheckoutId: "paycheckout-6cd6e21d-c35e-4ee3-8b86-965fb3b44c99"
      amount: 30000
    }
  ) {
    ... on RefundPaymentCheckoutOutput {
      success
    }
    ... on GqlHeroError {
      errorCode
      message
    }
    ... on ValidationErrors {
      validationErrors {
        path
        validationError
      }
    }
  }
}

Arguments

Ce point de terminaison prend un objet d'entrée avec les propriétés suivantes :

Propriété	Type	Description	Obligatoire
paymentCheckoutId	String	L'ID du paiement checkout à rembourser	oui
amount	Integer	Le montant à rembourser en centimes	oui

Réponse

Champ	Type	Description	Nullable
success	Booléen	Indique si le remboursement a réussi	non

Exemple d'une réponse réussie :

{
  "data": {
    "refundPaymentCheckout": {
      "success": true
    }
  }
}

Erreurs

Le processus de remboursement peut échouer pour diverses raisons. Le resolver retourne différents types d'erreurs :

Erreurs de validation

Se produit lorsque la validation de l'entrée échoue.

{
  "data": {
    "refundPaymentCheckout": {
      "validationErrors": [
        {
          "path": ["amount"],
          "validationError": "Le montant doit être un nombre positif"
        }
      ]
    }
  }
}

Erreurs fonctionnelles

Ces erreurs sont liées aux règles métier et aux opérations :

Code d'erreur	Description
UNAUTHORIZED	Vous n'avez pas la permission d'effectuer cette action
FUNCTIONAL_ERROR	Diverses violations de règles métier, notamment :
	- INVALID_AMOUNT : Le montant est invalide (doit être positif et ne pas dépasser le montant original du paiement)
	- INVALID_PAYMENT_CHECKOUT : Le paiement checkout n'existe pas
	- DRAFT_PAYMENT_CHECKOUT : Impossible de rembourser un paiement checkout en brouillon
	- BA_NOT_FOUND : Compte professionnel non trouvé
	- BA_ONBOARDING_IS_NOT_COMPLETED : L'onboarding du compte professionnel n'est pas terminé
	- BA_BALANCE_INSUFFICIENT : Fonds insuffisants sur le compte professionnel
	- BA_CANNOT_TRANSFER_FUNDS : Impossible de transférer des fonds depuis le compte professionnel
	- AMOUNT_TOO_LOW : Le montant de remboursement doit être d'au moins 1 centime
	- AMOUNT_TOO_HIGH : Le montant de remboursement dépasse le montant remboursable
	- LEDGER_BALANCE_TOO_LOW : Solde insuffisant dans le compte du grand livre
	- REFUND_IS_FROZEN : Le paiement est actuellement gelé et ne peut pas être remboursé
	- PAYMENT_NOT_STARTED : Impossible de rembourser un paiement qui n'a pas été initié

Erreurs techniques

Ce sont des erreurs système internes qui peuvent survenir :

Code d'erreur	Description
INTERNAL_SERVER_ERROR	Une erreur technique s'est produite lors du traitement
CORE_PAYMENT_REFUND_FAILED	Une erreur s'est produite dans le système de traitement des paiements

Exemple d'une réponse d'erreur :

{
  "data": {
    "refundPaymentCheckout": {
      "errorCode": "FUNCTIONAL_ERROR",
      "message": "AMOUNT_TOO_HIGH"
    }
  }
}

createPayment​

Exemple​

Arguments​

Réponse​

Erreurs​

getPaymentsInfos​

Exemple​

Arguments​

Réponse​

setOrderId​

Exemple​

Arguments​

Réponse​

refundPaymentCheckout​

Exemple​

Arguments​

Réponse​

Exemple d'une réponse réussie :​

Erreurs​

Erreurs de validation​

Erreurs fonctionnelles​

Erreurs techniques​

Exemple d'une réponse d'erreur :​

createPayment

Exemple

Arguments

Réponse

Erreurs

getPaymentsInfos

Exemple

Arguments

Réponse

setOrderId

Exemple

Arguments

Réponse

refundPaymentCheckout

Exemple

Arguments

Réponse

Exemple d'une réponse réussie :

Erreurs

Erreurs de validation

Erreurs fonctionnelles

Erreurs techniques

Exemple d'une réponse d'erreur :