> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear o actualizar pagos

> Crea o actualiza hasta 100 configuraciones de pago del comercio por id en una sola solicitud.

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.

> [!NOTE]
>
> Requiere un access token con el scope `payments:write`. Consulta
> [Token](https://firespark.cloud/docs/es/integrations-api/oauth/token/post.md) 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.

```json theme={null}
{ "logo_url": "https://cdn.example.com/acme-rewards.png" }
```

Para `kushki`:

```json theme={null}
{
  "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 `[]`.

```json theme={null}
[{ "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:

```json theme={null}
[
  [
    {
      "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

```bash theme={null}
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](https://firespark.cloud/docs/es/integrations-api/payments/\[id]/get). 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. |

```json Success theme={null}
{
  "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
    }
  ]
}
```

```json Campos inválidos theme={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`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.