Referência API

Iniciar pagamento de bilhetes

Valida acesso a bilhetes, tipo e comprador; cria ou reutiliza pagamento central com recibo vinculado ao domínio.

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

Modelo de acesso

Modelo de acesso: HMAC de Organização no servidor
Âmbito necessário: payments:write
Disponibilidade documentada: Implementado no código

Disponibilidade verificada no código, sem garantia de produção.

A assinatura privada fica no servidor. A API Versão 1 usa assinatura v2; não é uma API v2.

Cabeçalhos

Nome	Tipo	Validação
`x-white-label-domain`Obrigatório Domínio verificado que resolve a conta de Organização aprovada e vincula este pedido.	`string`	Validação: Nome de anfitrião HTTPS verificado.
`x-white-label-key-id`Obrigatório Identificador extraído da chave privada única; nunca envie o segredo neste cabeçalho.	`string`	Validação: Identificador interno da chave privada emitida.
`x-white-label-signature-version`Obrigatório Seleciona a assinatura vinculada ao domínio; as rotas API mantêm a Versão 1.	`string`	Validação: 2.
`x-white-label-timestamp`Obrigatório Instante da assinatura em milissegundos comparado com o relógio do servidor para rejeitar pedidos antigos.	`string`	Validação: Milissegundos com 13 dígitos; dentro de cinco minutos.
`x-white-label-nonce`Obrigatório Valor aleatório novo registado pelo servidor para impedir repetição de um pedido assinado.	`string`	Validação: Valor novo: 16–128 [A-Za-z0-9_-].
`x-white-label-signature`Obrigatório HMAC-SHA256 de domínio, chave de idempotência, credencial de campanha, instante, nonce, método, caminho, consulta ordenada e hash exato do corpo.	`string`	Validação: HMAC-SHA256 hexadecimal em minúsculas.
`x-white-label-campaign-key`Opcional Chave de campanha completa opcional que limita o pedido privado à mesma campanha autorizada.	`string`	Validação: Valor keyId:secret completo, opcional e limitado ao seu âmbito.
`X-Idempotency-Key`Obrigatório Identidade estável de operação reutilizada com os mesmos detalhes; detalhes diferentes com a mesma chave são rejeitados.	`string`	Validação: 16–128 [A-Za-z0-9_-].

Pedido

Nome	Tipo	Validação
`campaign_id`Obrigatório Campanha existente na conta e no âmbito mais limitado de qualquer credencial de campanha.	`string`	Validação: UUID.
`ticket_id`Obrigatório Tipo de bilhete escolhido da campanha indicada; o servidor verifica estado, capacidade e preço.	`string`	Validação: UUID.
`quantity`Obrigatório Número de bilhetes; o servidor impõe inventário e limites por pessoa.	`integer`	Validação: 1–100.
`phone_number`Obrigatório Telefone do participante; métodos e regras podem exigir número internacional válido.	`string`	Validação: Telefone válido e não vazio.
`email`Opcional Email de contacto usado pelo fluxo configurado; por si só não concede acesso.	`string`	Validação: Endereço de e-mail.
`discount_code`Opcional Código de desconto ou convite da campanha, revalidado antes da compra.	`string`	Validação: Valor sem espaços nas extremidades e não vazio.
`invite_code`Opcional Código de desconto ou convite da campanha, revalidado antes da compra.	`string`	Validação: Valor sem espaços nas extremidades e não vazio.
`luggage_quantity`Opcional Quantidade de bagagem para evento que suporta essa opção configurada.	`integer`	Validação: >=0.
`attendee_information`Opcional Respostas aos campos reais da campanha, valores exigidos e opções suportadas.	`object`	Validação: Valores de texto correspondentes aos campos configurados.
`payment_channel`Opcional Preferência opcional; só se usam métodos ativos para país de venda, moeda e comerciante reais.	`enum`	Validação: card \| mobile_money \| apple_pay \| bank_transfer \| crypto; disponibilidade controlada pelo servidor.
`network_code`Opcional Rede móvel configurada quando o método de pagamento a exige.	`string`	Validação: Rede configurada.
`is_app`Opcional Contexto existente para escolher configuração Web ou App; sem permissões extra.	`boolean`	Validação: Contexto do cliente.
`return_path`Opcional Destino relativo de regresso ao site atual verificado após pagamento central.	`string`	Validação: Caminho relativo no mesmo domínio verificado.
`clientIp`Opcional IP original enviada por servidor autorizado para controlos existentes.	`string`	Validação: Endereço IP válido.

Pedido

Os exemplos descrevem o contrato e não são executados. Use registos de teste autorizados; nunca cole segredos reais aqui.

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

Resposta

Resposta de sucesso · HTTP 200

json

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

Resposta de erro · HTTP 400

json

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

Validação, permissões, registos indisponíveis e falhas usam estado HTTP e erro do controlador.

Limites e novas tentativas

Organização: 120 pedidos por chave e 300 por IP por janela; respeite Retry-After e X-RateLimit.

Compatibilidade do código

As operações autorizadas exigem testes específicos da conta.

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 acesso

Cabeçalhos

Pedido

Pedido

Resposta

Limites e novas tentativas

Compatibilidade do código

Continuar a desenvolver