Initiate a full or partial refund against a payment intent (POST /refund) and retrieve refund status (GET /refund/{id}). Requires the write_refunds scope.
# 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: []