API

createPayment

Dies ist die Hauptmutation des Zahlungsablaufs. Sie ist nützlich, um Zahlungen bei Hero zu erstellen.

Example

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

Arguments

Die createPayment-Mutation nimmt ein Argument vom Typ NewPayment entgegen

Argument	Typ	Beschreibung	Pflichtfeld
amount	Int	Der Gesamtbetrag der Zahlung. Er sollte in Cent angegeben werden. Beispiel: 5000 für eine Zahlung von 50€.	ja
redirectUri	String	Die URI, über die Hero Ihr System benachrichtigt. Es ist auch die URI, zu der Hero Ihren Kunden weiterleitet, wenn die Zahlung abgeschlossen ist. Diese URI sollte nicht durch ein Authentifizierungssystem geschützt sein. Es wird empfohlen, die eindeutige ID der Bestellung darin aufzunehmen.	ja
comebackUri	String	Die URI, die es dem Kunden ermöglicht, zur Auswahl der Zahlungsmethode zurückzukehren. Wenn Sie diese nicht angeben, wird der Kunde zur zuletzt besuchten Seite weitergeleitet, wenn er auf die Schaltfläche "Revenir au site marchand" (am unteren Rand der Hero-Zahlungsseite) klickt.	nein
type	Enum	Der gewählte Zahlungstyp. Bitte senden Sie den von avalaiblePaymentTypes erhaltenen Wert zurück.	ja
issuer	Object	Informationen über Ihren Kunden.	ja
issuer.address	Object	Rechnungsadresse des Kunden	ja
issuer.address.line1	String	Rechnungsadresse des Kunden - Erste Zeile	ja
issuer.address.line2	String	Rechnungsadresse des Kunden - Zweite Zeile	nein
issuer.address.city	String	Rechnungsadresse des Kunden - Stadt	ja
issuer.address.zipCode	String	Rechnungsadresse des Kunden - Postleitzahl	ja
issuer.deliveryAddress	Object	Lieferadresse des Kunden	nein
issuer.deliveryAddress.line1	String	Lieferadresse des Kunden - Erste Zeile	ja
issuer.deliveryAddress.line2	String	Lieferadresse des Kunden - Zweite Zeile	nein
issuer.deliveryAddress.city	String	Lieferadresse des Kunden - Stadt	ja
issuer.deliveryAddress.zipCode	String	Lieferadresse des Kunden - Postleitzahl	ja
issuer.name	String	Name des Kundenunternehmens	ja
issuer.contactEmail	String	E-Mail-Adresse des Kunden	ja
issuer.contactPhone	String	Telefonnummer des Kunden	ja
issuer.customerReference	String	Die eindeutige Kennung, die Sie für diesen Kunden verwenden.	nein

Response

Wenn die Zahlung erstellt wurde, gibt die API die ID der Zahlung zurück. Sie sollten diese ID irgendwo speichern, um den Kunden zur Hero-Zahlungsseite unter dieser URL weiterleiten zu können: https://pay.heropay.eu/checkout/XXXXX, wobei XXX die payment_id ist (in der Produktionsumgebung). In der Staging-Umgebung wäre die URL https://staging.pay.heropay.eu/checkout/XXX

Errors

createPayment kann aus verschiedenen Gründen fehlschlagen. Hier ist die Liste der häufigsten Fehler und Erklärungen.

errorCode	Error Type	Beschreibung
NOT_LOGGED	Error	Der Api-Key fehlt oder ist ungültig.
MERCHANT_PRODUCT_DISABLED	Error	Das von Ihnen verwendete Konto ist nicht berechtigt, Zahlungen zu erhalten. Kontaktieren Sie Ihren Hero-Administrator.
INVALID_PAYMENT_TYPE	Error	Der Zahlungstyp ist ungültig. Überprüfen Sie Ihre Anfrage und stellen Sie sicher, dass Ihr Hero-Konto von unserem Team richtig konfiguriert wurde.
Amount XX is smaller than paymentMin YY	Error	Der Betrag ist niedriger als Ihr minimaler autorisierter Zahlungsbetrag. Wenn Sie glauben, dass dies nicht der Fall sein sollte, kontaktieren Sie Ihren Hero-Administrator.
Amount XX is bigger than paymentMax YY	Error	Der Betrag ist höher als Ihr maximaler autorisierter Zahlungsbetrag. Wenn Sie glauben, dass dies nicht der Fall sein sollte, kontaktieren Sie Ihren Hero-Administrator.

getPaymentsInfos

Sie können diesen Endpunkt aufrufen, wenn Sie die neuesten Informationen zu einer oder mehreren Zahlungen benötigen, wie z.B. ob die Zahlung abgeschlossen wurde oder den erstatteten Zahlungsbetrag.

Example

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

Dieser Endpunkt nimmt ein Argument entgegen. Die ID(s) der Zahlung(en), über die Sie Informationen erhalten möchten.

Argument	Typ	Beschreibung	Pflichtfeld
paymentIds	Array of String	Die `payment_id`(s) der Zahlung(en).	ja

Response

Die Antwort ist ein Array von Objekten für jede übermittelte payment_id. Nur die existierenden payment_ids werden mit den folgenden Informationen zurückgegeben. Wenn keine der payment_ids existiert, ist das Ergebnis ein leeres Array.

Weitere Informationen zu jedem Status und seiner Bedeutung finden Sie im Zahlungsablauf.

Feld	Typ	Beschreibung	Nullable
paymentId	string	Die ID der Zahlung	nein
isSuccess	boolean	Ob die Zahlung abgeschlossen wurde oder nicht.	nein
error	string	Die Zahlung wurde nicht abgeschlossen. Validieren Sie die Bestellung nicht.	ja
reviewStatus	integer	Der Risikobewertungsstatus. Wird für unsere Processing-Lösung nicht verwendet.	nein
reason	integer	Der Grund für den Risikobewertungsstatus. Wird für unsere Processing-Lösung nicht verwendet.	ja
initialPaymentAmount	integer	Der ursprüngliche Zahlungsbetrag.	nein
pendingRefundAmount	integer	Die Summe der Erstattungsbeträge, die derzeit verarbeitet werden.	nein
refundedAmount	integer	Die Summe aller erfolgreichen Erstattungsbeträge für diese Zahlung.	nein

Beispiel einer Antwort:

Erfolg:

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

Fehler:

{
  "result": []
}

warning

Bei einem Fehler sollte die Bestellung nicht validiert werden! Der Kunde sollte darüber informiert werden, dass seine Bestellung fehlgeschlagen ist und die Zahlung nicht abgeschlossen wurde.

setOrderId

Diese Anfrage gibt Ihnen die Möglichkeit, die Bestell-ID für eine initiierte Zahlung zu definieren.

Example

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

Arguments

Argument	Typ	Beschreibung	Pflichtfeld
paymentId	String	Die `payment_id` der Zahlung.	ja
orderId	String	Die orderId, die Sie mit der Zahlung verknüpfen möchten. Es ist ein String, der die Bestellung in Ihrem System repräsentiert.	ja

Response

Die Antwort ist immer true.

refundPaymentCheckout

Wenn Sie eine Transaktion rückgängig machen müssen, können Sie diesen Endpunkt verwenden, und wir kümmern uns für Sie um den Erstattungsprozess. Dies ermöglicht es Ihnen, bestimmte Zahlungscheckout-Transaktionen zu erstatten.

Example

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

Dieser Endpunkt nimmt ein Eingabeobjekt mit den folgenden Eigenschaften entgegen:

Eigenschaft	Typ	Beschreibung	Pflichtfeld
paymentCheckoutId	String	Die ID des zu erstattenden Zahlungscheckouts	ja
amount	Integer	Der zu erstattende Betrag in Cent	ja

Response

Feld	Typ	Beschreibung	Nullable
success	Boolean	Gibt an, ob die Erstattung erfolgreich war	nein

Beispiel einer erfolgreichen Antwort:

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

Errors

Der Erstattungsprozess kann aus verschiedenen Gründen fehlschlagen. Der Resolver gibt verschiedene Arten von Fehlern zurück:

Validation Errors

Tritt auf, wenn die Eingabevalidierung fehlschlägt.

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

Functional Errors

Diese Fehler stehen im Zusammenhang mit Geschäftsregeln und Operationen:

Error Code	Beschreibung
UNAUTHORIZED	Sie haben keine Berechtigung, diese Aktion durchzuführen
FUNCTIONAL_ERROR	Verschiedene Verstöße gegen Geschäftsregeln, darunter:
	- INVALID_AMOUNT: Der Betrag ist ungültig (muss positiv sein und darf den ursprünglichen Zahlungsbetrag nicht überschreiten)
	- INVALID_PAYMENT_CHECKOUT: Der Zahlungscheckout existiert nicht
	- DRAFT_PAYMENT_CHECKOUT: Ein Zahlungscheckout im Entwurfsstatus kann nicht erstattet werden
	- BA_NOT_FOUND: Geschäftskonto nicht gefunden
	- BA_ONBOARDING_IS_NOT_COMPLETED: Das Onboarding des Geschäftskontos ist nicht abgeschlossen
	- BA_BALANCE_INSUFFICIENT: Nicht genügend Guthaben auf dem Geschäftskonto
	- BA_CANNOT_TRANSFER_FUNDS: Geldmittel können nicht vom Geschäftskonto überwiesen werden
	- AMOUNT_TOO_LOW: Der Erstattungsbetrag muss mindestens 1 Cent betragen
	- AMOUNT_TOO_HIGH: Der Erstattungsbetrag übersteigt den erstattungsfähigen Betrag
	- LEDGER_BALANCE_TOO_LOW: Unzureichendes Guthaben auf dem Ledger-Konto
	- REFUND_IS_FROZEN: Die Zahlung ist derzeit eingefroren und kann nicht erstattet werden
	- PAYMENT_NOT_STARTED: Eine Zahlung, die nicht initiiert wurde, kann nicht erstattet werden

Technical Errors

Dies sind interne Systemfehler, die auftreten können:

Error Code	Beschreibung
INTERNAL_SERVER_ERROR	Während der Verarbeitung ist ein technischer Fehler aufgetreten
CORE_PAYMENT_REFUND_FAILED	Im Zahlungsverarbeitungssystem ist ein Fehler aufgetreten

Beispiel einer Fehlerantwort:

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

createPayment​

Example​

Arguments​

Response​

Errors​

getPaymentsInfos​

Example​

Arguments​

Response​

setOrderId​

Example​

Arguments​

Response​

refundPaymentCheckout​

Example​

Arguments​

Response​

Beispiel einer erfolgreichen Antwort:​

Errors​

Validation Errors​

Functional Errors​

Technical Errors​

Beispiel einer Fehlerantwort:​

createPayment

Example

Arguments

Response

Errors

getPaymentsInfos

Example

Arguments

Response

setOrderId

Example

Arguments

Response

refundPaymentCheckout

Example

Arguments

Response

Beispiel einer erfolgreichen Antwort:

Errors

Validation Errors

Functional Errors

Technical Errors

Beispiel einer Fehlerantwort: