# 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: 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: []