Empezar

Configura tu tienda, guarda tus llaves y comprueba que recibes webhooks.

Configura tu tienda con POST /v1/setup y guarda las llaves de la respuesta.
Deja la llave secreta en tu servidor y usa la llave pública en tu página.
Envía un webhook de prueba a tu endpoint.

La configuración es el único llamado sin llave secreta. Usa el client id y el client secret de tu aplicación del API de Integración de n1co:

Configurar la tienda

curl -s -X POST https://api-epay.dev.n1co.dev/v1/setup \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<client id de tu aplicación>",
    "client_secret": "<client secret de tu aplicación>",
    "webhook_url": "https://hooks.example.com/n1co"
  }'

201 Created

{
  "store_id": "0b9f8a52-2f0e-4d84-9a52-6c1f7e0d9a11",
  "store_name": "Example Store",
  "publishable_key": "pk_3x4mpl3pUbl1shabl3k3yAAAAAAAAAAA",
  "secret_key": "sk_3x4mpl3s3cr3tk3yAAAAAAAAAAAAAAAA",
  "webhook": {
    "url": "https://hooks.example.com/n1co",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  }
}

Llaves#

Llave	Formato	Dónde se usa
`publishable_key`	`pk_` y 32 caracteres	En tu página: `n1co('pk_…')`. Es pública.
`secret_key`	`sk_` y 32 caracteres	En tu servidor: `Authorization: Bearer sk_…`.
`webhook.secret`	`whsec_` y 32 caracteres	En tu servidor, para verificar los webhooks.

Cada sesión de tarjeta y cada payment intent traen además un client_secret. Tu servidor lo entrega solo a la página de ese comprador.

Un llamado autenticado

curl -s 'https://api-epay.dev.n1co.dev/v1/events?limit=1' \
  -H "Authorization: Bearer $N1CO_SECRET_KEY"

Sin una llave válida, la respuesta es 401 invalid_api_key.

Tu aplicación y los entornos#

Tu aplicación del API de Integración debe pertenecer a tu tienda y tener los roles EPay.ReadWrite.OwnedBy y Store.Read.OwnedBy. ePay usa el client secret solo en ese llamado y no lo guarda.

La primera configuración puede tardar cerca de un minuto: usa un timeout de al menos dos minutos.

Entorno	API de ePay	n1co.js
Desarrollo	`https://api-epay.dev.n1co.dev`	`https://elements.n1co.dev/v1/n1co.js`
Producción	Por anunciar	Por anunciar

Cada entorno tiene su propia configuración y sus propias llaves.

Cambiar la configuración#

Repite POST /v1/setup para cambiar cualquier cosa. Es idempotente y siempre vuelve a verificar tu aplicación.

Si envías	Respuesta
Lo mismo que ya está configurado	`409 store_already_enabled`, sin secretos
Una `webhook_url` distinta	`200` con un `webhook.secret` nuevo
`"rotate_secret_key": true`	`200` con una `secret_key` nueva
`"rotate_webhook_secret": true`	`200` con un `webhook.secret` nuevo
Un `client_id` distinto	`200`, vinculada a la nueva aplicación

Una llave rotada reemplaza a la anterior en cuanto llega la respuesta: despliégala de inmediato. La llave pública no se rota. Los códigos de error están en Errores.

La URL de webhooks#

Usa https, sin usuario, contraseña ni fragmento, y tiene como máximo 2048 caracteres.
Su host es un nombre o una IP públicos: no se aceptan localhost, *.local, *.internal ni nombres de una sola etiqueta.
Todas las direcciones a las que resuelve deben ser públicas.

Si no cumple, la respuesta es 400 invalid_request.

Comprobar la conexión#

POST /v1/webhooks/test envía un evento webhook.test firmado a tu webhook_url:

curl -s -X POST https://api-epay.dev.n1co.dev/v1/webhooks/test \
  -H "Authorization: Bearer $N1CO_SECRET_KEY"

Responde 202. Para verificar la firma, sigue con Webhooks; para tu primera integración, con Guardar una tarjeta.