Referencia API

Iniciar pago de entradas

Valida acceso a entradas, tipo y comprador; crea o reutiliza pago central con recibo vinculado al dominio.

POSThttps://api.sparkglim.net/api/white-label/v1/payments/initialize

Modelo de acceso

Modelo de acceso: HMAC de Organización en el servidor
Permiso requerido: payments:write
Disponibilidad documentada: Implementado en código

Disponibilidad verificada en el código, sin garantía de producción.

La firma privada permanece en su servidor. La API Versión 1 usa firma v2; no es una API v2.

Encabezados

Nombre	Tipo	Validación
`x-white-label-domain`Obligatorio Dominio verificado que resuelve la cuenta de Organización aprobada y vincula esta solicitud.	`string`	Validación: Nombre de host HTTPS verificado.
`x-white-label-key-id`Obligatorio Identificador extraído de la clave privada única; nunca envíe el secreto en esta cabecera.	`string`	Validación: Identificador interno de la clave privada emitida.
`x-white-label-signature-version`Obligatorio Selecciona la firma vinculada al dominio; las rutas API siguen en Versión 1.	`string`	Validación: 2.
`x-white-label-timestamp`Obligatorio Momento de firma en milisegundos comparado con el reloj del servidor para rechazar solicitudes caducadas.	`string`	Validación: Milisegundos de 13 dígitos; dentro de cinco minutos.
`x-white-label-nonce`Obligatorio Valor aleatorio nuevo registrado por el servidor para impedir repetir una solicitud firmada.	`string`	Validación: Valor nuevo: 16–128 [A-Za-z0-9_-].
`x-white-label-signature`Obligatorio HMAC-SHA256 de dominio, clave de idempotencia, credencial de campaña, instante, nonce, método, ruta, consulta ordenada y hash exacto del cuerpo.	`string`	Validación: HMAC-SHA256 hexadecimal en minúsculas.
`x-white-label-campaign-key`Opcional Clave de campaña completa opcional que limita la solicitud privada a la misma campaña autorizada.	`string`	Validación: Valor keyId:secret completo, opcional y limitado a su ámbito.
`X-Idempotency-Key`Obligatorio Identidad estable de operación reutilizada con los mismos detalles; cambiar detalles con la misma clave se rechaza.	`string`	Validación: 16–128 [A-Za-z0-9_-].

Solicitud

Nombre	Tipo	Validación
`campaign_id`Obligatorio Campaña existente dentro de la cuenta y del alcance más limitado de la credencial.	`string`	Validación: UUID.
`ticket_id`Obligatorio Tipo de entrada elegido de la campaña indicada; el servidor comprueba estado, capacidad y precio.	`string`	Validación: UUID.
`quantity`Obligatorio Número de entradas; el servidor impone inventario y límites por persona.	`integer`	Validación: 1–100.
`phone_number`Obligatorio Teléfono del participante; métodos y reglas pueden exigir número internacional válido.	`string`	Validación: Teléfono válido y no vacío.
`email`Opcional Correo de contacto usado por el flujo configurado; por sí solo no concede acceso.	`string`	Validación: Correo electrónico.
`discount_code`Opcional Código de descuento o invitación de campaña, revalidado antes de compra.	`string`	Validación: Valor sin espacios en los extremos y no vacío.
`invite_code`Opcional Código de descuento o invitación de campaña, revalidado antes de compra.	`string`	Validación: Valor sin espacios en los extremos y no vacío.
`luggage_quantity`Opcional Cantidad de equipaje para evento que admite esa opción configurada.	`integer`	Validación: >=0.
`attendee_information`Opcional Respuestas a campos reales de campaña, valores requeridos y opciones admitidas.	`object`	Validación: Valores de texto que coinciden con los campos configurados.
`payment_channel`Opcional Preferencia opcional; solo se usan métodos habilitados para país vendedor, moneda y comercio reales.	`enum`	Validación: card \| mobile_money \| apple_pay \| bank_transfer \| crypto; el servidor controla la disponibilidad.
`network_code`Opcional Red móvil configurada cuando el método de pago la requiere.	`string`	Validación: Red configurada.
`is_app`Opcional Contexto existente para elegir configuración web o app; sin permisos extra.	`boolean`	Validación: Contexto del cliente.
`return_path`Opcional Destino relativo de retorno al sitio actual verificado tras el pago centralizado.	`string`	Validación: Ruta relativa en el mismo dominio verificado.
`clientIp`Opcional IP original enviada por servidor autorizado para controles existentes.	`string`	Validación: Dirección IP válida.

Solicitud

Los ejemplos describen el contrato y no se ejecutan. Use registros de prueba autorizados; nunca pegue secretos reales aquí.

POST /api/white-label/v1/payments/initialize

http

POST /api/white-label/v1/payments/initialize HTTP/1.1
Host: api.sparkglim.net
x-white-label-domain: events.example.com
x-white-label-key-id: <ISSUED_KEY_ID>
x-white-label-signature-version: 2
x-white-label-timestamp: <FRESH_MILLISECONDS>
x-white-label-nonce: <FRESH_SIGNING_NONCE>
x-white-label-signature: <SERVER_GENERATED_SIGNATURE>
X-Idempotency-Key: example_stable_operation_0001
Content-Type: application/json

{
  "campaign_id": "11111111-1111-4111-8111-111111111111",
  "ticket_id": "22222222-2222-4222-8222-222222222222",
  "quantity": 1,
  "phone_number": "+233200000000",
  "return_path": "/payment-return"
}

Respuesta

Respuesta correcta · HTTP 200

json

{
  "success": true,
  "data": {
    "authorization_url": "https://checkout.sparkglim.net/gh/<SERVER_REFERENCE>",
    "reference": "<SERVER_REFERENCE>"
  },
  "requestId": "wlapi_example"
}

Respuesta de error · HTTP 400

json

{
  "success": false,
  "error": "<ERROR_MESSAGE>",
  "requestId": "wlapi_example"
}

Validación, permisos, registros no disponibles y fallos usan el estado HTTP y error del controlador.

Límites y reintentos

Organización: 120 solicitudes por clave y 300 por IP por ventana; respete Retry-After y X-RateLimit.

Compatibilidad del código

Las operaciones autorizadas requieren pruebas específicas de la cuenta.

server/src/api/router.ts
server/src/api/routes/white-label.ts
server/src/white-label/auth.ts
server/src/white-label/schemas.ts
server/src/white-label/organization-service.ts
server/src/white-label/service.ts

Modelo de acceso

Encabezados

Solicitud

Solicitud

Respuesta

Límites y reintentos

Compatibilidad del código

Seguir desarrollando