API

createPayment

È la principale mutazione del flusso di pagamento. È utile per creare pagamenti in Hero.

Esempio

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: "<Your customer identifier>"
      }
    }
  ) {
    id
  }
}

Argomenti

La mutazione createPayment accetta un argomento di tipo NewPayment

Argomento	Tipo	Descrizione	Obbligatorio
amount	Int	L'importo totale del pagamento. Dovrebbe essere in centesimi di euro. es: 5000 per un pagamento di 50€.	sì
redirectUri	String	L'URI dove Hero notificherà il tuo sistema. È anche l'URI dove Hero reindirizzerà il tuo cliente quando il pagamento sarà completato. Questo URI non dovrebbe essere protetto da alcun sistema di autenticazione. Si consiglia di includere l'ID unico dell'ordine.	sì
comebackUri	String	L'URI che consente al cliente di tornare alla selezione del metodo di pagamento. Se non lo fornisci, il cliente verrà reindirizzato all'ultima pagina visitata quando clicca sul pulsante "Revenir au site marchand" (in fondo alla pagina di pagamento Hero).	no
type	Enum	Il tipo di pagamento scelto. Si prega di restituire il valore ricevuto da avalaiblePaymentTypes.	sì
issuer	Object	Informazioni sul tuo cliente.	sì
issuer.address	Object	Indirizzo di fatturazione del cliente	sì
issuer.address.line1	String	Indirizzo di fatturazione del cliente - Prima riga	sì
issuer.address.line2	String	Indirizzo di fatturazione del cliente - Seconda riga	no
issuer.address.city	String	Indirizzo di fatturazione del cliente - Città	sì
issuer.address.zipCode	String	Indirizzo di fatturazione del cliente - Codice postale	sì
issuer.deliveryAddress	Object	Indirizzo di consegna del cliente	no
issuer.deliveryAddress.line1	String	Indirizzo di consegna del cliente - Prima riga	sì
issuer.deliveryAddress.line2	String	Indirizzo di consegna del cliente - Seconda riga	no
issuer.deliveryAddress.city	String	Indirizzo di consegna del cliente - Città	sì
issuer.deliveryAddress.zipCode	String	Indirizzo di consegna del cliente - Codice postale	sì
issuer.name	String	Nome dell'azienda cliente	sì
issuer.contactEmail	String	Email del cliente	sì
issuer.contactPhone	String	Numero di telefono del cliente	sì
issuer.customerReference	String	L'identificatore univoco che utilizzi per questo cliente.	no

Risposta

Quando il pagamento viene creato, l'API restituisce l'id del pagamento. Dovresti salvare questo ID da qualche parte per poter reindirizzare il cliente alla pagina di pagamento Hero a questo URL: https://pay.heropay.eu/checkout/XXXXX dove XXX è il payment_id (in produzione). In staging, l'URL sarebbe https://staging.pay.heropay.eu/checkout/XXX

Errori

createPayment può fallire per diversi motivi. Ecco l'elenco degli errori più comuni e le relative spiegazioni.

errorCode	Tipo di errore	Descrizione
NOT_LOGGED	Error	La Api-Key è mancante o non valida.
MERCHANT_PRODUCT_DISABLED	Error	L'account che stai utilizzando non è autorizzato a ricevere pagamenti. Contatta il tuo amministratore Hero.
INVALID_PAYMENT_TYPE	Error	Il tipo di pagamento non è valido. Controlla la tua richiesta e assicurati che il tuo account Hero sia configurato correttamente dal nostro team.
Amount XX is smaller than paymentMin YY	Error	L'importo è inferiore all'importo minimo autorizzato per il pagamento. Se pensi che non sia così, contatta il tuo amministratore Hero.
Amount XX is bigger than paymentMax YY	Error	L'importo è superiore all'importo massimo autorizzato per il pagamento. Se pensi che non sia così, contatta il tuo amministratore Hero.

getPaymentsInfos

Puoi chiamare questo endpoint quando hai bisogno di conoscere le ultime informazioni su uno o più pagamenti, come se il pagamento è stato finalizzato o l'importo rimborsato.

Esempio

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
      }
    }
  }
}

Argomenti

Questo endpoint accetta un argomento. L'ID o gli ID del pagamento o dei pagamenti di cui vuoi ottenere informazioni.

Argomento	Tipo	Descrizione	Obbligatorio
paymentIds	Array di String	Il `payment_id` del pagamento.	sì

Risposta

La risposta sarà un array di oggetti per ogni payment_id passato. Solo i payment_id esistenti verranno restituiti con le seguenti informazioni. Se nessuno dei payment_id esiste, il risultato sarà un array vuoto.

Consulta il flusso di pagamento per ulteriori informazioni su ciascuno stato e il suo significato.

Campo	Tipo	Descrizione	Nullable
paymentId	string	L'id del pagamento	no
isSuccess	boolean	Indica se il pagamento è stato finalizzato o meno.	no
error	string	Il pagamento non è stato finalizzato. Non convalidare l'ordine.	sì
reviewStatus	integer	Lo stato di revisione del rischio. Non utilizzato per la nostra soluzione di elaborazione.	no
reason	integer	Il motivo dello stato di revisione del rischio. Non utilizzato per la nostra soluzione di elaborazione.	sì
initialPaymentAmount	integer	L'importo iniziale del pagamento.	no
pendingRefundAmount	integer	La somma degli importi di rimborso attualmente in fase di elaborazione.	no
refundedAmount	integer	La somma di tutti gli importi di rimborso riusciti per questo pagamento.	no

Esempio di risposta:

Successo:

{
  "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
    }
  ]
}

Errore:

{
  "result": []
}

warning

Quando c'è un errore l'ordine non dovrebbe essere convalidato! Il cliente dovrebbe essere informato che il suo ordine è fallito e il pagamento non è stato finalizzato.

setOrderId

Questa richiesta ti dà la possibilità di definire l'ID dell'ordine per un pagamento avviato.

Esempio

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

Argomenti

Argomento	Tipo	Descrizione	Obbligatorio
paymentId	String	Il `payment_id` del pagamento.	sì
orderId	String	L'orderId che vuoi collegare al pagamento. È una stringa che rappresenta l'ordine nel tuo sistema.	sì

Risposta

La risposta è sempre true.

refundPaymentCheckout

Quando hai bisogno di annullare una transazione, puoi utilizzare questo endpoint e gestiremo il processo di rimborso per te. Questo ti permette di rimborsare specifiche transazioni di pagamento checkout.

Esempio

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

Argomenti

Questo endpoint accetta un oggetto di input con le seguenti proprietà:

Proprietà	Tipo	Descrizione	Obbligatorio
paymentCheckoutId	String	L'ID del checkout di pagamento da rimborsare	sì
amount	Integer	L'importo da rimborsare in centesimi	sì

Risposta

Campo	Tipo	Descrizione	Nullable
success	Boolean	Indica se il rimborso è stato effettuato con successo	no

Esempio di risposta positiva:

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

Errori

Il processo di rimborso può fallire per vari motivi. Il resolver restituisce diversi tipi di errori:

Errori di Validazione

Si verificano quando la validazione dell'input fallisce.

{
  "data": {
    "refundPaymentCheckout": {
      "validationErrors": [
        {
          "path": ["amount"],
          "validationError": "Amount must be a positive number"
        }
      ]
    }
  }
}

Errori Funzionali

Questi errori sono relativi a regole di business e operazioni:

Codice Errore	Descrizione
UNAUTHORIZED	Non hai il permesso di eseguire questa azione
FUNCTIONAL_ERROR	Varie violazioni delle regole di business tra cui:
	- INVALID_AMOUNT: L'importo non è valido (deve essere positivo e non superare l'importo originale del pagamento)
	- INVALID_PAYMENT_CHECKOUT: Il checkout di pagamento non esiste
	- DRAFT_PAYMENT_CHECKOUT: Impossibile rimborsare un checkout di pagamento in bozza
	- BA_NOT_FOUND: Account aziendale non trovato
	- BA_ONBOARDING_IS_NOT_COMPLETED: L'onboarding dell'account aziendale non è completato
	- BA_BALANCE_INSUFFICIENT: Fondi insufficienti nell'account aziendale
	- BA_CANNOT_TRANSFER_FUNDS: Impossibile trasferire fondi dall'account aziendale
	- AMOUNT_TOO_LOW: L'importo del rimborso deve essere di almeno 1 centesimo
	- AMOUNT_TOO_HIGH: L'importo del rimborso supera l'importo rimborsabile
	- LEDGER_BALANCE_TOO_LOW: Saldo insufficiente nell'account del libro mastro
	- REFUND_IS_FROZEN: Il pagamento è attualmente bloccato e non può essere rimborsato
	- PAYMENT_NOT_STARTED: Impossibile rimborsare un pagamento che non è stato avviato

Errori Tecnici

Questi sono errori interni del sistema che potrebbero verificarsi:

Codice Errore	Descrizione
INTERNAL_SERVER_ERROR	Si è verificato un errore tecnico durante l'elaborazione
CORE_PAYMENT_REFUND_FAILED	Si è verificato un errore nel sistema di elaborazione dei pagamenti

Esempio di risposta di errore:

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

createPayment​

Esempio​

Argomenti​

Risposta​

Errori​

getPaymentsInfos​

Esempio​

Argomenti​

Risposta​

setOrderId​

Esempio​

Argomenti​

Risposta​

refundPaymentCheckout​

Esempio​

Argomenti​

Risposta​

Esempio di risposta positiva:​

Errori​

Errori di Validazione​

Errori Funzionali​

Errori Tecnici​

Esempio di risposta di errore:​

createPayment

Esempio

Argomenti

Risposta

Errori

getPaymentsInfos

Esempio

Argomenti

Risposta

setOrderId

Esempio

Argomenti

Risposta

refundPaymentCheckout

Esempio

Argomenti

Risposta

Esempio di risposta positiva:

Errori

Errori di Validazione

Errori Funzionali

Errori Tecnici

Esempio di risposta di errore: