Ziina Webhooks API

# Ziina API - OpenAPI 3.0
# Provenance: fetched-spec, merged from Ziina's two published OpenAPI 3.0.0 documents on 2026-07-17:
#   https://docs.ziina.com/api-reference/payment-service-openapi.json (HTTP 200)
#   https://docs.ziina.com/api-reference/account-manager-openapi.json (HTTP 200)
# Both declare server https://api-v2.ziina.com/api and HTTP bearer (JWT) security.
# The /account operation was merged in from the Account API document; paths and schemas are otherwise verbatim.
openapi: 3.0.0
info:
  title: Ziina API
  version: 1.0.0
  description: Ziina payment platform REST API for the UAE. Create and retrieve payment intents (hosted
    and embedded checkout), issue refunds, initiate peer transfers between Ziina accounts, register webhook
    endpoints for payment events, and read account details. Amounts are passed in the base (minor) unit
    of the currency (fils for AED); the minimum charge is 2 AED. Auth is HTTP bearer (JWT) via OAuth 2.0
    access tokens with granular scopes (read_account, write_payment_intents, write_refunds, write_transfers,
    write_webhooks).
  contact:
    name: Ziina Support
    email: support@ziina.com
    url: https://docs.ziina.com
servers:
- url: https://api-v2.ziina.com/api
  description: Ziina production API
tags:
- name: PaymentIntent
  description: Create and retrieve payment intents (hosted/embedded checkout).
- name: Refund
  description: Issue and retrieve refunds against a payment intent.
- name: Transfer
  description: Initiate and retrieve peer transfers between Ziina accounts.
- name: Webhook
  description: Register or delete a webhook endpoint for payment events.
- name: Account
  description: Retrieve the authenticated account profile.
- name: HealthCheck
  description: Service status.
paths:
  /payment_intent/{id}:
    get:
      description: Get a payment intent by its ID
      operationId: PaymentIntentController_getPaymentIntent
      parameters:
      - name: id
        required: true
        in: path
        description: id of the payment intent
        schema:
          type: string
      responses:
        default:
          description: Created payment intent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentIntentDto'
      summary: ''
      tags:
      - PaymentIntent
  /payment_intent:
    post:
      operationId: PaymentIntentController_createPaymentIntent
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentIntentDto'
      responses:
        default:
          description: Created payment intent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentIntentDto'
      tags:
      - PaymentIntent
  /transfer:
    post:
      operationId: TransferController_initiateTransfer
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateTransferDto'
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentIntentDto'
      tags:
      - Transfer
  /transfer/{id}:
    get:
      description: Get a transfer by its ID. Caller must be the payer or the receiver.
      operationId: TransferController_getTransfer
      parameters:
      - name: id
        required: true
        in: path
        description: id of the transfer
        schema:
          type: string
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferDto'
      summary: ''
      tags:
      - Transfer
  /refund:
    post:
      operationId: RefundController_initiateRefund
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateRefundDto'
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundDto'
      tags:
      - Refund
  /refund/{id}:
    get:
      operationId: RefundController_getRefund
      parameters:
      - name: id
        required: true
        in: path
        description: id of the refund
        schema:
          type: string
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundDto'
      tags:
      - Refund
  /webhook:
    post:
      operationId: WebhookController_createWebhook
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetWebhookRequestDto'
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponseDto'
      tags:
      - Webhook
    delete:
      operationId: WebhookController_deleteWebhook
      parameters: []
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponseDto'
      tags:
      - Webhook
  /log:
    post:
      operationId: LogController_processLog
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogDto'
      responses:
        '201':
          description: ''
      tags:
      - Log
  /status:
    get:
      operationId: HealthCheckController_getStatus
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - HealthCheck
  /account:
    get:
      summary: Retrieve account information
      description: Fetch details about the account based on the provided Bearer token in the Authorization
        header.
      responses:
        default:
          description: Successful response with account information
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_id:
                    type: string
                    description: Unique identifier for the account
                  account_type:
                    type: string
                    enum:
                    - personal
                    - business
                    description: Type of the account
                  status:
                    type: string
                    enum:
                    - onboarding
                    - active
                    - locked
                    - deleted
                    - restrictedTransfer
                    description: Current status of the account
                  ziiname:
                    type: string
                    description: Ziina username associated with the account
                  display_name:
                    type: string
                    description: Display name of the account holder
                  profile_picture_url:
                    type: string
                    format: url
                    description: URL of the profile picture
              example:
                account_id: <UUID>
                account_type: personal
                status: active
                ziiname: ziina_user
                display_name: John Doe
                profile_picture_url: https://example.com/profile.jpg
      tags:
      - Account
      operationId: AccountController_getAccount
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
  schemas:
    ErrorDto:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message
        code:
          type: string
          description: HTTP error status code
      required:
      - message
      - code
    PaymentIntentDto:
      type: object
      properties:
        id:
          type: string
          description: id of the payment intent
        account_id:
          type: string
          description: Account which will receive payment
        amount:
          type: number
          description: Transaction amount. Values must be passed in the base units of their currency.
            For example, $10.50 should be provided as `1050`.
        tip_amount:
          type: number
          description: The amount of tips to be added to the payment intent
        fee_amount:
          type: number
          description: The amount of fees paid for this payment intent
        currency_code:
          type: string
          description: Currency code of the amount to charge. This should be a 3-letter ISO-4217 currency
            code. For example, if you wish to charge 10 AED, you should pass AED. For more information
            on supported currencies, please visit the [supported currencies page](/supported-currencies)
        created_at:
          type: string
          description: Unix timestamp in milliseconds
        status:
          type: string
          enum:
          - requires_payment_instrument
          - requires_user_action
          - pending
          - completed
          - failed
          - canceled
          description: Status of the transaction. You can find more details [here](/api-reference/payment-intent/index#fetching-a-payment-intent)
        operation_id:
          type: string
          description: Unique client generated UUID. In case of retries provide the same operation_id
        message:
          type: string
          description: A message to be displayed to the user on the hosted payment page
        redirect_url:
          type: string
          description: The URL to be used to redirect the client to the hosted payment page
        embedded_url:
          type: string
          description: The URL to be used to show embedded payment page with the payment widget
        success_url:
          type: string
          description: The URL to be called by the hosted web page when the payment is successful
        cancel_url:
          type: string
          description: The URL to be called by the hosted web page when the payment is cancelled
        latest_error:
          description: An error that was encountered while processing the payment intent
          allOf:
          - $ref: '#/components/schemas/ErrorDto'
        allow_tips:
          type: boolean
          default: false
          description: Whether tips are allowed for this payment intent
      required:
      - id
      - account_id
      - amount
      - tip_amount
      - currency_code
      - created_at
      - status
      - operation_id
    CreatePaymentIntentDto:
      type: object
      properties:
        amount:
          type: number
          description: Transaction amount. Values must be passed in the base units of their currency.
            For example, $10.50 should be provided as `1050`.
        currency_code:
          type: string
          description: Currency code of the amount to charge. This should be a 3-letter ISO-4217 currency
            code. For example, if you wish to charge 10 AED, you should pass AED. For more information
            on supported currencies, please visit the [supported currencies page](/supported-currencies)
          minLength: 3
          maxLength: 3
        message:
          type: string
          description: A message to be displayed to the user on the hosted payment page
        success_url:
          type: string
          description: The URL to be called by the hosted web page when the payment is successful
        cancel_url:
          type: string
          description: The URL to be called by the hosted web page when the payment is cancelled
        failure_url:
          type: string
          description: Url where user will be redirected after failed payment
        test:
          type: boolean
          description: Whether to create a test payment. Test payments do not require a payment method
            and can be used to test the payment flow. You won't be charged for this call. You can use
            [test cards](/test-cards) to test the payment flow.
        expiry:
          type: string
          description: Unix timestamp in milliseconds, must be a future date
        allow_tips:
          type: boolean
          default: false
          description: Whether to allow tips for this payment intent
      required:
      - amount
      - currency_code
    InitiateTransferDto:
      type: object
      properties:
        operation_id:
          type: string
          description: Unique client generated UUID. In case of retries provide the same operation_id
        to_account_ids:
          description: 'Array of account ids to transfer to. You need to specify only one of the properties:
            to_account_ids or to_ziinames'
          type: array
          items:
            type: string
        to_ziinames:
          description: 'Array of ziinames to transfer to. You need to specify only one of the properties:
            to_account_ids or to_ziinames'
          type: array
          items:
            type: string
        amount:
          type: number
          description: Transaction amount. Values must be passed in the base units of their currency.
            For example, $10.50 should be provided as `1050`.
        currency_code:
          type: string
          description: Currency code of the amount to charge. This should be a 3-letter ISO-4217 currency
            code. For example, if you wish to charge 10 AED, you should pass AED. For more information
            on supported currencies, please visit the [supported currencies page](/supported-currencies)
        message:
          type: string
          description: A message to be displayed to the user on the hosted payment page
      required:
      - operation_id
      - to_account_ids
      - to_ziinames
      - amount
      - currency_code
    TransferDto:
      type: object
      properties:
        id:
          type: string
          description: id of the transfer
        account_id:
          type: string
          description: Account which will receive the transfer
        amount:
          type: number
          description: Transaction amount. Values must be passed in the base units of their currency.
            For example, $10.50 should be provided as `1050`.
        currency_code:
          type: string
          description: Currency code of the amount to charge. This should be a 3-letter ISO-4217 currency
            code. For example, if you wish to charge 10 AED, you should pass AED. For more information
            on supported currencies, please visit the [supported currencies page](/supported-currencies)
        created_at:
          type: string
          description: Unix timestamp in milliseconds
        status:
          type: string
          enum:
          - requires_payment_instrument
          - requires_user_action
          - pending
          - completed
          - failed
          - canceled
          description: Status of the transaction. You can find more details [here](/api-reference/payment-intent/index#fetching-a-payment-intent)
        operation_id:
          type: string
          description: Unique client generated UUID. In case of retries provide the same operation_id
        message:
          type: string
          description: Optional text comment attached to a transfer. Displayed to the user in the app
            as part of the transaction details.
      required:
      - id
      - account_id
      - amount
      - currency_code
      - created_at
      - status
      - operation_id
    InitiateRefundDto:
      type: object
      properties:
        id:
          type: string
          description: Unqiue client generated UUID of the refund
        payment_intent_id:
          type: string
          description: id of the payment intent
        amount:
          type: number
          description: Transaction amount. Values must be passed in the base units of their currency.
            For example, $10.50 should be provided as `1050`.
        currency_code:
          type: string
          description: Currency code of the amount to charge. This should be a 3-letter ISO-4217 currency
            code. For example, if you wish to charge 10 AED, you should pass AED. For more information
            on supported currencies, please visit the [supported currencies page](/supported-currencies)
        test:
          type: boolean
          description: Whether to create a test payment. Test payments do not require a payment method
            and can be used to test the payment flow. You won't be charged for this call. You can use
            [test cards](/test-cards) to test the payment flow.
      required:
      - id
      - payment_intent_id
    RefundDto:
      type: object
      properties:
        id:
          type: string
          description: Id of the refund
        payment_intent_id:
          type: string
          description: id of the payment intent
        amount:
          type: number
          description: Transaction amount. Values must be passed in the base units of their currency.
            For example, $10.50 should be provided as `1050`.
        currency_code:
          type: string
          description: Currency code of the amount to charge. This should be a 3-letter ISO-4217 currency
            code. For example, if you wish to charge 10 AED, you should pass AED. For more information
            on supported currencies, please visit the [supported currencies page](/supported-currencies)
        status:
          type: string
          enum:
          - pending
          - completed
          - failed
        created_at:
          type: string
          description: Unix timestamp in milliseconds
        error:
          nullable: true
          description: Optional error
          allOf:
          - $ref: '#/components/schemas/ErrorDto'
      required:
      - id
      - payment_intent_id
      - amount
      - currency_code
      - status
      - created_at
    SetWebhookRequestDto:
      type: object
      properties:
        url:
          type: string
          description: Url where webhooks will be sent
        secret:
          type: string
          description: Optional. Provide your client secret if you want to verify the authenticity of
            the request using HMAC. This ensures the request hasn't been tampered with. You can generate
            your own secret and use it consistently for signing and verifying requests.
      required:
      - url
    WebhookResponseDto:
      type: object
      properties:
        success:
          type: boolean
          description: true if request was successful, false otherwise
        error:
          type: string
          description: Optional error message
      required:
      - success
    LogDto:
      type: object
      properties: {}
security:
- bearer: []