API

createPayment

It's the main mutation of payment flow. It's useful to create payment at Hero.

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

The createPayment mutation takes one argument of the type NewPayment

Argument	Type	Description	Mandatory
amount	Int	The total payment amount. It should be in cents of euros. ex: 5000 for a 50€ payment.	yes
redirectUri	String	The URI where hero will notify your system. It's also the URI where Hero will redirect your customer when the payment is done. This URI should not be protected by any Auth system. It's recommanded to include the unique ID of the order in it.	yes
comebackUri	String	The URI allowing the customer to go back to your payment method selection. If you don't provide it, the customer will be redirected to the latest visited page when clicking on the button "Revenir au site marchand" (at the bottom of the Hero payment page).	no
type	Enum	The choosen payment type. Please send back the value received by avalaiblePaymentTypes.	yes
issuer	Object	Information about your customer.	yes
issuer.address	Object	Billing customer address	yes
issuer.address.line1	String	Billing customer address - First row	yes
issuer.address.line2	String	Billing customer address - Second row	no
issuer.address.city	String	Billing customer address - City	yes
issuer.address.zipCode	String	Billing customer address - Zip Code	yes
issuer.deliveryAddress	Object	Delivery customer address	no
issuer.deliveryAddress.line1	String	Delivery customer address - First row	yes
issuer.deliveryAddress.line2	String	Delivery customer address - Second row	no
issuer.deliveryAddress.city	String	Delivery customer address - City	yes
issuer.deliveryAddress.zipCode	String	Delivery customer address - Zip Code	yes
issuer.name	String	Name of the customer company	yes
issuer.contactEmail	String	Customer's Email	yes
issuer.contactPhone	String	Customer's phone number	yes
issuer.customerReference	String	The unique identifier you use for this customer.	no

Response

When payment is created the API returns the id of the payment. You should save this ID somewhere to be able to redirect the customer to the Hero Payment Page at this URL : https://pay.heropay.eu/checkout/XXXXX where XXX is the payment_id (in production). In staging, the URL would be https://staging.pay.heropay.eu/checkout/XXX

Errors

createPayment can fail for several reasons. Here is the list of most common errors and explanations.

errorCode	Error Type	Description
NOT_LOGGED	Error	The Api-Key is missing or invalid.
MERCHANT_PRODUCT_DISABLED	Error	The account you use is not authorized to get paid. Contact your Hero administrator.
INVALID_PAYMENT_TYPE	Error	The payment Type is invalid. Check your request and make sure your Hero account is properly configured by our team.
Amount XX is smaller than paymentMin YY	Error	The amount is inferior to your minimum authorized payment amount. If you think this should not the case, contact your Hero administrator.
Amount XX is bigger than paymentMax YY	Error	The amount is higher than your maximum authorized payment amount. If you think this should not be the case, contact your Hero administrator.

getPaymentsInfos

You can call this endpoint when you need to know one or multiple payments' latest informations such as whether the payment has been finalized or the payment refunded amount.

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

This endpoint takes one argument. The ID(s) of the payment(s) you want to get informations.

Argument	Type	Description	Mandatory
paymentIds	Array of String	The payment's `payment_id`(s).	yes

Response

The response will be an an array of object for each payment_id passed. Only the existing payment_id will be returned with the following informations. If, none of the payment_id exist, the result will be an empty array.

Please see the payment flow for more information on each status and its meaning.

Field	Type	Description	Nullable
paymentId	string	The id of the payment	no
isSuccess	boolean	Whether the payment has been finalized or not.	no
error	string	The payment hasn't been finalized. Don't validate the order.	yes
reviewStatus	integer	The risk review status. Not used for our Processing Solution.	no
reason	integer	The reason of the risk review status. Not used for our Processing Solution.	yes
initialPaymentAmount	integer	The payment's initial amount.	no
pendingRefundAmount	integer	The sum of refund amounts currently being processed.	no
refundedAmount	integer	The sum of all successful refund amounts for this payment.	no

Example of a response:

Success:

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

Error:

{
  "result": []
}

warning

When there is an error the order should not be validated ! The customer should be informed that their order failed and the payment hasn't been finalized.

setOrderId

This request gives you the possibility to define the order ID for an initiated payment.

Example

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

Arguments

Argument	Type	Description	Mandatory
paymentId	String	The payment's `payment_id`.	yes
orderId	String	The orderId you want to link to the Payemnt. It's a string that represents the order in your system.	yes

Response

The response is always true.

refundPaymentCheckout

When you need to revert a transaction, you can use this endpoint and we will handle the refund process for you. This allows you to refund specific payment checkout transactions.

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

This endpoint takes an input object with the following properties:

Property	Type	Description	Mandatory
paymentCheckoutId	String	The ID of the payment checkout to refund	yes
amount	Integer	The amount to refund in cents	yes

Response

Field	Type	Description	Nullable
success	Boolean	Indicates whether the refund was successful	no

Example of a successful response:

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

Errors

The refund process may fail for various reasons. The resolver returns different types of errors:

Validation Errors

Occurs when the input validation fails.

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

Functional Errors

These errors are related to business rules and operations:

Error Code	Description
UNAUTHORIZED	You don't have permission to perform this action
FUNCTIONAL_ERROR	Various business rule violations including:
	- INVALID_AMOUNT: The amount is invalid (must be positive and not exceed original payment amount)
	- INVALID_PAYMENT_CHECKOUT: The payment checkout doesn't exist
	- DRAFT_PAYMENT_CHECKOUT: Cannot refund a draft payment checkout
	- BA_NOT_FOUND: Business account not found
	- BA_ONBOARDING_IS_NOT_COMPLETED: Business account onboarding is not completed
	- BA_BALANCE_INSUFFICIENT: Not enough funds in the business account
	- BA_CANNOT_TRANSFER_FUNDS: Unable to transfer funds from business account
	- AMOUNT_TOO_LOW: The refund amount must be at least 1 cent
	- AMOUNT_TOO_HIGH: The refund amount exceeds the refundable amount
	- LEDGER_BALANCE_TOO_LOW: Insufficient balance in the ledger account
	- REFUND_IS_FROZEN: The payment is currently frozen and cannot be refunded
	- PAYMENT_NOT_STARTED: Cannot refund a payment that hasn't been initiated

Technical Errors

These are internal system errors that may occur:

Error Code	Description
INTERNAL_SERVER_ERROR	A technical error occurred during processing
CORE_PAYMENT_REFUND_FAILED	An error occurred in the payment processing system

Example of an error response:

{
  "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​

Example of a successful response:​

Errors​

Validation Errors​

Functional Errors​

Technical Errors​

Example of an error response:​

createPayment

Example

Arguments

Response

Errors

getPaymentsInfos

Example

Arguments

Response

setOrderId

Example

Arguments

Response

refundPaymentCheckout

Example

Arguments

Response

Example of a successful response:

Errors

Validation Errors

Functional Errors

Technical Errors

Example of an error response: