# Operations

In the evolving landscape of businesses, the necessity to perform subsequent operations on a payment often emerges. These may include issuing a refund, or making a payment link unavailable, effectively cancelling a payment to prevent a customer from proceeding with it. Ottu’s Operations API has been meticulously designed to facilitate seamless payment integration between your merchant system and the [Payment Gateway](https://docs.ottu.com/user-guide/payment-gateway) (PG). One of Ottu’s standout features is the concept of a Unified API. With this approach, Ottu accepts a uniform payload structure, irrespective of the targeted payment gateway. Ottu takes on the role of managing the intricate communication with the PG, effectively relieving your team of the heavy-lifting. Ottu offers a total of six operations. Three are [Internal Operations](#internal-operations), performed within Ottu’s system itself: [cancel](#cancel), [delete](#delete), and [expire](#expire). If any of these operations are triggered and the payment transaction is in a valid state for that operation, the payment transaction state is updated directly within Ottu’s system. The other three operations are [External Operations](#external-operations), synchronized with the Payment Gateway level: [refund](#refund-1), [capture](#capture-1), and [void](#void-1). For these operations, when a request is initiated by the merchant, Ottu communicates with the corresponding PG to attempt the operation, thus ensuring synchronization.

{% hint style="info" %}
Ottu’s Operations API provides a seamless and unified interface for performing subsequent operations on a payment, including refunds, cancellations, and expiration. It ensures consistent communication with different payment gateways, lifting the burden of direct interaction.
{% endhint %}

Importantly, if a PG accepts an operation, a [child payment transaction](https://docs.ottu.com/user-guide/payment-tracking#states-of-child-payment-transaction) is created within Ottu’s system. This child transaction, [linked](https://docs.ottu.com/user-guide/payment-tracking#child-table-transaction) to the original payment transaction against which the operation was triggered, will record the new state along with the PG’s response, the operational [amount](https://docs.ottu.com/user-guide/payment-tracking#amount-definitions-and-calculation-mechanism), and the [currency code](https://docs.ottu.com/checkout-api#currency_code-string-required). For example, if a payment transaction of 100 KWD has been processed and the merchant now wishes to issue a `refund` of 20 KWD, triggering the operation will not change the state or amount of the original payment transaction. Instead, a child transaction will be created within Ottu’s system, reflecting the refunded amount of 20 KWD, the currency, and the new state as `refund`. Please note that **not** all payment gateways support all external operations. Ottu is consistently working to broaden its payment gateway integrations. However, if a particular payment gateway does not offer support for certain operations, Ottu is unable to facilitate those specific operations. In such cases, API calls for unsupported external operations will be rejected by Ottu, with an appropriate error message indicating the lack of support. For a comprehensive list of payment gateways and the operations they support see [Operation Definitions & Conditions](https://docs.ottu.com/user-guide/payment-gateway#operation-definitions-and-conditions).

{% hint style="warning" %}
Please be aware that operations via the Operations API do not function with **foreign currencies**. If your customer has completed a payment using a [currency exchange](https://docs.ottu.com/user-guide/currencies#currency-exchanges) (for instance, if the Merchant ID or MID is set to KWD but the customer has paid the amount in USD using Ottu's currency exchange to calculate and display the amount), external operations will not be successful. External operations only work when the payment currency is identical to the MID currency.
{% endhint %}

The Operations API is part of Ottu’s ongoing commitment to development, and the recent upgrade to **version 2** is testament to this. Nevertheless, the documentation for **version 1** of the operation API remains accessible [here](https://app.gitbook.com/o/QvpaILbKwb9WBfHGe5bZ/s/HliFFcthyaYAsSykrr31/). It’s worth noting that certain conditions must be met to perform operations, and not all PGs support all operations. For more details, please see our section on [Operation Definitions & Conditions.](https://docs.ottu.com/user-guide/payment-gateway#operation-definitions-and-conditions)

{% hint style="info" %}
Ottu’s Operations API supports both system-side operations `cancel`, `delete`, `expire` and gateway-level operations `capture`, `refund`, `void`, ensuring your transaction data is always in sync with the PG. Remember, availability of gateway-level operations may depend on the specific payment gateway’s capabilities.
{% endhint %}

## [Setup](#setup)

Before proceeding with any operation, it is essential to have an existing payment transaction. This transaction can be created in one of two ways:

1. **Via the Checkout API:** You can initiate a payment transaction through Ottu’s [Checkout API](https://docs.ottu.com/developer/checkout-api). This will create a new transaction and return a unique [session\_id](https://docs.ottu.com/checkout-api#session_id-string-mandatory) which you can use for subsequent operations.
2. **Via the Ottu Dashboard:** Alternatively, you can manually create a payment transaction directly from the Ottu Dashboard. Check [Creating Payment Request](https://docs.ottu.com/getting-started#creating-payment-request). From the dashboard, you can track and manage all your transactions. See [Payment Tracking](https://docs.ottu.com/user-guide/payment-tracking).

Once a payment transaction has been initiated, you will receive either a [session\_id](https://docs.ottu.com/checkout-api#session_id-string-mandatory) or an [order\_no](https://docs.ottu.com/checkout-api#order_no-string-optional). It is recommended to use the session\_id for operations, as it is always present in the response, whereas order\_no is a property defined by the merchant and may not always be available. Remember to securely store these identifiers, as they are essential for performing operations on the payment transaction.

### [Boost Your Integration](#boost-your-integration)

To enhance your integration with Operation APIs such as [Cancel](#cancel), [Expire](#expire), [Delete](#delete), [Capture](#capture), [Refund](#refund), and [Void](#void), consider leveraging our dedicated Python SDK. This SDK simplifies the integration process by encapsulating complex API interactions, thus allowing you to focus on the core functionalities of your business.

**Available Package:**

* **Python SDK:** Streamlines the management of operations like cancellation, expiration, deletion, capture, refund, and void actions through a straightforward, object-oriented interface. [Learn more](https://github.com/ottuco/ottu-py?tab=readme-ov-file#operations)
* **Django SDK:** Seamlessly integrates payment methods into Django projects, offering specialized tools and utilities that simplify payment processes. [Explore details](https://github.com/ottuco/ottu-py?tab=readme-ov-file#django-integration)

Understanding the key concepts and frameworks documented is crucial for utilizing this package effectively and ensuring robust, maintainable integration.

## [Authentication](#authentication)

To interact with Ottu’s Operation API, both [API-Key](https://docs.ottu.com/authentication#private-key-api-key) and [Basic Authentication](https://docs.ottu.com/authentication#basic-authentication) methods are supported. Using the API Key for authentication provides superadmin privileges, enabling the performance of any operation. It’s crucial to handle this information with utmost care and restrict its sharing to prevent misuse. For enhanced security, it is recommended to use Basic Authentication and assign specific permissions, ensuring controlled access to different API endpoints.

{% hint style="info" %}
For optimal security, we highly recommend using Basic Authentication and assigning specific permissions to control access to various API endpoints.
{% endhint %}

## [Permissions](#permissions)

**API Key:** Superadmin privileges are automatically granted to the [private API Key](https://docs.ottu.com/authentication#private-key). For more information on using the API Key, check this [resource](https://docs.ottu.com/authentication#private-key-api-key).

**Basic Authentication:** This method works with any user and permission that has access to the system. If a user is a superadmin, they have access to all operations. However, for a more granular control, you can assign specific permissions to the user.

Each action performed on the system is logged and can be traced back to the specific user who performed the operation. For this reason, it’s strongly recommended not to share a single user among multiple people. Instead, create an individual user for each person who needs access. Permissions can be assigned for one or more specific operations. 

#### Permission codes for each operation:

* `payment.capture`: For the **Capture** operation
* `payment.expire`: For the **Expire** operation
* `payment.refund`: For the **Refund** operation
* `payment.void`: For the **Void** operation
* `payment.cancel`: For the **Cancel** operation
* `payment.delete`: For the **Delete** operation
* `payment.inquiry`: For the **Inquiry** operation

{% hint style="info" %}
Remember to assign the relevant permissions to your users based on the operations they need to perform.
{% endhint %}

## [Internal Operations](#internal-operations)

Internal operations are actions performed directly on Ottu’s system level, affecting the status of transactions without interacting with external payment gateways. They provide control over transaction lifecycles and data management.

### [Cancel](#cancel)

The Payment Cancel operation is employed to halt a payment process in progress. It’s applicable to transactions in the following states:

* `created`
* `pending`
* `cod`
* `attempted`

This operation provides a means for a merchant to stop a payment process that hasn’t reached its completion.

### [Expire](#expire)

The Expire operation is used to automatically invalidate a payment transaction that hasn’t been completed within a certain period of time. This operation targets transactions in these states:

* `created`
* `pending`
* `attempted`

It ensures that lingering incomplete payments are tidied up by transitioning them to an `expired` state, from which they cannot be resumed or completed.

### [Delete](#delete)

The Delete operation allows for the removal of transactions that are no longer needed. The action taken depends on the current state of the transaction:

* For transactions in the `paid`, `authorized`, or `cod/cash` state, a soft deletion is applied. These transactions are removed from reports and dashboard listings but remain retrievable from the Deleted Transactions section.
* For all other transaction states, a hard delete is executed, resulting in the permanent removal of the transactions from the system.

## [External Operations](#external-operations)

External operations involve communication with [payment gateways](https://docs.ottu.com/user-guide/payment-gateway), aiming to modify the state of transactions on the payment gateway’s side. These operations provide additional control over the payment lifecycle by allowing further actions after initial payment authorization. They include Capture, Refund, and Void operations. Not all payment gateways support all operations. Check [here](https://docs.ottu.com/user-guide/payment-gateway#available-operations) to see which operations are supported by each payment gateway.

### [Capture](#capture)

The Capture operation is a function that lets merchants secure authorized funds for transactions that haven’t yet been settled. This operation can only be performed on transactions in the `authorized` state. Merchants can opt to capture the full authorized amount or just a portion of it, however, capturing more than the authorized amount is not possible. If the operation is successful, a [child transaction](https://docs.ottu.com/user-guide/payment-tracking/payment-transactions-states#child-payment-transaction) linked to the original payment transaction is created, which contains the details of the capture operation. Child transactions can be tracked in the [Child Transaction Table](https://docs.ottu.com/user-guide/payment-tracking/payment-transactions-insights#transaction-table).

### [Refund](#refund)

The Refund operation enables merchants to refund previously captured or paid transactions, effectively returning funds back to the customer’s account when necessary. To carry out a refund on an authorized payment transaction, a prior [capture ](#capture)operation must have been completed and the captured amount must be sufficient to cover the refund. For paid transactions, the refund amount should not exceed the paid amount. The refund can be done either fully or partially.

Just like the Capture operation, a successful refund operation creates a [child transaction](https://docs.ottu.com/user-guide/payment-tracking/payment-transactions-states#child-payment-transaction) linked to the [parent transaction](https://docs.ottu.com/user-guide/payment-tracking/payment-transactions-states#parent-payment-transaction), containing all the details related to the refund. Ottu also offers an [approval feature](https://docs.ottu.com/user-guide/features/two-step-refund-and-void-authorization) for refund operations, enabling merchants to assign a checker role to specific staff members. This checker can approve or reject any refund requests, thus preventing unauthorized or fraudulent refunds.

Additionally, Ottu provides an `extra` object field, which is optional and serves to specify additional parameters for the operation. This field is generally utilized to support the Instant Fund Gratification (IFG) feature. IFG refers to a capability where refunds are processed instantly or very quickly following a transaction cancellation or return request.

### [Void](#void)

The Void operation allows merchants to cancel an `authorized` payment transaction before a capture operation is performed. This means that the transaction won’t be captured and the customer will not be charged. The Void operation is strictly applicable to transactions in the `authorized`state.

## [Tracking-Key Header](#tracking-key-header)

### [Overview](#overview)

The `Tracking-Key`, in the context of the Operation API, is a unique identifier embedded in the header of each [external operation](#external-operations) request initiated by the merchant. This key plays a pivotal role in maintaining the distinctiveness of every operation transaction, ensuring precise tracking and efficient retrieval of the latest status information.

### [Purpose of Tracking Key](#purpose-of-tracking-key)

It enables merchants to obtain the most recent status of an operation without the possibility of triggering **duplicate operations** in subsequent requests when using the same key.

### [Guide: Step by Step](#guide-step-by-step)

In this section will delve into an example illustrating how a merchant can employ the `Tracking-Key`.

#### 1. [Perform Operation Request](#1.-perform-operation-request)

The merchant initiates the process by including the `Tracking-Key` in the header of the operation API when submitting a request. This key serves as a distinctive identifier, differentiating each operation initiated by the merchant from others.

To prevent the occurrence of multiple operations, the `Tracking-Key`, once added during the initial operation, is stored in the [child payment transaction](https://docs.ottu.com/user-guide/payment-tracking/payment-transactions-states#child-payment-transaction) data. **Consequently**, if the same `Tracking-Key`is later included in the header of **any** [external operation API](#external-operations) with the `session_id` or `order_no`,whether it was previously associated with the Tracking-Key or not, the system will refrain from initiating a new operation. Instead, it will promptly provide the latest operation status response. \
**Nevertheless,** if the initial operation performed unsuccessfully, the `Tracking Key` will not be stored.

#### **Example:** 

The merchant initiates a POST [Refund](#refund) request by submitting the [session\_id](https://docs.ottu.com/checkout-api#session_id-string-mandatory) of the previous paid transaction and specifying the refund `amount`.  Additionally, a new header parameter, `Tracking-Key`, is included, with "`trackingtest`" used as an example value for demonstration purposes.

#### **Header Parameter:**

```json
Tracking-Key: "trackingtest"
```

#### **Body Parameters:**

```json
{
    "operation": "refund",
    "session_id": "2a956e4c9294c2c0e9253c21b1a592ceb4018c68",
    "amount": "1"
}
```

#### 2. [**Retrieve the Latest Operation Status**](#2.-retrieve-the-latest-operation-status)

When the merchant seeks to inquire about the status of a previously conducted operation, he should initiate another operation request using the same `Tracking-Key` value as the one utilized in the initial targeted operation transaction.

* The merchant should include a new header parameter, `Tracking-Key`, with the same value as in the previous operation transaction.
* Alongside the `Tracking-Key`, the [session\_id](https://docs.ottu.com/checkout-api#session_id-string-mandatory) / [order\_no](https://docs.ottu.com/checkout-api#order_no-string-optional) of the specified operation transaction should be provided in the operation request.
* Regardless of the `session_id`/`order_no`, `amount` (no need to provide), and `operation` parameter values provided within the external operation request, the response will consistently provide the latest status of the original operation request from the initial provision of the `Tracking-key`  value.

#### Example:

The merchant initiates a new operation request, employing the same `Tracking-Key`, `session_id`, and operation parameters as specified in the last [Example](#example).

#### **Header Parameter:**

```json
Tracking-Key: "trackingtest"
```

#### **Body Parameters:**

```json
{
    "operation": "refund",
    "session_id": "2a956e4c9294c2c0e9253c21b1a592ceb4018c68"
}
```

#### **Response:**

Ottu's system, recognizing the `Tracking-Key` and the associated `session_id` retrieves the relevant transaction details from the database. The response to the operation request includes the latest status information for the origin operation transaction.

```json
{
   "amount":"1.00",
   "amount_details":{
      "currency_code":"SAR",
      "amount":"1.0",
      "total":"1.0",
      "fee":"0"
   },
   "currency_code":"SAR",
   "customer_id":"Example_id",
   "customer_phone":"12345678",
   "extra":{},
   "gateway_account":"Credit-Card",
   "gateway_name":"mpgs",
   "gateway_response":{
      It will contain the raw pg response sent by the pg to Ottu
   },
   "initiator":{},
   "is_sandbox":true,
   "payment_type":"one_off",
   "reference_number":"SMAUGGGLERDK",
   "remaining_amount":"1.000",
   "result":"success",
   "session_id":"cb4b9e4cde8f2ac9664eba743497657d13e3c9b6",
   "signature":"3f312d13**************",
   "state":"refunded",
   "timestamp_utc":"2023-11-23 11:20:50"
}
```

For a more detailed technical understanding and the implementation specifics of these operations, please refer to the OpenAPI schema in the [Operation API Schema Reference](#operation-api-schema-reference).

## [Operation API Schema Reference](#operation-api-schema-reference)

## Operations

> The Payment Operations API provides an interface to manage your payment transactions beyond their initial creation. It allows for several operations including \`refund\`, \`capture\`, \`void\`, and others, directly syncing with the Payment Gateway (PG) for certain actions to ensure consistency across systems.\
> \
> Two key identifiers, \`order\_no\` and \`session\_id\`, can be used interchangeably to specify the payment transaction that the operation should be applied to.\
> \
> For operations such as \`refund\` and \`capture\`, you can optionally define the \`amount\` to be actioned. If not provided, the API will attempt to perform the operation on the full amount, or the remaining amount if previous operations were conducted. However, note that for \`void\`, the operation always applies to the full amount, ignoring the \`amount\` value if provided.\
> \
> This API also allows you to perform certain operations solely at the Ottu system level, providing increased control over your payment transactions.\
> \
> For every operation, the API provides a clear response containing information about the executed operation, a user-friendly message (\`detail\`), and the operation's result (\`success\` indicates a successful operation).\ <br>

```json
{"openapi":"3.1.1","info":{"title":"Ottu API","version":"1.0.0"},"servers":[{"url":"https://sandbox.ottu.net"}],"security":[{"SSO_BasicAuth":[]},{"basicAuth":[]},{"SSO_JWT_Auth":[]}],"components":{"securitySchemes":{"SSO_BasicAuth":{"type":"http","scheme":"basic"},"basicAuth":{"type":"http","scheme":"basic"},"SSO_JWT_Auth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Operation":{"type":"object","description":"Fetch the payment txn based on the order no or session id\nalso, if the payment txn is not in the accepted state for the\ninput operation, raise an error","properties":{"order_no":{"type":"string","description":"This is an optional identifier used to specify the payment transaction upon which the operation should be performed. You can use either the `order_no` or `session_id` field; at least one of these two identifiers must be provided to select the payment transaction that should be actioned.","maxLength":128},"session_id":{"type":"string","description":"Similar to `order_no`, `session_id` is an optional identifier used to specify the payment transaction for the operation. You must provide either `order_no` or `session_id` in order to select the appropriate payment transaction.","maxLength":128},"operation":{"enum":["delete","cancel","expire","refund","capture","void"],"type":"string","description":"* `delete` - delete\n* `cancel` - cancel\n* `expire` - expire\n* `refund` - refund\n* `capture` - capture\n* `void` - void"},"amount":{"type":"string","format":"decimal","pattern":"^-?\\d{0,13}(?:\\.\\d{0,3})?$","description":"This field is optional and used to specify the amount you want to action for `refund` and `capture` operations. If not specified, Ottu will attempt to perform the operation on the full amount, or the remaining amount if previous operations have been performed. Keep in mind that `void` operations always concern the full amount; the `amount` field is not considered in this case. The `amount` field can be sent for all operations, but it will only be taken into account for `refund` and `capture` operations."},"extra":{"type":"object","additionalProperties":{},"description":"This field is optional and used to specify additional parameters for the operation. \n\n**IFG**: \n\n<b>Full Refund Details</b>\n\nFor full refund you don't need to use extra key.\n\n<b>Partial Refund Details</b>\n\nFor operations involving partial refunds, the extra field allows specifying individual ticket orders along with their corresponding refund amounts.\n\nThis capability ensures precise control over the refund amounts for each ticket within an order.\n\n<b>Key Points</b>\n\n`passengerDocumentNumber`: It is imperative to include the document number for each ticket involved in the refund operation. This ensures that the refund is accurately applied to the correct tickets within an order.\n\n`amount`: Alongside each ticket document number, specify the desired refund amount for that ticket and make sure the type of amount is `INT`.\n\n`Excluding Tickets`:  If certain tickets within an order should not be refunded, you can specify a refund amount of zero for those tickets. This approach allows for selective refunding within a single order.\n\n`Important Note`\n\nAll tickets intended for refund must be explicitly listed in the refund order details, with their respective refund amounts clearly defined. This requirement ensures comprehensive and error-free processing of partial refunds.\n\n<b>Example</b>\n\ncheck in Request samples there is an example showcasing how to structure the extra field for a partial refund request, including specifying refund amounts for tickets"}},"required":["operation"]},"PaymentOperationResponses":{"oneOf":[{"$ref":"#/components/schemas/InternalOperation"},{"$ref":"#/components/schemas/ExternalOperation"}]},"InternalOperation":{"type":"object","properties":{"detail":{"type":"string","description":"Provides a message associated with the operation, suitable for displaying to the end user."},"operation":{"enum":["refund","void","capture","delete","cancel","expire"],"type":"string","description":"Specifies the executed operation. It can be either `delete`, `cancel`, or `expire`.\n\n* `refund` - Refund\n* `void` - Void\n* `capture` - Capture\n* `delete` - Delete\n* `cancel` - Cancel\n* `expire` - Expire"},"result":{"enum":["success","failed"],"type":"string","description":"Indicates the outcome of the operation. `success` denotes a successful operation.\n\n* `success` - Success\n* `failed` - Failed"}},"required":["detail","operation","result"]},"ExternalOperation":{"type":"object","properties":{"amount":{"type":"string","readOnly":true,"description":"The specific amount for which the operation was performed."},"session_id":{"type":"string","description":"The session ID of the parent transaction will be included in the webhook payload. This session ID is crucial for associating the webhook event with the original transaction, allowing for accurate tracking and processing.","readOnly":true},"order_no":{"type":"string","description":"The 'order_no' field indicates the unique order number of the parent transaction. This identifier is crucial for tracking and managing the related order within its entire lifecycle.","readOnly":true},"initiator":{"allOf":[{"$ref":"#/components/schemas/InitiatorUser"}],"description":"If the operation was performed using Basic Auth (and not an API Key), this field contains the details of the `initiator` who started the operation."},"is_sandbox":{"type":"boolean","title":"Is Sandbox?","description":"Indicates whether the operation was performed in a test environment or not."},"operation":{"enum":["capture","refund","void"],"type":"string","description":"Identifies the operation that was executed.","readOnly":true},"pg_code":{"type":"string","description":"Represents the `pg_code` of the Payment Gateway settings which was used to perform the operation."},"pg_response":{"type":"object","additionalProperties":{},"readOnly":true,"description":"Contains the raw response from the payment gateway (PG) for the operation (`pg_response`). It will always be a valid JSON."},"reference_number":{"type":"string","readOnly":true,"description":"A unique reference_number assigned by Ottu for the performed operation. It's also sent to the PG and can be used as a reconciliation parameter."},"source":{"enum":["input","pg"],"type":"string","description":"Can have one of two values - `input` or `pg`. If `input`, it means the operation was performed in an API call triggered by the merchant. If `pg`, it means the operation was done on the PG management dashboard, and the PG notified Ottu via webhook. The `pg` value will always be notified to the webhook, never in an API call.","readOnly":true},"success":{"type":"boolean","readOnly":true,"description":"Indicates whether the operation was successful or not (`success=True` or `success=False`)."},"result":{"enum":["success","failed"],"type":"string","description":"The result of the operation - whether it was successful or not.","readOnly":true},"signature":{"type":"string","readOnly":true,"description":"Signature Field: A cryptographic hash used to guarantee data integrity and authenticity during client-server exchanges. This hash ensures that the API payload has not been tampered with, and can only be verified by authorized parties."},"timestamp_utc":{"type":"string","format":"date-time","description":"Specifies the time when the operation was performed, in the UTC timezone."},"txn":{"allOf":[{"$ref":"#/components/schemas/ChildPayment"}],"readOnly":true,"description":"Every operation results in the creation of a payment transaction (`txn`), which is a child of the payment transaction against which the operation is performed. This child transaction holds all the details of the operation."},"pg_params":{"allOf":[{"$ref":"#/components/schemas/PGParams"}],"readOnly":true,"description":"The `pg_params` field contains the details received \nfrom the payment gateway callback these details are \nprovided to us by the gateway after a user has completed \na payment transaction additionally, `pg_params` \ncan include information obtained from an inquiry \nrequest made to the payment gateway status check API. \n"},"extra":{"description":"The extra information for the payment details, which the merchant has sent it in key value form."}},"required":["amount","operation","order_no","pg_params","pg_response","reference_number","result","session_id","signature","source","success","timestamp_utc","txn"]},"InitiatorUser":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"first_name":{"type":"string","maxLength":32},"last_name":{"type":"string","maxLength":32},"username":{"type":"string","description":"Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.","pattern":"^[\\w.@+-]+$","maxLength":150},"email":{"type":"string","format":"email","title":"Email address","maxLength":254},"phone":{"type":"string","title":"Phone number","maxLength":128}},"required":["email","id","username"]},"ChildPayment":{"type":"object","properties":{"amount":{"type":"string","readOnly":true},"currency_code":{"type":"string","description":"The specified currency represents the denomination of the transaction.Nevertheless, it doesn't necessarily mandate payment in this exact currency.Due to potential currency conversions or exchanges, the final charge may be in a different currency.","maxLength":3,"minLength":3},"order_no":{"type":["string","null"],"description":"The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.","maxLength":128},"session_id":{"type":"string","description":"A unique identifier for each payment transaction, used to maintain the session state during the payment process.","maxLength":128},"state":{"enum":["paid","refunded","refund_queued","refund_rejected","voided"],"type":"string","description":"The current state of the payment transaction, it helps to understand the progress of the payment.\n\n* `paid` - paid\n* `refunded` - refunded\n* `refund_queued` - refund_queued\n* `refund_rejected` - refund_rejected\n* `voided` - voided"}},"required":["amount","currency_code"]},"PGParams":{"type":"object","description":"Serializer for PaymentTransaction with dynamically generated fields.","properties":{"auth_code":{},"card_type":{},"card_holder":{},"cardholder_email":{},"card_expiry_month":{},"card_expiry_year":{},"full_card_expiry":{},"card_number":{},"card_issuer":{},"ref":{},"result":{},"track_id":{},"post_date":{},"transaction_id":{},"payment_id":{},"pg_message":{},"receipt_no":{},"transaction_no":{},"decision":{},"card_expiry":{},"card_details":{},"dcc_payer_amount":{},"dcc_payer_currency":{},"dcc_payer_exchange_rate":{},"rrn":{}}},"PaymentOperationErrors":{"oneOf":[{"$ref":"#/components/schemas/FieldErrors"},{"$ref":"#/components/schemas/OperationFailure"}]},"FieldErrors":{"type":"object","properties":{"field_name":{"type":"array","items":{"type":"string","default":"This field is required."}}}},"OperationFailure":{"type":"object","properties":{"detail":{"type":"string","description":"Provides a message associated with the operation, suitable for displaying to the end user."},"operation":{"enum":["delete","cancel","expire","refund","capture","void","operation_tracking"],"type":"string","description":"* `delete` - delete\n* `cancel` - cancel\n* `expire` - expire\n* `refund` - refund\n* `capture` - capture\n* `void` - void\n* `operation_tracking` - operation_tracking"},"result":{"enum":["failed"],"type":"string","description":"* `failed` - Failed"}},"required":["detail","operation","result"]},"GenericErrorMessage":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}},"paths":{"/b/pbl/v2/operation/":{"post":{"operationId":"public_operations","description":"The Payment Operations API provides an interface to manage your payment transactions beyond their initial creation. It allows for several operations including `refund`, `capture`, `void`, and others, directly syncing with the Payment Gateway (PG) for certain actions to ensure consistency across systems.\n\nTwo key identifiers, `order_no` and `session_id`, can be used interchangeably to specify the payment transaction that the operation should be applied to.\n\nFor operations such as `refund` and `capture`, you can optionally define the `amount` to be actioned. If not provided, the API will attempt to perform the operation on the full amount, or the remaining amount if previous operations were conducted. However, note that for `void`, the operation always applies to the full amount, ignoring the `amount` value if provided.\n\nThis API also allows you to perform certain operations solely at the Ottu system level, providing increased control over your payment transactions.\n\nFor every operation, the API provides a clear response containing information about the executed operation, a user-friendly message (`detail`), and the operation's result (`success` indicates a successful operation).\n\n","summary":"Operations","parameters":[{"in":"header","name":"Authorization","schema":{"type":"string","default":"Api-Key 1sxkXhZt.cz1mPFsYtnPG9nsXhCWuEty6RiaxCbZm"},"description":"Private API key to be provided in the format `Api-Key <key>`.","required":true},{"in":"header","name":"Tracking-Key","schema":{"type":"string","default":"Tracking-Key: your_operation_tracking_key"},"description":"The Tracking-Key is a unique identifier provided by the merchant for each operation request.\n\nIt is crucial for ensuring the distinctiveness of each operation.\n\nWhen initiating an operation, this key is stored alongside other transaction details in the database.\n\nIt serves as a reference for future status queries.\n\nEnabling the retrieval of the latest status information for a specific operation.\n\nEnsure that each `Tracking-Key` is distinct to prevent ambiguities in operation tracking and status updates.\n\n"}],"tags":["Payment Operations"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Operation"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Operation"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Operation"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOperationResponses"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOperationErrors"}}},"description":""},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""}}}}}}
```

{% hint style="warning" %}
[Operations](https://docs.ottu.com/developer/operations) are not working for foreign [currenies](https://docs.ottu.com/user-guide/currencies).&#x20;
{% endhint %}

## [FAQ](#faq)

#### :digit\_one: [**What happens if I try to perform an operation that is not supported by the Payment Gateway (PG)?**](#what-happens-if-i-try-to-perform-an-operation-that-is-not-supported-by-the-payment-gateway-pg)

If you attempt to perform an operation that is not supported by the PG, the operation will be rejected by Ottu with an error message. The list of supported operations for each PG can be found [here](https://docs.ottu.com/user-guide/payment-gateway#available-operations).

#### :digit\_two: [**Can I perform operations on a transaction that is already completed?**](#can-i-perform-operations-on-a-transaction-that-is-already-completed)

For certain operations like [refund](#refund-1), you can perform operations on transactions that have been successfully completed. However, operations like [cancel](#cancel-1) or [expire](#expire-1) can only be performed on transactions that are not yet completed.

#### :digit\_three: [**Can I partially refund or capture a transaction?**](#can-i-partially-refund-or-capture-a-transaction)

Yes, for operations like [refund](#refund-1) or [capture](#capture-1), you can specify the amount to be actioned. If not specified, Ottu will attempt to perform the operation on the full amount of the transaction.

#### :digit\_four: [**What does 'soft delete' and 'hard delete' mean?**](#what-does-soft-delete-and-hard-delete-mean)

**Soft delete** is used for transactions that are `paid`, `authorized`, or `cod`/`cash`. These transactions are removed from reports and dashboard listings, but they're still available in the **deleted transactions** section and can be restored anytime. \
**Hard delete** is used for non-success transactions, which are permanently removed from the system

#### :digit\_five: [**What does a 'child transaction' mean?**](#what-does-a-child-transaction-mean)

A [child transaction](https://docs.ottu.com/user-guide/payment-tracking/payment-transactions-states#child-payment-transaction) is a sub-transaction created when operations like [refund](#refund-1) or [capture](#capture-1) are performed. This child transaction holds the details of the operation, including the new state, the [amount](https://docs.ottu.com/user-guide/payment-tracking#amount-definitions-and-calculation-mechanism), and the [payment gateway](https://docs.ottu.com/user-guide/payment-gateway)'s response.&#x20;

#### :digit\_six: [**How do I know which operations a payment gateway supports?**](#how-do-i-know-which-operations-a-payment-gateway-supports)

Ottu maintains a list of the operations supported by each payment gateway, which can be found [here](https://docs.ottu.com/user-guide/payment-gateway#available-operations).

#### :digit\_seven: [**What is the difference between using API-Key authentication and Basic Authentication?**](#what-is-the-difference-between-using-api-key-authentication-and-basic-authentication)

Using an [API-Key](https://docs.ottu.com/authentication#private-key-api-key) grants you superadmin privileges and allows you to perform any operation. However, with [Basic Authentication](https://docs.ottu.com/authentication#authentication), you can assign specific [permissions ](#permissions)to control access to various API endpoints. It's recommended to use Basic Authentication for granular access control.

#### :digit\_eight: [**What permissions are required to perform operations?**](#what-permissions-are-required-to-perform-operations)

The required permissions depend on the operation you want to perform. You can grant permissions for specific operations like 'payment.capture' for[ capture](#capture-1), 'payment.expire' for [expire](#expire-1), and so on. See the list of permission codes for each operation [here](#permission-codes-for-each-operation).

#### :digit\_nine: [**What happens when a refund operation is requested via the API?**](#what-happens-when-a-refund-operation-is-requested-via-the-api)

When a [refund](#refund-1) operation is requested via the API, the request goes directly to the payment gateway and the maker-checker flow is not activated. Currently, the maker-checker flow can only be enabled for operations performed manually via the Ottu dashboard. This ensures that refunds are issued directly when requested via the API, bypassing the internal approval process.

As we conclude this guide, we hope that the provided information has given you a comprehensive understanding of the operations endpoint and its various functionalities. We've covered everything from initial setup to the various types of operations and how they interact with different transaction states. However, in case you need to delve deeper into the technical implementation, feel free to explore the [Operation API Schema Reference](#operations-api-schema-reference). Remember, each operation has specific requirements and behaviors, so it's important to carefully review this documentation before proceeding. As always, we're here to help should you need any further assistance or clarification. Happy integrating with Ottu!