API

createPayment

Es la mutación principal del flujo de pago. Es útil para crear pagos en 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

La mutación createPayment toma un argumento del tipo NewPayment

Argumento	Tipo	Descripción	Obligatorio
amount	Int	El monto total del pago. Debe estar en céntimos de euros. ej: 5000 para un pago de 50€.	sí
redirectUri	String	La URI donde Hero notificará a tu sistema. También es la URI donde Hero redirigirá a tu cliente cuando el pago esté completado. Esta URI no debe estar protegida por ningún sistema de autenticación. Se recomienda incluir el ID único del pedido en ella.	sí
comebackUri	String	La URI que permite al cliente volver a tu selección de método de pago. Si no la proporcionas, el cliente será redirigido a la última página visitada cuando haga clic en el botón "Revenir au site marchand" (en la parte inferior de la página de pago de Hero).	no
type	Enum	El tipo de pago elegido. Por favor, devuelve el valor recibido por avalaiblePaymentTypes.	sí
issuer	Object	Información sobre tu cliente.	sí
issuer.address	Object	Dirección de facturación del cliente	sí
issuer.address.line1	String	Dirección de facturación del cliente - Primera línea	sí
issuer.address.line2	String	Dirección de facturación del cliente - Segunda línea	no
issuer.address.city	String	Dirección de facturación del cliente - Ciudad	sí
issuer.address.zipCode	String	Dirección de facturación del cliente - Código postal	sí
issuer.deliveryAddress	Object	Dirección de entrega del cliente	no
issuer.deliveryAddress.line1	String	Dirección de entrega del cliente - Primera línea	sí
issuer.deliveryAddress.line2	String	Dirección de entrega del cliente - Segunda línea	no
issuer.deliveryAddress.city	String	Dirección de entrega del cliente - Ciudad	sí
issuer.deliveryAddress.zipCode	String	Dirección de entrega del cliente - Código postal	sí
issuer.name	String	Nombre de la empresa del cliente	sí
issuer.contactEmail	String	Correo electrónico del cliente	sí
issuer.contactPhone	String	Número de teléfono del cliente	sí
issuer.customerReference	String	El identificador único que utilizas para este cliente.	no

Response

Cuando se crea el pago, la API devuelve el id del pago. Deberías guardar este ID en algún lugar para poder redirigir al cliente a la página de pago de Hero en esta URL: https://pay.heropay.eu/checkout/XXXXX donde XXX es el payment_id (en producción). En entorno de staging, la URL sería https://staging.pay.heropay.eu/checkout/XXX

Errors

createPayment puede fallar por varias razones. Aquí está la lista de los errores más comunes y sus explicaciones.

errorCode	Error Type	Descripción
NOT_LOGGED	Error	Falta la Api-Key o es inválida.
MERCHANT_PRODUCT_DISABLED	Error	La cuenta que estás utilizando no está autorizada para recibir pagos. Contacta con tu administrador Hero.
INVALID_PAYMENT_TYPE	Error	El tipo de pago es inválido. Revisa tu solicitud y asegúrate de que tu cuenta Hero esté correctamente configurada por nuestro equipo.
Amount XX is smaller than paymentMin YY	Error	El monto es inferior a tu monto mínimo de pago autorizado. Si crees que este no debería ser el caso, contacta con tu administrador Hero.
Amount XX is bigger than paymentMax YY	Error	El monto es superior a tu monto máximo de pago autorizado. Si crees que este no debería ser el caso, contacta con tu administrador Hero.

getPaymentsInfos

Puedes llamar a este endpoint cuando necesites conocer la información más reciente de uno o varios pagos, como si el pago ha sido finalizado o el monto reembolsado del pago.

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

Este endpoint toma un argumento. El/los ID(s) del/de los pago(s) sobre los que quieres obtener información.

Argumento	Tipo	Descripción	Obligatorio
paymentIds	Array of String	El/los `payment_id`(s) del pago.	sí

Response

La respuesta será un array de objetos para cada payment_id pasado. Solo los payment_id existentes serán devueltos con la siguiente información. Si ninguno de los payment_id existe, el resultado será un array vacío.

Por favor, consulta el flujo de pago para más información sobre cada estado y su significado.

Campo	Tipo	Descripción	Nullable
paymentId	string	El id del pago	no
isSuccess	boolean	Indica si el pago ha sido finalizado o no.	no
error	string	El pago no ha sido finalizado. No valides el pedido.	sí
reviewStatus	integer	El estado de revisión de riesgo. No se utiliza para nuestra solución de Procesamiento.	no
reason	integer	La razón del estado de revisión de riesgo. No se utiliza para nuestra solución de Procesamiento.	sí
initialPaymentAmount	integer	El monto inicial del pago.	no
pendingRefundAmount	integer	La suma de los montos de reembolso actualmente en proceso.	no
refundedAmount	integer	La suma de todos los montos de reembolso exitosos para este pago.	no

Ejemplo de una respuesta:

Éxito:

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

Cuando hay un error, ¡el pedido no debe ser validado! Se debe informar al cliente que su pedido ha fallado y que el pago no ha sido finalizado.

setOrderId

Esta solicitud te da la posibilidad de definir el ID del pedido para un pago iniciado.

Example

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

Arguments

Argumento	Tipo	Descripción	Obligatorio
paymentId	String	El `payment_id` del pago.	sí
orderId	String	El orderId que quieres vincular al Pago. Es una cadena que representa el pedido en tu sistema.	sí

Response

La respuesta es siempre true.

refundPaymentCheckout

Cuando necesites revertir una transacción, puedes usar este endpoint y nosotros manejaremos el proceso de reembolso por ti. Esto te permite reembolsar transacciones específicas de pago.

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

Este endpoint toma un objeto de entrada con las siguientes propiedades:

Propiedad	Tipo	Descripción	Obligatorio
paymentCheckoutId	String	El ID del pago a reembolsar	sí
amount	Integer	El monto a reembolsar en céntimos	sí

Response

Campo	Tipo	Descripción	Nullable
success	Boolean	Indica si el reembolso fue exitoso	no

Ejemplo de una respuesta exitosa:

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

Errors

El proceso de reembolso puede fallar por varias razones. El resolvedor devuelve diferentes tipos de errores:

Validation Errors

Ocurre cuando la validación de entrada falla.

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

Functional Errors

Estos errores están relacionados con reglas de negocio y operaciones:

Error Code	Descripción
UNAUTHORIZED	No tienes permiso para realizar esta acción
FUNCTIONAL_ERROR	Varias violaciones de reglas de negocio, incluyendo:
	- INVALID_AMOUNT: El monto es inválido (debe ser positivo y no exceder el monto original del pago)
	- INVALID_PAYMENT_CHECKOUT: El pago no existe
	- DRAFT_PAYMENT_CHECKOUT: No se puede reembolsar un pago en borrador
	- BA_NOT_FOUND: Cuenta de negocio no encontrada
	- BA_ONBOARDING_IS_NOT_COMPLETED: El proceso de onboarding de la cuenta de negocio no está completo
	- BA_BALANCE_INSUFFICIENT: Fondos insuficientes en la cuenta de negocio
	- BA_CANNOT_TRANSFER_FUNDS: No se pueden transferir fondos desde la cuenta de negocio
	- AMOUNT_TOO_LOW: El monto del reembolso debe ser de al menos 1 céntimo
	- AMOUNT_TOO_HIGH: El monto del reembolso excede el monto reembolsable
	- LEDGER_BALANCE_TOO_LOW: Saldo insuficiente en la cuenta contable
	- REFUND_IS_FROZEN: El pago está actualmente congelado y no puede ser reembolsado
	- PAYMENT_NOT_STARTED: No se puede reembolsar un pago que no ha sido iniciado

Technical Errors

Estos son errores internos del sistema que pueden ocurrir:

Error Code	Descripción
INTERNAL_SERVER_ERROR	Ocurrió un error técnico durante el procesamiento
CORE_PAYMENT_REFUND_FAILED	Ocurrió un error en el sistema de procesamiento de pagos

Ejemplo de una respuesta de error:

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

Ejemplo de una respuesta exitosa:​

Errors​

Validation Errors​

Functional Errors​

Technical Errors​

Ejemplo de una respuesta de error:​

createPayment

Example

Arguments

Response

Errors

getPaymentsInfos

Example

Arguments

Response

setOrderId

Example

Arguments

Response

refundPaymentCheckout

Example

Arguments

Response

Ejemplo de una respuesta exitosa:

Errors

Validation Errors

Functional Errors

Technical Errors

Ejemplo de una respuesta de error: