Endpoints

API v1OpenAPI 3.1

API Reference

Endpoints e schemas para integrar o Kivora Payments por API Key.

Downloads

Descarregue a especificação oficial da API.

Download OpenAPI JSON Download OpenAPI YAML

Postman e Insomnia estarão disponíveis em breve.

POST/v1/b2c

Enviar dinheiro (B2C)

Realiza um envio de dinheiro para um cliente (Business to Customer). O estado inicial tipicamente é `processing` até o provedor confirmar o payout.

Headers obrigatórios

Header	Tipo	Descrição
`Content-Type`obrigatório	string	application/json
`Authorization`obrigatório	string	Bearer sk_live_xxx

API Key necessária

Sim (Authorization: Bearer sk_...)

Body Schema

B2CRequest

Campo	Tipo	Descrição
`phone`	string	Número de telemóvel do beneficiário.
`amount`	number	Montante a enviar.
`currency`	string	Moeda ISO 4217. Predefinição: MZN.
`reference`	string	Referência externa opcional do payout.

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "phone",
    "amount"
  ],
  "description": "Pedido para enviar dinheiro a um cliente (Business to Customer).",
  "properties": {
    "phone": {
      "type": "string",
      "description": "Número de telemóvel do beneficiário.",
      "example": "841234567"
    },
    "amount": {
      "type": "number",
      "minimum": 0,
      "description": "Montante a enviar.",
      "example": 100
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "default": "MZN",
      "description": "Moeda ISO 4217. Predefinição: MZN.",
      "example": "MZN"
    },
    "reference": {
      "type": "string",
      "description": "Referência externa opcional do payout.",
      "example": "PAYOUT-100"
    }
  }
}

Exemplo Request

json

{
  "phone": "841234567",
  "amount": 100,
  "currency": "MZN",
  "reference": "PAYOUT-100"
}

Exemplos de requisição

bash

curl -X POST "https://www.kivorapayments.com/v1/b2c" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"phone":"841234567","amount":100,"currency":"MZN","reference":"PAYOUT-100"}'

Response Schema

B2CResponse

Campo	Tipo	Descrição
`id`	string	Identificador do envio.
`status`	string enum	Estado actual do envio.
`amount`	number
`currency`	string
`reference`	string
`createdAt`	string (date-time)	Data de criação (presente em consultas GET).

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status",
    "amount",
    "currency"
  ],
  "description": "Transacção B2C criada ou consultada.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador do envio.",
      "example": "out_xxxxx"
    },
    "status": {
      "type": "string",
      "enum": [
        "processing",
        "completed",
        "failed",
        "cancelled"
      ],
      "description": "Estado actual do envio.",
      "example": "processing"
    },
    "amount": {
      "type": "number",
      "example": 100
    },
    "currency": {
      "type": "string",
      "example": "MZN"
    },
    "reference": {
      "type": "string",
      "example": "PAYOUT-100"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Data de criação (presente em consultas GET).",
      "example": "2026-07-30T16:00:00Z"
    }
  }
}

Resposta 201

json

{
  "id": "out_xxxxx",
  "status": "processing",
  "amount": 100,
  "currency": "MZN"
}

Try it out

Possíveis erros

Código	Descrição
400	Body inválido — phone e amount são obrigatórios
401	Não autenticado — Secret API Key em falta, inválida, revogada ou expirada
403	Sem permissão — a API Key não tem o scope necessário ou o recurso não pertence à organização
404	Recurso relacionado não encontrado
500	Erro interno do servidor

GET/v1/b2c/{transactionId}

Consultar envio B2C

Consulta o estado de um envio de dinheiro. Status possíveis: `processing`, `completed`, `failed`, `cancelled`.

Headers obrigatórios

Header	Tipo	Descrição
`Authorization`obrigatório	string	Bearer sk_live_xxx

API Key necessária

Sim (Authorization: Bearer sk_...)

Path Parameters

Parâmetro	Tipo	Descrição
`transactionId`obrigatório	string	Identificador da transacção B2C.

Body Schema

—

Exemplo Request

Exemplos de requisição

bash

curl "https://www.kivorapayments.com/v1/b2c/{transactionId}" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json"

Response Schema

B2CResponse

Campo	Tipo	Descrição
`id`	string	Identificador do envio.
`status`	string enum	Estado actual do envio.
`amount`	number
`currency`	string
`reference`	string
`createdAt`	string (date-time)	Data de criação (presente em consultas GET).

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status",
    "amount",
    "currency"
  ],
  "description": "Transacção B2C criada ou consultada.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador do envio.",
      "example": "out_xxxxx"
    },
    "status": {
      "type": "string",
      "enum": [
        "processing",
        "completed",
        "failed",
        "cancelled"
      ],
      "description": "Estado actual do envio.",
      "example": "processing"
    },
    "amount": {
      "type": "number",
      "example": 100
    },
    "currency": {
      "type": "string",
      "example": "MZN"
    },
    "reference": {
      "type": "string",
      "example": "PAYOUT-100"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Data de criação (presente em consultas GET).",
      "example": "2026-07-30T16:00:00Z"
    }
  }
}

Resposta 200

json

{
  "id": "out_xxxxx",
  "status": "completed",
  "amount": 100,
  "currency": "MZN",
  "createdAt": "2026-07-30T16:00:00Z"
}

Try it out

Possíveis erros

Código	Descrição
400	transactionId inválido
401	Não autenticado — Secret API Key em falta, inválida, revogada ou expirada
403	Sem permissão — a API Key não tem o scope necessário ou o recurso não pertence à organização
404	Transacção não encontrada
500	Erro interno do servidor

POST/v1/c2b

Iniciar cobrança C2B

Inicia uma cobrança ao cliente (Customer to Business). O pagador recebe um pedido no telemóvel para autorizar o pagamento. O estado inicial é `pending`.

Headers obrigatórios

Header	Tipo	Descrição
`Content-Type`obrigatório	string	application/json
`Authorization`obrigatório	string	Bearer sk_live_xxx

API Key necessária

Sim (Authorization: Bearer sk_...)

Body Schema

C2BRequest

Campo	Tipo	Descrição
`phone`	string	Número de telemóvel do pagador (MSISDN local, sem +258).
`amount`	number	Montante a cobrar.
`currency`	string	Moeda ISO 4217. Predefinição: MZN.
`reference`	string	Referência externa opcional (ex.: ID da encomenda).
`description`	string	Descrição legível do pagamento.

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "phone",
    "amount"
  ],
  "description": "Pedido para iniciar uma cobrança Customer to Business (C2B).",
  "properties": {
    "phone": {
      "type": "string",
      "description": "Número de telemóvel do pagador (MSISDN local, sem +258).",
      "example": "841234567"
    },
    "amount": {
      "type": "number",
      "minimum": 0,
      "description": "Montante a cobrar.",
      "example": 100
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "default": "MZN",
      "description": "Moeda ISO 4217. Predefinição: MZN.",
      "example": "MZN"
    },
    "reference": {
      "type": "string",
      "description": "Referência externa opcional (ex.: ID da encomenda).",
      "example": "ORDER-1001"
    },
    "description": {
      "type": "string",
      "description": "Descrição legível do pagamento.",
      "example": "Pagamento da encomenda"
    }
  }
}

Exemplo Request

json

{
  "phone": "841234567",
  "amount": 100,
  "currency": "MZN",
  "reference": "ORDER-1001",
  "description": "Pagamento da encomenda"
}

Exemplos de requisição

bash

curl -X POST "https://www.kivorapayments.com/v1/c2b" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"phone":"841234567","amount":100,"currency":"MZN","reference":"ORDER-1001","description":"Pagamento da encomenda"}'

Response Schema

C2BResponse

Campo	Tipo	Descrição
`id`	string	Identificador do pagamento.
`status`	string enum	Estado actual do pagamento.
`amount`	number
`currency`	string
`reference`	string	Referência externa, se fornecida.
`createdAt`	string (date-time)	Data de criação (presente em consultas GET).

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status",
    "amount",
    "currency"
  ],
  "description": "Pagamento C2B criado ou consultado.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador do pagamento.",
      "example": "pay_xxxxx"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "paid",
        "failed"
      ],
      "description": "Estado actual do pagamento.",
      "example": "pending"
    },
    "amount": {
      "type": "number",
      "example": 100
    },
    "currency": {
      "type": "string",
      "example": "MZN"
    },
    "reference": {
      "type": "string",
      "description": "Referência externa, se fornecida.",
      "example": "ORDER-1001"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Data de criação (presente em consultas GET).",
      "example": "2026-07-30T15:30:00Z"
    }
  }
}

Resposta 201

json

{
  "id": "pay_xxxxx",
  "status": "pending",
  "reference": "ORDER-1001",
  "amount": 100,
  "currency": "MZN"
}

Try it out

Possíveis erros

Código	Descrição
400	Body inválido — phone e amount são obrigatórios
401	Não autenticado — Secret API Key em falta, inválida, revogada ou expirada
403	Sem permissão — a API Key não tem o scope necessário ou o recurso não pertence à organização
404	Recurso relacionado não encontrado
500	Erro interno do servidor

GET/v1/c2b/{paymentId}

Consultar pagamento C2B

Consulta o estado actual de um pagamento C2B. Status possíveis: `pending`, `processing`, `paid`, `failed`.

Headers obrigatórios

Header	Tipo	Descrição
`Authorization`obrigatório	string	Bearer sk_live_xxx

API Key necessária

Sim (Authorization: Bearer sk_...)

Path Parameters

Parâmetro	Tipo	Descrição
`paymentId`obrigatório	string (uuid)	UUID ou identificador do pagamento C2B.

Body Schema

—

Exemplo Request

Exemplos de requisição

bash

curl "https://www.kivorapayments.com/v1/c2b/{paymentId}" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json"

Response Schema

C2BResponse

Campo	Tipo	Descrição
`id`	string	Identificador do pagamento.
`status`	string enum	Estado actual do pagamento.
`amount`	number
`currency`	string
`reference`	string	Referência externa, se fornecida.
`createdAt`	string (date-time)	Data de criação (presente em consultas GET).

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status",
    "amount",
    "currency"
  ],
  "description": "Pagamento C2B criado ou consultado.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador do pagamento.",
      "example": "pay_xxxxx"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "paid",
        "failed"
      ],
      "description": "Estado actual do pagamento.",
      "example": "pending"
    },
    "amount": {
      "type": "number",
      "example": 100
    },
    "currency": {
      "type": "string",
      "example": "MZN"
    },
    "reference": {
      "type": "string",
      "description": "Referência externa, se fornecida.",
      "example": "ORDER-1001"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Data de criação (presente em consultas GET).",
      "example": "2026-07-30T15:30:00Z"
    }
  }
}

Resposta 200

json

{
  "id": "pay_xxxxx",
  "status": "paid",
  "amount": 100,
  "currency": "MZN",
  "reference": "ORDER-1001",
  "createdAt": "2026-07-30T15:30:00Z"
}

Try it out

Possíveis erros

Código	Descrição
400	paymentId inválido
401	Não autenticado — Secret API Key em falta, inválida, revogada ou expirada
403	Sem permissão — a API Key não tem o scope necessário ou o recurso não pertence à organização
404	Pagamento não encontrado
500	Erro interno do servidor

POST/v1/subscriptions

Criar assinatura

Cria uma assinatura recorrente para um cliente. A cobrança segue o `interval` indicado (ex.: `monthly`).

Headers obrigatórios

Header	Tipo	Descrição
`Content-Type`obrigatório	string	application/json
`Authorization`obrigatório	string	Bearer sk_live_xxx

API Key necessária

Sim (Authorization: Bearer sk_...)

Body Schema

SubscriptionRequest

Campo	Tipo	Descrição
`customer`	Customer
`amount`	number	Valor cobrado em cada ciclo.
`currency`	string	Moeda ISO 4217. Predefinição: MZN.
`interval`	string enum	Frequência de cobrança.
`reference`	string	Referência externa opcional da assinatura.

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "customer",
    "amount",
    "interval"
  ],
  "description": "Pedido para criar uma assinatura recorrente.",
  "properties": {
    "customer": {
      "$ref": "#/components/schemas/Customer"
    },
    "amount": {
      "type": "number",
      "minimum": 0,
      "description": "Valor cobrado em cada ciclo.",
      "example": 299
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "default": "MZN",
      "description": "Moeda ISO 4217. Predefinição: MZN.",
      "example": "MZN"
    },
    "interval": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "yearly"
      ],
      "description": "Frequência de cobrança.",
      "example": "monthly"
    },
    "reference": {
      "type": "string",
      "description": "Referência externa opcional da assinatura.",
      "example": "SUB-001"
    }
  }
}

Exemplo Request

json

{
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "amount": 299,
  "currency": "MZN",
  "interval": "monthly",
  "reference": "SUB-001"
}

Exemplos de requisição

bash

curl -X POST "https://www.kivorapayments.com/v1/subscriptions" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"customer":{"name":"John Doe","email":"john@example.com"},"amount":299,"currency":"MZN","interval":"monthly","reference":"SUB-001"}'

Response Schema

SubscriptionResponse

Campo	Tipo	Descrição
`id`	string	Identificador da assinatura.
`status`	string enum	Estado da assinatura.
`amount`	number
`currency`	string
`interval`	string enum
`reference`	string
`nextBillingDate`	string (date)	Próxima data de cobrança (YYYY-MM-DD).
`customer`	Customer

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status"
  ],
  "description": "Assinatura criada ou consultada.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador da assinatura.",
      "example": "sub_xxxxx"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "cancelled",
        "past_due",
        "paused"
      ],
      "description": "Estado da assinatura.",
      "example": "active"
    },
    "amount": {
      "type": "number",
      "example": 299
    },
    "currency": {
      "type": "string",
      "example": "MZN"
    },
    "interval": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "yearly"
      ],
      "example": "monthly"
    },
    "reference": {
      "type": "string",
      "example": "SUB-001"
    },
    "nextBillingDate": {
      "type": "string",
      "format": "date",
      "description": "Próxima data de cobrança (YYYY-MM-DD).",
      "example": "2026-08-30"
    },
    "customer": {
      "$ref": "#/components/schemas/Customer"
    }
  }
}

Resposta 201

json

{
  "id": "sub_xxxxx",
  "status": "active"
}

Try it out

Possíveis erros

Código	Descrição
400	Body inválido — customer, amount e interval são obrigatórios
401	Não autenticado — Secret API Key em falta, inválida, revogada ou expirada
403	Sem permissão — a API Key não tem o scope necessário ou o recurso não pertence à organização
404	Recurso relacionado não encontrado
500	Erro interno do servidor

GET/v1/subscriptions/{subscriptionId}

Consultar assinatura

Obtém os detalhes e o estado actual de uma assinatura.

Headers obrigatórios

Header	Tipo	Descrição
`Authorization`obrigatório	string	Bearer sk_live_xxx

API Key necessária

Sim (Authorization: Bearer sk_...)

Path Parameters

Parâmetro	Tipo	Descrição
`subscriptionId`obrigatório	string	Identificador da assinatura.

Body Schema

—

Exemplo Request

Exemplos de requisição

bash

curl "https://www.kivorapayments.com/v1/subscriptions/{subscriptionId}" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json"

Response Schema

SubscriptionResponse

Campo	Tipo	Descrição
`id`	string	Identificador da assinatura.
`status`	string enum	Estado da assinatura.
`amount`	number
`currency`	string
`interval`	string enum
`reference`	string
`nextBillingDate`	string (date)	Próxima data de cobrança (YYYY-MM-DD).
`customer`	Customer

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status"
  ],
  "description": "Assinatura criada ou consultada.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador da assinatura.",
      "example": "sub_xxxxx"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "cancelled",
        "past_due",
        "paused"
      ],
      "description": "Estado da assinatura.",
      "example": "active"
    },
    "amount": {
      "type": "number",
      "example": 299
    },
    "currency": {
      "type": "string",
      "example": "MZN"
    },
    "interval": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "yearly"
      ],
      "example": "monthly"
    },
    "reference": {
      "type": "string",
      "example": "SUB-001"
    },
    "nextBillingDate": {
      "type": "string",
      "format": "date",
      "description": "Próxima data de cobrança (YYYY-MM-DD).",
      "example": "2026-08-30"
    },
    "customer": {
      "$ref": "#/components/schemas/Customer"
    }
  }
}

Resposta 200

json

{
  "id": "sub_xxxxx",
  "status": "active",
  "amount": 299,
  "currency": "MZN",
  "interval": "monthly",
  "nextBillingDate": "2026-08-30"
}

Try it out

Possíveis erros

Código	Descrição
400	subscriptionId inválido
401	Não autenticado — Secret API Key em falta, inválida, revogada ou expirada
403	Sem permissão — a API Key não tem o scope necessário ou o recurso não pertence à organização
404	Assinatura não encontrada
500	Erro interno do servidor

Webhooks

Eventos enviados automaticamente pela Kivora para o URL configurado no dashboard. Não existem endpoints públicos de gestão — apenas entrega de eventos. Responda com HTTP 2xx para confirmar a recepção.

EVENTpayment.created

payment.created

Disparado quando um pagamento C2B é criado. O estado inicial é tipicamente `pending`.

Payload Example

json

{
  "id": "evt_1a2b3c4d5e",
  "type": "payment.created",
  "created_at": "2026-07-30T15:30:00Z",
  "livemode": false,
  "data": {
    "id": "pay_xxxxx",
    "status": "pending",
    "amount": 100,
    "currency": "MZN",
    "reference": "ORDER-1001",
    "phone": "841234567"
  }
}

EVENTpayment.pending

payment.pending

Disparado quando o pagamento fica a aguardar acção do cliente ou do provedor.

Payload Example

json

{
  "id": "evt_2b3c4d5e6f",
  "type": "payment.pending",
  "created_at": "2026-07-30T15:30:05Z",
  "livemode": false,
  "data": {
    "id": "pay_xxxxx",
    "status": "pending",
    "amount": 100,
    "currency": "MZN",
    "reference": "ORDER-1001"
  }
}

EVENTpayment.completed

payment.completed

Disparado quando o pagamento é confirmado com sucesso (`status: paid`).

Payload Example

json

{
  "id": "evt_3c4d5e6f7a",
  "type": "payment.completed",
  "created_at": "2026-07-30T15:31:00Z",
  "livemode": false,
  "data": {
    "id": "pay_xxxxx",
    "status": "paid",
    "amount": 100,
    "currency": "MZN",
    "reference": "ORDER-1001",
    "paid_at": "2026-07-30T15:31:00Z"
  }
}

EVENTpayment.failed

payment.failed

Disparado quando o pagamento falha (fundos insuficientes, timeout, rejeição, etc.).

Payload Example

json

{
  "id": "evt_4d5e6f7a8b",
  "type": "payment.failed",
  "created_at": "2026-07-30T15:31:10Z",
  "livemode": false,
  "data": {
    "id": "pay_xxxxx",
    "status": "failed",
    "amount": 100,
    "currency": "MZN",
    "reference": "ORDER-1001",
    "failure_reason": "insufficient_funds"
  }
}

EVENTb2c.created

b2c.created

Disparado quando um envio B2C é criado.

Payload Example

json

{
  "id": "evt_5e6f7a8b9c",
  "type": "b2c.created",
  "created_at": "2026-07-30T16:00:00Z",
  "livemode": false,
  "data": {
    "id": "out_xxxxx",
    "status": "processing",
    "amount": 100,
    "currency": "MZN",
    "reference": "PAYOUT-100",
    "phone": "841234567"
  }
}

EVENTb2c.processing

b2c.processing

Disparado enquanto o payout está a ser processado pelo provedor.

Payload Example

json

{
  "id": "evt_6f7a8b9c0d",
  "type": "b2c.processing",
  "created_at": "2026-07-30T16:00:05Z",
  "livemode": false,
  "data": {
    "id": "out_xxxxx",
    "status": "processing",
    "amount": 100,
    "currency": "MZN",
    "reference": "PAYOUT-100"
  }
}

EVENTb2c.completed

b2c.completed

Disparado quando o dinheiro foi entregue com sucesso ao beneficiário.

Payload Example

json

{
  "id": "evt_7a8b9c0d1e",
  "type": "b2c.completed",
  "created_at": "2026-07-30T16:01:00Z",
  "livemode": false,
  "data": {
    "id": "out_xxxxx",
    "status": "completed",
    "amount": 100,
    "currency": "MZN",
    "reference": "PAYOUT-100",
    "completed_at": "2026-07-30T16:01:00Z"
  }
}

EVENTb2c.failed

b2c.failed

Disparado quando o envio B2C falha.

Payload Example

json

{
  "id": "evt_8b9c0d1e2f",
  "type": "b2c.failed",
  "created_at": "2026-07-30T16:01:10Z",
  "livemode": false,
  "data": {
    "id": "out_xxxxx",
    "status": "failed",
    "amount": 100,
    "currency": "MZN",
    "reference": "PAYOUT-100",
    "failure_reason": "invalid_phone"
  }
}

EVENTsubscription.created

subscription.created

Disparado quando uma assinatura é criada com sucesso.

Payload Example

json

{
  "id": "evt_9c0d1e2f3a",
  "type": "subscription.created",
  "created_at": "2026-07-30T17:00:00Z",
  "livemode": false,
  "data": {
    "id": "sub_xxxxx",
    "status": "active",
    "amount": 299,
    "currency": "MZN",
    "interval": "monthly",
    "reference": "SUB-001",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

EVENTsubscription.cancelled

subscription.cancelled

Disparado quando uma assinatura é cancelada.

Payload Example

json

{
  "id": "evt_0d1e2f3a4b",
  "type": "subscription.cancelled",
  "created_at": "2026-08-15T10:00:00Z",
  "livemode": false,
  "data": {
    "id": "sub_xxxxx",
    "status": "cancelled",
    "amount": 299,
    "currency": "MZN",
    "interval": "monthly",
    "reference": "SUB-001",
    "cancelled_at": "2026-08-15T10:00:00Z"
  }
}

EVENTsubscription.renewed

subscription.renewed

Disparado quando uma assinatura é renovada com sucesso no ciclo de cobrança.

Payload Example

json

{
  "id": "evt_1e2f3a4b5c",
  "type": "subscription.renewed",
  "created_at": "2026-08-30T00:00:00Z",
  "livemode": false,
  "data": {
    "id": "sub_xxxxx",
    "status": "active",
    "amount": 299,
    "currency": "MZN",
    "interval": "monthly",
    "reference": "SUB-001",
    "nextBillingDate": "2026-09-30",
    "payment_id": "pay_renew_xxxxx"
  }
}

Schemas

Estruturas de dados reutilizáveis da API.

B2CRequest

Campo	Tipo	Descrição
`phone`	string	Número de telemóvel do beneficiário.
`amount`	number	Montante a enviar.
`currency`	string	Moeda ISO 4217. Predefinição: MZN.
`reference`	string	Referência externa opcional do payout.

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "phone",
    "amount"
  ],
  "description": "Pedido para enviar dinheiro a um cliente (Business to Customer).",
  "properties": {
    "phone": {
      "type": "string",
      "description": "Número de telemóvel do beneficiário.",
      "example": "841234567"
    },
    "amount": {
      "type": "number",
      "minimum": 0,
      "description": "Montante a enviar.",
      "example": 100
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "default": "MZN",
      "description": "Moeda ISO 4217. Predefinição: MZN.",
      "example": "MZN"
    },
    "reference": {
      "type": "string",
      "description": "Referência externa opcional do payout.",
      "example": "PAYOUT-100"
    }
  }
}

B2CResponse

Campo	Tipo	Descrição
`id`	string	Identificador do envio.
`status`	string enum	Estado actual do envio.
`amount`	number
`currency`	string
`reference`	string
`createdAt`	string (date-time)	Data de criação (presente em consultas GET).

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status",
    "amount",
    "currency"
  ],
  "description": "Transacção B2C criada ou consultada.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador do envio.",
      "example": "out_xxxxx"
    },
    "status": {
      "type": "string",
      "enum": [
        "processing",
        "completed",
        "failed",
        "cancelled"
      ],
      "description": "Estado actual do envio.",
      "example": "processing"
    },
    "amount": {
      "type": "number",
      "example": 100
    },
    "currency": {
      "type": "string",
      "example": "MZN"
    },
    "reference": {
      "type": "string",
      "example": "PAYOUT-100"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Data de criação (presente em consultas GET).",
      "example": "2026-07-30T16:00:00Z"
    }
  }
}

C2BRequest

Campo	Tipo	Descrição
`phone`	string	Número de telemóvel do pagador (MSISDN local, sem +258).
`amount`	number	Montante a cobrar.
`currency`	string	Moeda ISO 4217. Predefinição: MZN.
`reference`	string	Referência externa opcional (ex.: ID da encomenda).
`description`	string	Descrição legível do pagamento.

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "phone",
    "amount"
  ],
  "description": "Pedido para iniciar uma cobrança Customer to Business (C2B).",
  "properties": {
    "phone": {
      "type": "string",
      "description": "Número de telemóvel do pagador (MSISDN local, sem +258).",
      "example": "841234567"
    },
    "amount": {
      "type": "number",
      "minimum": 0,
      "description": "Montante a cobrar.",
      "example": 100
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "default": "MZN",
      "description": "Moeda ISO 4217. Predefinição: MZN.",
      "example": "MZN"
    },
    "reference": {
      "type": "string",
      "description": "Referência externa opcional (ex.: ID da encomenda).",
      "example": "ORDER-1001"
    },
    "description": {
      "type": "string",
      "description": "Descrição legível do pagamento.",
      "example": "Pagamento da encomenda"
    }
  }
}

C2BResponse

Campo	Tipo	Descrição
`id`	string	Identificador do pagamento.
`status`	string enum	Estado actual do pagamento.
`amount`	number
`currency`	string
`reference`	string	Referência externa, se fornecida.
`createdAt`	string (date-time)	Data de criação (presente em consultas GET).

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status",
    "amount",
    "currency"
  ],
  "description": "Pagamento C2B criado ou consultado.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador do pagamento.",
      "example": "pay_xxxxx"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "paid",
        "failed"
      ],
      "description": "Estado actual do pagamento.",
      "example": "pending"
    },
    "amount": {
      "type": "number",
      "example": 100
    },
    "currency": {
      "type": "string",
      "example": "MZN"
    },
    "reference": {
      "type": "string",
      "description": "Referência externa, se fornecida.",
      "example": "ORDER-1001"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Data de criação (presente em consultas GET).",
      "example": "2026-07-30T15:30:00Z"
    }
  }
}

Customer

Campo	Tipo	Descrição
`name`	string	Nome completo do cliente.
`email`	string (email)	Email do cliente.
`phone`	string	Número de telemóvel (opcional).

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "email"
  ],
  "description": "Dados do cliente associado a uma assinatura ou pagamento.",
  "properties": {
    "name": {
      "type": "string",
      "description": "Nome completo do cliente.",
      "example": "John Doe"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Email do cliente.",
      "example": "john@example.com"
    },
    "phone": {
      "type": "string",
      "description": "Número de telemóvel (opcional).",
      "example": "841234567"
    }
  }
}

ErrorResponse

Campo	Tipo	Descrição
`error`	object

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "error"
  ],
  "description": "Resposta de erro padrão da API pública.",
  "properties": {
    "error": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Código de erro estável.",
          "example": "PAYMENT_PROCESSING_ERROR"
        },
        "message": {
          "type": "string",
          "description": "Mensagem legível para o cliente.",
          "example": "Unable to process payment."
        }
      }
    }
  }
}

Money

Campo	Tipo	Descrição
`amount`	number	Valor na unidade principal da moeda (ex.: 100 = 100 MZN).
`currency`	string	Código ISO 4217 da moeda.

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "amount",
    "currency"
  ],
  "description": "Montante monetário com moeda ISO 4217.",
  "properties": {
    "amount": {
      "type": "number",
      "minimum": 0,
      "description": "Valor na unidade principal da moeda (ex.: 100 = 100 MZN).",
      "example": 100
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "default": "MZN",
      "description": "Código ISO 4217 da moeda.",
      "example": "MZN"
    }
  }
}

SubscriptionRequest

Campo	Tipo	Descrição
`customer`	Customer
`amount`	number	Valor cobrado em cada ciclo.
`currency`	string	Moeda ISO 4217. Predefinição: MZN.
`interval`	string enum	Frequência de cobrança.
`reference`	string	Referência externa opcional da assinatura.

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "customer",
    "amount",
    "interval"
  ],
  "description": "Pedido para criar uma assinatura recorrente.",
  "properties": {
    "customer": {
      "$ref": "#/components/schemas/Customer"
    },
    "amount": {
      "type": "number",
      "minimum": 0,
      "description": "Valor cobrado em cada ciclo.",
      "example": 299
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "default": "MZN",
      "description": "Moeda ISO 4217. Predefinição: MZN.",
      "example": "MZN"
    },
    "interval": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "yearly"
      ],
      "description": "Frequência de cobrança.",
      "example": "monthly"
    },
    "reference": {
      "type": "string",
      "description": "Referência externa opcional da assinatura.",
      "example": "SUB-001"
    }
  }
}

SubscriptionResponse

Campo	Tipo	Descrição
`id`	string	Identificador da assinatura.
`status`	string enum	Estado da assinatura.
`amount`	number
`currency`	string
`interval`	string enum
`reference`	string
`nextBillingDate`	string (date)	Próxima data de cobrança (YYYY-MM-DD).
`customer`	Customer

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status"
  ],
  "description": "Assinatura criada ou consultada.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador da assinatura.",
      "example": "sub_xxxxx"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "cancelled",
        "past_due",
        "paused"
      ],
      "description": "Estado da assinatura.",
      "example": "active"
    },
    "amount": {
      "type": "number",
      "example": 299
    },
    "currency": {
      "type": "string",
      "example": "MZN"
    },
    "interval": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "yearly"
      ],
      "example": "monthly"
    },
    "reference": {
      "type": "string",
      "example": "SUB-001"
    },
    "nextBillingDate": {
      "type": "string",
      "format": "date",
      "description": "Próxima data de cobrança (YYYY-MM-DD).",
      "example": "2026-08-30"
    },
    "customer": {
      "$ref": "#/components/schemas/Customer"
    }
  }
}

WebhookEvent

Campo	Tipo	Descrição
`id`	string	Identificador único do evento.
`type`	string enum	Tipo do evento.
`created_at`	string (date-time)	Momento em que o evento foi gerado (UTC).
`livemode`	boolean	`true` se o evento ocorreu em modo live; `false` em modo test.
`data`	object	Objecto com os dados do recurso associado ao evento.

json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "type",
    "created_at",
    "livemode",
    "data"
  ],
  "description": "Payload enviado pela Kivora ao URL de webhook configurado no dashboard.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador único do evento.",
      "example": "evt_1a2b3c4d5e"
    },
    "type": {
      "type": "string",
      "enum": [
        "payment.created",
        "payment.pending",
        "payment.completed",
        "payment.failed",
        "b2c.created",
        "b2c.processing",
        "b2c.completed",
        "b2c.failed",
        "subscription.created",
        "subscription.cancelled",
        "subscription.renewed"
      ],
      "description": "Tipo do evento.",
      "example": "payment.completed"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Momento em que o evento foi gerado (UTC).",
      "example": "2026-07-30T15:31:00Z"
    },
    "livemode": {
      "type": "boolean",
      "description": "`true` se o evento ocorreu em modo live; `false` em modo test.",
      "example": false
    },
    "data": {
      "type": "object",
      "additionalProperties": true,
      "description": "Objecto com os dados do recurso associado ao evento.",
      "properties": {
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "amount": {
          "type": "number"
        },
        "currency": {
          "type": "string"
        },
        "reference": {
          "type": "string"
        }
      }
    }
  }
}