Crear o actualizar pagos

Envía un arreglo de pagos. Cada ítem crea el pago cuando su id es nuevo, o actualiza el pago existente cuando ya pertenece al comercio del access token. id es el UUID de Fire spark y es obligatorio en cada ítem. Envía solo los campos que cambian.

Requiere un access token con el scope payments:write. Consulta Token para obtener un token.

merchant_id y env salen del token. Al crear, payment_provider_id y payment_method_id son obligatorios. El método debe pertenecer a ese proveedor. Si omites status, queda ACTIVE. Si omites los arreglos de alcance, el pago aplica a todas las tiendas, canales, marcas y fulfillments. Envía null en un pago existente para volver a ese alcance. private_key y webhook_signature se guardan, pero no salen en la respuesta. Si envías config, rules o conditions, ese campo se reemplaza por completo. Si lo omites, se conserva el valor guardado.

Config

config se valida contra el slug del proveedor, el método y la versión de las filas del catálogo.

Proveedor	Método	Versión	`config`
`kushki`	`CARD`, `WALLET`, `PIN_PAD`	`1.0.0`	`public_key` y `private_key` obligatorios. `webhook_signature` opcional.
`firespark`	`CASH`	`1.0.0`	`{}`
`firespark`	`REDEMPTION`	`1.0.0`	Solo `logo_url` (URL opcional). Cualquier otra clave se rechaza.
`yape`	`BANK_TRANSFER`, `PIN_PAD`	`1.0.0`	`{}`
`niubiz`	`PIN_PAD`	`1.0.0`	`{}`

Cualquier otro proveedor, método o versión acepta un objeto JSON. Al crear, un config omitido se valida como {}. Un pago firespark REDEMPTION es una fuente de canje propia (vales, Yape, Masivo, etc.). El name del pago y config.logo_url identifican esa fuente, así que las tiendas los muestran en lugar del logo del proveedor Fire spark. logo_url es público: sale en las respuestas y llega a la tienda.

{ "logo_url": "https://cdn.example.com/acme-rewards.png" }

Para kushki:

{
  "public_key": "pk_test_123",
  "private_key": "sk_test_123",
  "webhook_signature": "whsec_123"
}

Rules

rules es un arreglo de ventanas inclusivas de total del pedido. Cada ítem necesita minimum_order_value y maximum_order_value (0 a 1.000.000). [] significa que no hay tope de monto. Si omites rules al crear, se guarda [].

[{ "minimum_order_value": 5, "maximum_order_value": 200 }]

Conditions

conditions es un OR de grupos AND: el arreglo exterior es OR y cada arreglo interior es AND. [] significa que el pago aplica cuando coincide el alcance. Si omites conditions al crear, se guarda []. Cada condición necesita primitive, type, operator y value. Opcionales: interpretation (client, server o both) e invalidMessage. Primitivas de checkout que puedes enviar:

`primitive`	Ejemplos de `type`	Ejemplos de `operator`
`currency`	`Order total`	`greater than or equal to`, `less than`
`number`	`Cart product count`, `Order includes product`	`equal to`, `greater than`
`boolean`	`Is anonymous order`, `Customer is anonymous`	`is`, `is not`
`string`	`Order includes product with tag`	`equal to`, `contains`
`enum`	`Payment method`, `Payment collect at`, `Payment status`	`is`, `is any of`
`custom`	`Store`, `Channel`, `Brand`, `Fulfillment`	`is`, `is not`
`custom`	`Stores`, `Channels`, `Brands`, `Fulfillments`	`is any of`, `is none of`, `is all of`

Order includes product también necesita product_id. Order includes product with tag también necesita tag. Este ejemplo ofrece el pago cuando el total es al menos 10, o cuando el carrito tiene 3 productos o más:

[
  [
    {
      "primitive": "currency",
      "type": "Order total",
      "operator": "greater than or equal to",
      "value": 10
    }
  ],
  [
    {
      "primitive": "number",
      "type": "Cart product count",
      "operator": "greater than or equal to",
      "value": 3
    }
  ]
]

Solicitud

curl -X PUT "https://firespark.cloud/api/integrations/v1/payments" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "3b1c8f2e-5a44-4d1b-9c0e-2f6a1d8b7e90",
      "payment_provider_id": "6f1c8f2e-5a44-4d1b-9c0e-2f6a1d8b7e90",
      "payment_method_id": "7c1c8f2e-5a44-4d1b-9c0e-2f6a1d8b7e90",
      "config": {
        "public_key": "pk_test_123",
        "private_key": "sk_test_123",
        "webhook_signature": "whsec_123"
      },
      "rules": [
        { "minimum_order_value": 5, "maximum_order_value": 200 }
      ],
      "conditions": [
        [
          {
            "primitive": "currency",
            "type": "Order total",
            "operator": "greater than or equal to",
            "value": 10,
            "interpretation": "both",
            "invalidMessage": "Minimum order is 10"
          }
        ]
      ],
      "store_ids": ["downtown"],
      "channel_ids": ["app"],
      "brand_ids": ["0001"],
      "fulfillment_ids": ["delivery"],
      "store_label_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
      "channel_label_ids": null,
      "brand_label_ids": null,
      "fulfillment_label_ids": null,
      "status": "ACTIVE"
    },
    {
      "id": "4c2d9f3e-6b55-4e2c-8d1f-3a7b2e9c8f01",
      "status": "INACTIVE"
    }
  ]'

El cuerpo es un arreglo de 1 a 100 ítems. Cada ítem lleva id más los campos descritos arriba.

Respuesta

Zod valida el cuerpo completo antes de guardar. Si algún campo es inválido, responde HTTP 400 y no se guarda ningún ítem. Cuando el cuerpo es válido, los ítems se guardan uno tras otro. El HTTP es 200 solo si todos se guardaron. Si un ítem posterior falla por una regla de negocio, el HTTP es el status de ese ítem (422 o 500).

Campo	Descripción
`id`	El `id` del ítem. `null` si faltaba o no era válido.
`status`	`200` si se guardó. `422` por un `id` duplicado, un proveedor o método desconocido, un método de otro proveedor, un `config` inválido, o al crear sin proveedor y método. `500` por un fallo inesperado.
`data`	El pago guardado sin secretos en `config`, con la misma forma que Obtener pago. Solo cuando `status` es `200`.
`error`	Mensaje de error. Solo cuando `status` no es `200`.
`details`	Detalle del error a nivel de ítem, incluidas las rutas de `config` inválido.

{
  "data": [
    {
      "id": "3b1c8f2e-5a44-4d1b-9c0e-2f6a1d8b7e90",
      "status": 200,
      "data": {
        "id": "3b1c8f2e-5a44-4d1b-9c0e-2f6a1d8b7e90",
        "payment_provider_id": "6f1c8f2e-5a44-4d1b-9c0e-2f6a1d8b7e90",
        "payment_method_id": "7c1c8f2e-5a44-4d1b-9c0e-2f6a1d8b7e90",
        "config": { "public_key": "pk_test_123" },
        "status": "ACTIVE"
      }
    },
    {
      "id": "4c2d9f3e-6b55-4e2c-8d1f-3a7b2e9c8f01",
      "status": 422,
      "error": "Payment provider and method are required",
      "details": null
    }
  ]
}

{
  "error": "Invalid fields",
  "details": {
    "0.id": "Invalid UUID"
  }
}

Errores

Estado	Descripción
`400`	El cuerpo no es un arreglo de 1 a 100 ítems, o algún ítem tiene campos inválidos. No se guarda ningún ítem.
`401`	Access token ausente o inválido.
`403`	El token no incluye el scope `payments:write`.

Documentación de API

Endpoints

Guías

Recursos

Crear o actualizar pagos

Config

Rules

Conditions

Solicitud

Respuesta

Errores

​Config

​Rules

​Conditions

​Solicitud

​Respuesta

​Errores

Config

Rules

Conditions

Solicitud

Respuesta

Errores