openapi: 3.0.0
info:
  title: Remit Core API
  version: 1.0.4
  description: >
    > **Remit Core** Partners should be aware that **new fields and/or values**
    may appear

    > in requests and responses over time.

    > Any unrecognised fields and/or values **must be ignored** if they are not
    relevant to the Partner.


    ---


    ## Overview


    **Remit Core** is a platform for processing cross-border money transfers.


    Partners integrate with Remit Core via API and initiate transfers.

    Remit Core handles all operational complexity: routing, validation, status
    tracking,

    and interaction with payment infrastructure. Partners do not need to deal
    with the specifics

    of national payment systems or differences in protocols.


    **For the Partner, Remit Core is the single integration point.** All
    interaction takes place

    through the API described in this document.


    ---


    ## Transfer Types


    Remit Core supports two transfer types:


    ### CREDIT Transfer *(primary scenario)*


    The Partner debits funds from the sender on their side;

    Remit Core credits funds to the recipient.


    ```

    Partner (debit) → Remit Core → Recipient (credit via Remit Core)

    ```


    For this transfer type, the key parameters are: the settlement currency with
    the Partner

    (debit currency - `senderCurrencyCode`) and the recipient's credit currency
    (`receiverCurrencyCode`).


    ### DEBIT Transfer *(limited scenario)*


    Remit Core debits funds from the sender;

    the Partner credits funds to the recipient on their side.


    ```

    Sender (debit via Remit Core) → Remit Core → Partner (credit)

    ```


    For this transfer type, the key parameters are: the sender's debit currency
    (`senderCurrencyCode`) and

    the settlement currency with the Partner (credit currency -
    `receiverCurrencyCode`).


    DEBIT transfers are used on a limited basis and require additional
    agreement.


    ---


    ## Payment Instruments


    A payment instrument is the details by which Remit Core identifies

    the sender (for debit) or the recipient (for credit).


    | Operation | Available instruments |

    |---|---|

    | Credit to recipient (CREDIT) | Card number; phone number + short bank code
    |

    | Debit from sender (DEBIT) | Card number |


    ---


    ## Authentication and Headers


    ### Required Header (all methods)


    | Header | Description |

    |---|---|

    | `X-Api-Key` | Partner key in UUID format. Issued upon onboarding to the
    platform. |


    ---


    ## Onboarding and Testing


    ### Network Connection (production environment)


    The **IPSec** protocol is used for connections in the production
    environment.


    Before integration:

    1. Complete the <a href='/remitcore/Sunnybox-IPsec.docx'>IPSec configuration
    form</a>.

    2. Provide your account manager with the IP addresses from which requests
    will be sent to Remit Core.


    The test environment is accessible directly from the Internet.


    ### Test Environment


    - **Base URL:** `https://remit-core.ipt-merch.com`

    - **Postman Collection for CREDIT transfers:** <a
    href='/remitcore/remitcore_postman_collection_credit.json'
    target='_blank'>download</a>

    - **Credentials** (`X-Api-Key` for the test environment): request from your
    account manager.


    ---


    ## Interaction Flow


    ### Optional Step: Currency Conversion - `POST /convert`


    Preliminary amount calculation and current exchange rate retrieval.


    - This method **does not create a transfer** - it is an informational
    request only.

    - Can be used by the Partner to display preliminary transfer terms to the
    end client.

    - **Not a required step** before `POST /register`.


    <a href='/img/remitcore/en_remitcore_convert.png' target='_blank'>
      <img src='/img/remitcore/en_remitcore_convert.png'/>
    </a>


    ---


    ### Optional Step: Get Available Recipient Banks - `POST /info/v1/get_banks`


    Returns a list of banks (short bank codes) where an active card was found
    for the specified recipient phone number.


    This method is needed **only when crediting by phone number** (payment
    instrument `PHONE`):

    in this case, a short bank code (`bankLabel`) must be provided alongside the
    phone number.

    The method allows the Partner to determine in advance which banks have an
    active card

    for the recipient, and to offer the client a choice.


    The list of bank names corresponding to short bank codes: <a
    href='/remitcore/en_bank_label_list_for_transfers.xlsx'
    target='_blank'>download</a>.


    - This method **does not create a transfer** - it is an auxiliary
    informational request.

    - **Not a required step**: if the Partner obtains the bank code by other
    means
      (e.g. the client selects the bank themselves), this method may be skipped.
    - Currently, only **Uzbekistan** (`UZB`) is supported as the recipient's
    country.


    **Typical use-case:**


    1. The client enters the recipient's phone number

    2. The Partner calls `POST /info/v1/get_banks` → receives the list of banks
    with active cards

    3. The client selects the necessary bank from the list

    4. The Partner sends `phoneNumber` + `bankLabel` in the `target` field when
    calling `POST /register`


    ---


    ### Main Transfer Flow


    #### CREDIT Transfer


    ```

    POST /register → POST /process

    ```


    A CREDIT transfer requires just two steps. Once `POST /process` completes
    successfully,

    Remit Core automatically credits the funds to the recipient.


    | Step | Method | Required | Description |

    |---|---|---|---|

    | 1 | `POST /register` | Required | Transfer registration: data validation
    and transfer entity creation |

    | 2 | `POST /process` | Required | Initiates transfer processing |


    ---


    #### DEBIT Transfer


    ```

    POST /register → POST /process → [POST /resend_otp] → [POST /confirm] →
    [POST /cancel]

    ```


    A DEBIT transfer may include additional confirmation steps:

    Remit Core initiates the debit from the sender, which may require
    confirmation via OTP or 3DS.


    | Step | Method | Required | Description |

    |---|---|---|---|

    | 1 | `POST /register` | Required | Transfer registration: data validation
    and transfer entity creation |

    | 2 | `POST /process` | Required | Initiates transfer processing |

    | 3 | `POST /resend_otp` | If needed | Resends OTP to the client if not
    received or not entered in time |

    | 4 | `POST /confirm` | If needed | Transfer confirmation via OTP or 3DS (if
    required for the operation) |

    | 5 | `POST /cancel` | If needed | Transfer cancellation |


    ---


    #### Common for Both Transfer Types


    The current transfer status can be requested at any time via `POST
    /get_status`.


    Remit Core also sends a **callback** with the final transfer result

    to the URL agreed upon during onboarding.


    #### Asynchronous Result (code 2000)


    In some cases, Remit Core cannot return the final result synchronously.

    In such cases, the method will return code **2000** ("Request accepted. Wait
    for operation processing information in Callback or request status").


    When this occurs, the Partner must either:

    - wait for the **callback** from Remit Core, **or**

    - poll the transfer status via `POST /get_status`.


    <a href='/img/remitcore/en_remitcore_transfer.png' target='_blank'>
      <img src='/img/remitcore/en_remitcore_transfer.png'/>
    </a>


    ---


    ## Transfer Status Model


    ### CREDIT Transfer


    <a href='/img/remitcore/remitcore_state_model_credit.png' target='_blank'>
      <img src='/img/remitcore/remitcore_state_model_credit.png'
           style="display: block; margin: 0 auto; max-width:70%; height: auto;"/>
    </a>


    | Status | Description |

    |---|---|

    | `INIT` | Transfer initiated - `POST /register` request received |

    | `REGISTERED` | Transfer successfully registered |

    | `PROCESSING` | Transfer is being processed - `POST /process` request
    received |

    | `SUCCESS` | Transfer successfully completed |

    | `FAILED` | Transfer rejected |

    | `CANCELLED` | Transfer cancelled (no further requests received to continue
    processing) |


    ---


    ### DEBIT Transfer


    <a href='/img/remitcore/remitcore_state_model_debit.png' target='_blank'>
      <img src='/img/remitcore/remitcore_state_model_debit.png'
           style="display: block; margin: 0 auto; max-width:70%; height: auto;"/>
    </a>


    | Status | Description |

    |---|---|

    | `INIT` | Transfer initiated - `POST /register` request received |

    | `REGISTERED` | Transfer successfully registered |

    | `PROCESSING` | Transfer is being processed - `POST /process` request
    received |

    | `CONFIRMATION` | Client confirmation required (OTP or 3DS) |

    | `CONFIRMING` | Confirmation in progress - `POST /confirm` request received
    |

    | `SUCCESS` | Transfer successfully completed |

    | `FAILED` | Transfer rejected |

    | `CANCELLING` | Cancellation in progress - `POST /cancel` request received
    |

    | `CANCELLING_FAILED` | Cancellation failed |

    | `CANCELLED` | Transfer cancelled (no further requests received to continue
    processing, or transfer is successfully cancelled after `POST /cancel`
    request) |


    ---


    ## Settlement Report


    Remit Core automatically generates a **daily settlement report** and sends
    it

    to the list of email addresses provided by the Partner in advance.


    ### File Format


    - Format: **CSV**

    - Delimiter: **`;`**

    - First row: field names

    - File name: `Remit_Core_transfers_YYYYMMDD.csv`, where `YYYYMMDD` is the
    export date


    ### Settlement Report Fields


    | Field | Description |

    |---|---|

    | `transfer_id` | Transfer identifier in Remit Core |

    | `transfer_created_at` | Transfer creation date and time |

    | `transfer_sender_amount` | Transfer amount in the sender's currency (minor
    units, excluding fee) |

    | `sender_currency` | Sender's currency (ISO 4217 alpha-3) |

    | `transfer_receiver_amount` | Transfer amount in the recipient's currency
    (minor units, excluding fee) |

    | `receiver_currency` | Recipient's currency (ISO 4217 alpha-3) |

    | `route_name` | Transfer direction |

    | `transfer_fee_amount` | Fee amount in the fee currency (minor units). May
    be negative (Partner reward) |

    | `fee_currency` | Fee currency (ISO 4217 alpha-3) |

    | `transaction_type` | Transfer type: CREDIT, DEBIT |

    | `transfer_exchange_rate` | Exchange rate fixed for the transfer (Sender's
    currency -> Recipient's currency) |

    | `payment_system` | Recipient's payment system for СREDIT transfer /
    Sender's payment system for DEBIT transfer (if applicable for payment
    instrument) |


    ### How the Partner is Reflected in the Settlement Report


    - For a **CREDIT transfer**, the Partner acts as the **sender**:
      `Sender_Currency` = `Fee_Currency` = settlement currency with the Partner.
    - For a **DEBIT transfer**, the Partner acts as the **recipient**:
      `Receiver_Currency` = `Fee_Currency` = settlement currency with the Partner.

    ---


    ## Country-Specific Transfer Details


    ### Uzbekistan


    <details>

    <summary><strong>Transfer Limits</strong></summary>


    Limits apply to cards issued in Uzbekistan.


    **By amount:**

    - Minimum transfer amount - 1 UZS

    - Single transaction limit - 18 749 999 UZS

    - Cumulative limit over the last 30 days - 9 999 USD


    **By number of transfers:**

    - Per day — maximum 5 transfers

    - Per month — maximum 150 transfers


    </details>


    <details>

    <summary><strong>Supported Card BINs</strong></summary>


    | Payment System | BINs |

    |---|---|

    | **UZCARD** | 5440, 5614, 6262, 6263, 6264, 8600 |

    | **HUMO** | 4008, 4027, 4062, 4067, 4073, 4097, 4198, 4294, 4728, 4790,
    5555, 9860 |

    | **Visa** | 49169903 |


    </details>
servers:
  - url: https://remit-core.ipt-merch.com
    description: Test environment
x-tagGroups:
  - name: API
    tags:
      - Transfer process
      - Information retrieval
tags:
  - name: Transfer process
    description: Methods used in the transfer process
  - name: Information retrieval
    description: Auxiliary Information Methods
paths:
  /v1/register:
    post:
      tags:
        - Transfer process
      summary: Transfer registration
      description: >
        Validates the request and registers a new transfer (creates a transfer
        entity).


        This is the **first required step** in the transfer flow. Upon
        successful registration,

        a `transferId` is returned - it must be used in all subsequent requests
        for this transfer.


        Applicable to both **CREDIT** and **DEBIT** transfer types.
      operationId: registerTransfer
      security:
        - XApiKeyAuth: []
      requestBody:
        description: >-
          Transfer registration parameters. Use `CreditTransferRequest` for
          CREDIT transfers and `DebitTransferRequest` for DEBIT transfers
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CreditTransferRequest'
                - $ref: '#/components/schemas/DebitTransferRequest'
      responses:
        '200':
          description: >
            Successful response or business logic error.

            Check the `code` field to determine the outcome - code `0` indicates
            success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterTransferResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request validation error - invalid JSON, missing required fields, or
            constraint violations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/process:
    post:
      tags:
        - Transfer process
      summary: Initiate transfer processing
      description: >
        Initiates processing of a previously registered transfer.


        This is the **second required step** in the transfer flow, called after
        `POST /register`.

        The transfer must be in the status `REGISTERED` - only in that state it
        can be processed.


        Applicable to both **CREDIT** and **DEBIT** transfer types.


        Key response scenarios (excluding errors):

        - **code 0** - transfer processed successfully (**CREDIT** transfers)

        - **code 2000** - request accepted asynchronously; wait for a callback
        or poll `POST /get_status` (both **CREDIT** and **DEBIT** transfers)

        - **code 2001** - confirmation required (**DEBIT** transfers): 
           - for `confirmationType = OTP` submit the code via `POST /confirm`,
           - for `confirmationType = 3DS` confirmation is completed outside of Remit Core.
      operationId: processTransfer
      security:
        - XApiKeyAuth: []
      requestBody:
        description: Identifier of the transfer to process
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferIdRequest'
      responses:
        '200':
          description: >
            Successful response, business logic error, or notification about
            required additional actions.

            Check the `code` field to determine the outcome
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ProcessTransferResponse'
                  - $ref: >-
                      #/components/schemas/NeedConfirmationProcessTransferResponse
                  - $ref: '#/components/schemas/ProcessPendingTransferResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request validation error - invalid JSON, missing required fields, or
            constraint violations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      callbacks:
        TransferResultInfo:
          $ref: '#/components/callbacks/TransferResultInfo'
  /v1/get_status:
    post:
      tags:
        - Transfer process
      summary: Get transfer status
      description: >
        Returns the current status of a transfer.


        Can be called at any point in the transfer lifecycle. Particularly
        useful when

        `POST /process`, `POST /confirm` or `POST /cancel` returned **code
        2000** (asynchronous processing)

        and no callback has been received yet.


        The transfer can be identified by either `transferId` (Remit Core
        identifier)

        or `externalTransferId` (Partner's own identifier). At least one must be
        provided.


        Applicable to both **CREDIT** and **DEBIT** transfer types.
      operationId: getStatus
      security:
        - XApiKeyAuth: []
      requestBody:
        description: >-
          Transfer identifier - either `transferId` or `externalTransferId` must
          be provided
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusTransferRequest'
      responses:
        '200':
          description: >
            Successful response or business logic error.

            Check the `code` field to determine the outcome - code `0` indicates
            success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusTransferResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request validation error - invalid JSON, missing required fields, or
            constraint violations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/confirm:
    post:
      tags:
        - Transfer process
      summary: Confirm transfer
      description: >
        Confirms a transfer using a one-time password (OTP).


        The transfer must be in the status `CONFIRMATION` - only in that state
        it can be confirmed.


        Must be called when `POST /process` returns **code 2001** with
        `confirmationType = OTP`.

        The client receives the OTP via the channel configured for their card
        (e.g. SMS),

        and the Partner submits it using this method.


        Applicable to **DEBIT** transfers only.


        Key response scenarios (excluding errors):

        - **code 0** - transfer confirmed successfully 

        - **code 2000** - request accepted asynchronously; wait for a callback
        or poll `POST /get_status`

        - **code 3008** - OTP incorrect; need to resend code - use `POST
        /resend_otp` for the new one
      operationId: confirm
      security:
        - XApiKeyAuth: []
      requestBody:
        description: Transfer identifier and one-time password provided by the client
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmTransferRequest'
      responses:
        '200':
          description: >
            Successful response, business logic error, or notification about
            required additional actions.

            Check the `code` field to determine the outcome
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ConfirmTransferResponse'
                  - $ref: '#/components/schemas/ConfirmPendingTransferResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request validation error - invalid JSON, missing required fields, or
            constraint violations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      callbacks:
        TransferResultInfo:
          $ref: '#/components/callbacks/TransferResultInfo'
  /v1/resend_otp:
    post:
      tags:
        - Transfer process
      summary: Resend OTP for transfer confirmation
      description: >
        Requests a new one-time password (OTP) to be sent to the client.


        Use this method when `POST /process` returned **code 2001** with
        `confirmationType = OTP`

        and the client did not receive the OTP or the previous OTP has expired. 

        Or after an unsuccessful attempt of confirmation via `POST /confirm` (if
        received **code 3008**).


        The transfer must be in the status `CONFIRMATION`.


        Applicable to **DEBIT** transfers only.
      operationId: resendOtp
      security:
        - XApiKeyAuth: []
      requestBody:
        description: Identifier of the transfer for which to resend the OTP
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferIdRequest'
      responses:
        '200':
          description: >
            Successful response or business logic error.

            Check the `code` field to determine the outcome - code `0` indicates
            success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResendOtpResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request validation error - invalid JSON, missing required fields, or
            constraint violations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/cancel:
    post:
      tags:
        - Transfer process
      summary: Cancel transfer
      description: >
        Requests cancellation of a transfer that has been successfully processed
        (transfer must be in the status `SUCCESS`).


        The result may be synchronous or asynchronous (code `2000` - wait for a
        callback or poll `POST /get_status`).


        Applicable to **DEBIT** transfers only. Cancellation of CREDIT transfers
        is prohibited (code `8003`).
      operationId: cancel
      security:
        - XApiKeyAuth: []
      requestBody:
        description: Identifier of the transfer to cancel
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferIdRequest'
      responses:
        '200':
          description: |
            Successful response or business logic error.
            Check the `code` field to determine the outcome
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CancelTransferResponse'
                  - $ref: '#/components/schemas/CancelPendingTransferResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request validation error - invalid JSON, missing required fields, or
            constraint violations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      callbacks:
        TransferResultInfo:
          $ref: '#/components/callbacks/TransferResultInfo'
  /v1/convert:
    post:
      tags:
        - Information retrieval
      summary: Convert amount and get exchange rate
      description: >
        Returns the current exchange rate and calculates the transfer amount in
        the target currency.


        This method is **optional** and **informational** - it does not create a
        transfer

        and is not a required step before `POST /register`.

        It can be used to display preliminary transfer terms to the end client.


        Exactly one of the following fields must be provided:

        - `senderAmount` - to calculate the amount the recipient will receive

        - `receiverAmount` - to calculate the amount the sender needs to send
      operationId: convert
      security:
        - XApiKeyAuth: []
      requestBody:
        description: >-
          Currency pair and amount for conversion. Provide either `senderAmount`
          or `receiverAmount`, not both
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertRequest'
      responses:
        '200':
          description: >
            Successful response or business logic error.

            Check the `code` field to determine the outcome - code `0` indicates
            success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request validation error - invalid JSON, missing required fields, or
            constraint violations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /info/v1/get_banks:
    post:
      tags:
        - Information retrieval
      summary: Get available recipient banks
      description: >
        Returns a list of banks (short bank codes) where an active card was
        found for the specified recipient phone number.


        This method is **optional** and **informational** - it does not create a
        transfer.


        Use this method when crediting by phone number (payment instrument
        `PHONE`):

        in this case, `phoneNumber` and `bankLabel` must both be provided in the
        `target` field

        of the `POST /register` request. This method helps determine which banks
        have an active card

        for the recipient, so the end client can choose the correct bank.


        Currently supported recipient country: **Uzbekistan** (`UZB`) only.
      operationId: getBanks
      security:
        - XApiKeyAuth: []
      requestBody:
        description: Recipient phone number and country code
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetBanksRequest'
      responses:
        '200':
          description: >
            Successful response or business logic error.

            Check the `code` field to determine the outcome - code `0` indicates
            success.

            The `banks` array may be empty if no active cards were found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBanksResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request validation error - invalid JSON, missing required fields, or
            constraint violations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /info/v1/get_balance:
    post:
      tags:
        - Information retrieval
      summary: Get partner account balance
      description: >
        Returns the current balance of the partner's account as reflected in the
        core banking system (ABS) at the moment of the request.


        This method is **informational** - it does not create a transfer.


        The partner is identified by the `X-Api-Key` header, so no request
        parameters are required.

        The request body must be an empty JSON object `{}`.


        **Important:** depending on the ABS operational day cycle, some
        transactions of the current day

        may not yet be reflected in the returned balance. The finalised daily
        balance is available

        only after the ABS end-of-day processing completes.
      operationId: getBalance
      security:
        - XApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Empty JSON object
              example: {}
      responses:
        '200':
          description: >
            Successful response or business logic error.

            Check the `code` field to determine the outcome - code `0` indicates
            success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBalanceResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request validation error - invalid JSON, missing required fields, or
            constraint violations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ConvertRequest:
      type: object
      required:
        - senderCurrencyCode
        - senderCountry
        - receiverCurrencyCode
        - receiverCountry
      properties:
        senderAmount:
          type: integer
          format: int64
          description: >
            Transfer amount in minor units of sender's currency. Must be greater
            than zero.

            Provide this field to calculate `receiverAmount`.

            Must not be specified if `receiverAmount` is provided
          example: 100000
        senderCurrencyCode:
          type: string
          description: Sender's currency code according to ISO 4217 alpha-3
          pattern: ^[A-Z]{3}$
          example: UZS
        senderCountry:
          description: Sender's country code according to ISO 3166-1 alpha-3
          type: string
          pattern: ^[A-Z]{3}$
          example: UZB
        receiverCurrencyCode:
          type: string
          description: Recipient's currency code according to ISO 4217 alpha-3
          pattern: ^[A-Z]{3}$
          example: RUB
        receiverCountry:
          description: Recipient's country code according to ISO 3166-1 alpha-3
          type: string
          pattern: ^[A-Z]{3}$
          example: RUS
        receiverAmount:
          type: integer
          format: int64
          description: >
            Amount to be received by the recipient in minor units of recipient's
            currency. Must be greater than zero.

            Provide this field to calculate `senderAmount`.

            Must not be specified if `senderAmount` is provided
          example: 13900000
    ConvertResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `0` - Request completed successfully
              * `8002` - Access restriction by partner/direction/country/currency
              * `9100` - External service interaction error
          type: integer
          example: 0
        message:
          description: Response status message
          type: string
          example: Request completed successfully
        result:
          description: Conversion result. Present when `code = 0`
          allOf:
            - $ref: '#/components/schemas/ConvertResult'
    ConvertResult:
      type: object
      required:
        - senderAmount
        - senderCurrencyCode
        - senderCountry
        - receiverCurrencyCode
        - receiverCountry
        - exchangeRate
        - receiverAmount
      properties:
        exchangeRate:
          type: string
          description: >-
            Exchange rate from sender's currency to recipient's currency (with
            exactly 4 decimal places)
          example: '140.0000'
        senderAmount:
          type: integer
          format: int64
          description: Transfer amount in minor units of sender's currency
          example: 100000
        senderCurrencyCode:
          type: string
          description: Sender's currency code according to ISO 4217 alpha-3
          pattern: ^[A-Z]{3}$
          example: UZS
        senderCountry:
          description: Sender's country code according to ISO 3166-1 alpha-3
          type: string
          pattern: ^[A-Z]{3}$
          example: UZB
        receiverCurrencyCode:
          type: string
          description: Recipient's currency code according to ISO 4217 alpha-3
          pattern: ^[A-Z]{3}$
          example: RUB
        receiverCountry:
          description: Recipient's country code according to ISO 3166-1 alpha-3
          type: string
          pattern: ^[A-Z]{3}$
          example: RUS
        receiverAmount:
          type: integer
          format: int64
          description: >-
            Amount to be received by recipient in minor units of recipient's
            currency
          example: 13900000
        fee:
          type: integer
          format: int64
          description: Fee amount in minor units of sender's currency
          example: 1000
    StatusTransferRequest:
      type: object
      description: At least one of `transferId` or `externalTransferId` must be provided
      properties:
        transferId:
          description: >
            Transfer identifier in Remit Core, received in the response to `POST
            /register`.

            Required if `externalTransferId` is not specified
          type: string
          example: 01990610-f6fb-72fd-84c1-ff8cf5840599
        externalTransferId:
          description: |
            Transfer identifier in the Partner's system.
            Required if `transferId` is not specified
          type: string
    TransferRequest:
      type: object
      required:
        - transferType
        - externalTransferId
        - clientId
        - transferData
        - target
      properties:
        transferType:
          description: |
            Transfer type. Possible values:
              * `CREDIT` - Partner debits the sender; Remit Core credits the recipient
              * `DEBIT` - Remit Core debits the sender; Partner credits the recipient
          type: string
          enum:
            - CREDIT
            - DEBIT
          example: CREDIT
        externalTransferId:
          description: >-
            Unique transfer identifier in the Partner's system. Used for
            idempotency
          type: string
          example: partner-tx-00123
        clientId:
          description: |
            Unique identifier of the sender on the partner's side.

            Acceptable values include:
              - the sender's phone number;
              - an internal client ID in the partner's system;
              - the sender's email address;
              - any other unique identifying attribute.

            Important: the clientId value must uniquely correspond to a single
            individual sender of the transfer. Using the same clientId for
            different individuals is not allowed
          type: string
          example: client-7890
        transferData:
          $ref: '#/components/schemas/TransferData'
        target:
          type: object
        source:
          type: object
        sender:
          $ref: '#/components/schemas/PersonData'
        receiver:
          $ref: '#/components/schemas/PersonData'
    CreditTransferRequest:
      description: >
        Request body for **CREDIT** transfer registration.

        The Partner debits the sender independently; Remit Core credits the
        recipient.
      allOf:
        - $ref: '#/components/schemas/TransferRequest'
        - type: object
          required:
            - sender
          properties:
            source:
              $ref: '#/components/schemas/CreditSourceInstrument'
            target:
              $ref: '#/components/schemas/CreditTargetInstrument'
            sender:
              allOf:
                - $ref: '#/components/schemas/PersonData'
                - type: object
                  required:
                    - firstName
                    - lastName
    DebitTransferRequest:
      description: >
        Request body for **DEBIT** transfer registration.

        Remit Core debits the sender; the Partner credits the recipient
        independently.
      allOf:
        - $ref: '#/components/schemas/TransferRequest'
        - type: object
          required:
            - sender
            - receiver
            - source
          properties:
            source:
              $ref: '#/components/schemas/DebitSourceInstrument'
            target:
              $ref: '#/components/schemas/DebitTargetInstrument'
            sender:
              allOf:
                - $ref: '#/components/schemas/PersonData'
                - type: object
                  required:
                    - firstName
                    - lastName
                    - birthday
                    - birthPlace
                    - identityDocument
                  properties:
                    identityDocument:
                      allOf:
                        - $ref: '#/components/schemas/IdentityDocument'
                        - type: object
                          required:
                            - documentType
                            - documentCountry
                            - number
                            - issuedDate
                            - issuedBy
                    extraFields:
                      $ref: '#/components/schemas/SenderPersonDataExtraFields'
            receiver:
              allOf:
                - $ref: '#/components/schemas/PersonData'
                - type: object
                  required:
                    - firstName
                    - lastName
                  properties:
                    extraFields:
                      type: object
                      description: Additional recipient data (if required)
    TransferData:
      type: object
      description: |
        Financial parameters of the transfer.

        Exactly one of the following must be provided:
        - `senderAmount` - if the sender wants to send a fixed amount
        - `receiverAmount` - if the recipient must receive a fixed amount
      required:
        - senderCurrencyCode
        - senderCountry
        - receiverCountry
        - receiverCurrencyCode
      properties:
        senderAmount:
          type: integer
          format: int64
          description: >
            Transfer amount in minor units of sender's currency. Must be greater
            than zero.

            Required if `receiverAmount` is not specified
          example: 100000
        senderCurrencyCode:
          type: string
          description: Sender's currency code according to ISO 4217 alpha-3
          pattern: ^[A-Z]{3}$
          example: UZS
        senderCountry:
          description: Sender's country code according to ISO 3166-1 alpha-3
          type: string
          pattern: ^[A-Z]{3}$
          example: UZB
        receiverCountry:
          description: Recipient's country code according to ISO 3166-1 alpha-3
          type: string
          pattern: ^[A-Z]{3}$
          example: RUS
        receiverAmount:
          type: integer
          format: int64
          description: >
            Amount to be received by the recipient in minor units of recipient's
            currency. Must be greater than zero.

            Required if `senderAmount` is not specified
          example: 13900000
        receiverCurrencyCode:
          type: string
          description: Recipient's currency code according to ISO 4217 alpha-3
          pattern: ^[A-Z]{3}$
          example: RUB
        reason:
          type: string
          description: Transfer purpose/reason
          example: Business payment
    PI.Phone:
      type: object
      description: >
        Payment instrument - recipient's phone number with bank label.

        Used in `target` for **CREDIT** transfers when crediting by phone
        number.

        To obtain the list of available `bankLabel` values for a phone number,
        use `POST /info/v1/get_banks`
      required:
        - paymentInstrumentType
        - phoneNumber
        - bankLabel
      properties:
        paymentInstrumentType:
          description: Payment instrument type identifier. Must be `PHONE`
          type: string
          enum:
            - PHONE
          example: PHONE
        phoneNumber:
          type: string
          description: Phone number (E.164 format)
          pattern: ^\+[1-9]\d{1,14}$
          example: '+998901234567'
        bankLabel:
          type: string
          minLength: 3
          maxLength: 3
          description: Short bank code (3 characters) identifying the recipient's bank
          example: KPT
    PI.MaskedCard:
      type: object
      description: >
        Payment instrument - masked card number.

        Used in `source` for **CREDIT** transfers or `target` for **DEBIT**
        transfers
      required:
        - paymentInstrumentType
        - maskedPan
      properties:
        paymentInstrumentType:
          description: Payment instrument type identifier. Must be `MASKED_CARD`
          type: string
          enum:
            - MASKED_CARD
          example: MASKED_CARD
        maskedPan:
          description: Masked card number with asterisks replacing the middle digits
          type: string
          example: 400078******7810
    PI.Account:
      type: object
      description: >
        Payment instrument - bank account number.

        Used in `source` for **CREDIT** transfers or `target` for **DEBIT**
        transfers
      required:
        - paymentInstrumentType
        - accountNumber
      properties:
        paymentInstrumentType:
          description: Payment instrument type identifier. Must be `ACCOUNT`
          type: string
          enum:
            - ACCOUNT
          example: ACCOUNT
        accountNumber:
          description: Bank account number (digits only)
          type: string
          pattern: ^\d*$
          example: '40817810099910004312'
    PI.CardPan:
      type: object
      description: |
        Payment instrument - full card number (PAN).
        Used in `target` for **CREDIT** transfers when crediting by card number
      required:
        - paymentInstrumentType
        - cardPan
      properties:
        paymentInstrumentType:
          description: Payment instrument type identifier. Must be `CARD_PAN`
          type: string
          enum:
            - CARD_PAN
          example: CARD_PAN
        cardPan:
          description: Full card number (16–19 digits)
          type: string
          minLength: 16
          maxLength: 19
          pattern: ^\d{16,19}$
          example: '40817810099910004312'
    PI.Card:
      type: object
      description: |
        Payment instrument - full card details for debit authorization.
        Used in `source` for **DEBIT** transfers
      required:
        - paymentInstrumentType
        - pan
        - expiryDate
        - phoneNumber
      properties:
        paymentInstrumentType:
          description: Payment instrument type identifier. Must be `CARD`
          type: string
          enum:
            - CARD
          example: CARD
        pan:
          description: Card number (16–19 digits)
          type: string
          minLength: 16
          maxLength: 19
          pattern: ^\d{16,19}$
          example: '4000789077777810'
        expiryDate:
          description: Card expiry date in `MMYY` format
          type: string
          minLength: 4
          maxLength: 4
          pattern: ^\d{4}$
          example: '0530'
        securityCode:
          description: Card security code (CVC/CVV), 3–4 digits
          type: string
          minLength: 3
          maxLength: 4
          pattern: ^\d{3,4}$
          example: '433'
        phoneNumber:
          description: Phone number linked to the card (E.164 format)
          type: string
          pattern: ^\+[1-9]\d{1,14}$
          example: '+998948063815'
    CreditSourceInstrument:
      description: >
        Payment instrument identifying the **sender's** account for a CREDIT
        transfer.

        The Partner uses this to indicate the source account on their side.


        Optional. If provided, all fields of the selected instrument are
        required
      oneOf:
        - $ref: '#/components/schemas/PI.Account'
        - $ref: '#/components/schemas/PI.MaskedCard'
    CreditTargetInstrument:
      description: |
        Payment instrument identifying the **recipient** for a CREDIT transfer.
        Remit Core uses this to credit funds to the recipient
      oneOf:
        - $ref: '#/components/schemas/PI.CardPan'
        - $ref: '#/components/schemas/PI.Phone'
    DebitSourceInstrument:
      description: |
        Payment instrument identifying the **sender** for a DEBIT transfer.
        Remit Core uses this to debit funds from the sender
      oneOf:
        - $ref: '#/components/schemas/PI.Card'
    DebitTargetInstrument:
      description: >
        Payment instrument identifying the **recipient's** account for a DEBIT
        transfer.

        The Partner uses this to indicate the destination account on their side
      oneOf:
        - $ref: '#/components/schemas/PI.Account'
        - $ref: '#/components/schemas/PI.MaskedCard'
    PersonData:
      type: object
      properties:
        firstName:
          description: First name (ASCII Latin characters only)
          type: string
          minLength: 1
          example: IVAN
        middleName:
          description: Middle name/Second name (ASCII Latin characters only)
          type: string
          minLength: 2
          example: IVANOVICH
        lastName:
          description: Last name (ASCII Latin characters only)
          type: string
          minLength: 2
          example: IVANOV
        nationality:
          description: Nationality code according to ISO 3166-1 numeric (3 digits)
          type: string
          minLength: 3
          maxLength: 3
          example: '860'
        birthday:
          description: Date of birth in `YYYY-MM-DD` format
          type: string
          format: date
          example: '1995-11-17'
        birthPlace:
          description: Place of birth
          type: string
          example: Tashkent
        address:
          description: Residential address
          type: string
          minLength: 2
          example: Republic of Uzbekistan, Tashkent, Fidokor str., 30, room 18
        identityDocument:
          $ref: '#/components/schemas/IdentityDocument'
        extraFields:
          type: object
          description: Additional fields (if required)
    SenderPersonDataExtraFields:
      type: object
      description: >-
        Additional sender identification fields required for DEBIT transfers
        from Uzbekistan
      properties:
        pinfl:
          description: >
            Personal identification number (PINFL) of an individual in
            Uzbekistan.

            Required for `transferType = DEBIT` and `senderCountry = UZB`
          type: string
          example: '12345678901234'
        residencyCode:
          description: |
            Residency status in Uzbekistan.
            Required for `transferType = DEBIT` and `senderCountry = UZB`.
            Possible values:
              * `1` - Resident
              * `2` - Non-resident
          type: integer
          example: 1
    IdentityDocument:
      type: object
      description: Identity document details
      properties:
        documentType:
          description: |
            Identity document type. Possible values:
              * `ID` - National identity card
              * `PASSPORT` - Domestic (internal) passport
              * `FOREIGN_PASSPORT` - International passport used for cross-border identification
              * `RESIDENT_CARD` - Residence permit or permanent residency card issued by the country of stay
              * `MILITARY_ID` - Military identity document
              * `DRIVER_LICENSE` - Driver's license
              * `OTHER` - Other identity document not covered by the types above
          enum:
            - ID
            - PASSPORT
            - FOREIGN_PASSPORT
            - RESIDENT_CARD
            - MILITARY_ID
            - DRIVER_LICENSE
            - OTHER
          type: string
          example: PASSPORT
        documentCountry:
          description: >-
            Country code that issued the document, according to ISO 3166-1
            alpha-3
          type: string
          pattern: ^[A-Z]{3}$
          example: UZB
        series:
          description: Document series, if applicable
          type: string
          example: AB
        number:
          description: Document number
          type: string
          example: '754755'
        issuedDate:
          description: Document issue date in `DD-MM-YYYY` format
          type: string
          example: 12-06-2025
        issuedBy:
          description: Name of the authority that issued the document
          type: string
          example: UFMS FOR SPB №66
        extraFields:
          type: object
          description: Additional document fields if required
          additionalProperties:
            type: string
    RegisterTransferResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `0` - Request completed successfully
              * `3001` - A transfer with the provided externalTransferId has already been registered
              * `3003` - The transfer amount exceeds the single transaction limit
              * `3004` - The daily transfer amount limit has been reached or exceeded
              * `3010` - The specified identificationType is not allowed for this direction
              * `3011` - Required PersonData fields are missing according to the rules
              * `3012` - The monthly transfer amount limit has been reached or exceeded
              * `3013` - The daily number of transfers exceeds the allowed limit
              * `3014` - The monthly number of transfers exceeds the allowed limit
              * `3017` - Limits are not configured for the partner, or the limits service is unavailable
              * `3021` - Recipient’s card not found in the system
              * `3024` - Recipient’s bank not found or not supported by the system
              * `3030` - Sender failed stop-list check
              * `3031` - Recipient failed stop-list check
              * `3034` - Recipient’s card type/payment system not supported
              * `3102` - Exceeded the limit
              * `3103` - Rejected by security settings
              * `8002` - Access restriction by partner/direction/country/currency
              * `9000` - Internal error
              * `9100` - External service interaction error
          type: integer
          example: 0
        message:
          description: Response message
          type: string
          example: Request completed successfully
        result:
          description: Transfer information
          allOf:
            - $ref: '#/components/schemas/TransferResultStatusForRegister'
            - $ref: '#/components/schemas/TransferResult'
    TransferResultStatusForRegister:
      type: object
      required:
        - status
      properties:
        status:
          description: |
            Current transfer status. 

            Possible values (for both **CREDIT** and **DEBIT** transfer):
              * `REGISTERED` - Transfer successfully registered
              * `FAILED` - Transfer rejected
          type: string
          enum:
            - REGISTERED
            - FAILED
          example: REGISTERED
    ProcessTransferResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `0` - Request completed successfully
              * `2002` - Request must be repeated
              * `3003` - The transfer amount exceeds the single transaction limit
              * `3012` - The monthly transfer amount limit has been reached or exceeded
              * `3013` - The daily number of transfers exceeds the allowed limit
              * `3014` - The monthly number of transfers exceeds the allowed limit
              * `3017` - Limits are not configured for the partner, or the limits service is unavailable
              * `3020` - Sender’s card not found in the system
              * `3023` - Sender’s bank not found or not supported by the system
              * `3030` - Sender failed stop-list check
              * `3031` - Recipient failed stop-list check
              * `3032` - The client’s phone number in the request does not match the number linked to the card
              * `3035` - Transfer confirmation is not possible in the current status
              * `3036` - Confirmation performed after the allowed time window — transfer expired
              * `3037` - Error occurred while crediting funds
              * `3039` - Sender’s card type/payment system not supported
              * `3041` - Error occurred while debiting funds
              * `3054` - Transfer with the specified ID not found
              * `3102` - Exceeded the limit
              * `3103` - Rejected by security settings
              * `5003` - Exchange rate has changed since the transfer registration
              * `9000` - Internal error
              * `9100` - External service interaction error
          type: integer
          example: 0
        message:
          description: Response message
          type: string
          example: Request completed successfully
        result:
          description: Transfer details
          allOf:
            - $ref: '#/components/schemas/TransferResultStatusForProcess'
            - $ref: '#/components/schemas/TransferResult'
    TransferResultStatusForProcess:
      type: object
      required:
        - status
      properties:
        status:
          description: |
            Current transfer status. 

            Possible values for **CREDIT** transfer:
              * `SUCCESS` - Transfer successfully completed
              * `FAILED` - Transfer rejected

            Possible values for **DEBIT** transfer:
              * `REGISTERED` - Transfer registered (returns with response code `2002` - Request must be repeated)
              * `FAILED` - Transfer rejected
          type: string
          enum:
            - REGISTERED
            - SUCCESS
            - FAILED
          example: SUCCESS
    ProcessPendingTransferResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `2000` - Request accepted. Please wait for operation status via Callback or query the status manually
          type: integer
          example: 2000
        message:
          description: Response message
          type: string
          example: >-
            Request accepted. Wait for operation processing information in
            Callback or request status
        result:
          description: Transfer details with current status
          allOf:
            - $ref: '#/components/schemas/TransferResultStatusForProcessPending'
            - $ref: '#/components/schemas/TransferResult'
    TransferResultStatusForProcessPending:
      type: object
      required:
        - status
      properties:
        status:
          description: |
            Current transfer status. 

            Possible values (for both **CREDIT** and **DEBIT** transfer):
              * `PROCESSING` - Transfer processing initiated
          type: string
          enum:
            - PROCESSING
          example: PROCESSING
    NeedConfirmationProcessTransferResponse:
      type: object
      required:
        - code
        - message
        - confirmationData
      properties:
        code:
          description: |
            Response code. Possible values:
              * `2001` - Request completed successfully. Transfer confirmation required
          type: integer
          example: 2001
        message:
          description: Response message
          type: string
          example: Request completed successfully. Transfer confirmation required
        confirmationData:
          description: >-
            Confirmation type and value. Returned when transfer confirmation is
            required
          allOf:
            - $ref: '#/components/schemas/ConfirmationData'
        result:
          description: Transfer details
          allOf:
            - $ref: >-
                #/components/schemas/TransferResultStatusForNeedConfirmationProcess
            - $ref: '#/components/schemas/TransferResult'
    TransferResultStatusForNeedConfirmationProcess:
      type: object
      required:
        - status
      properties:
        status:
          description: |
            Current transfer status. 

            Possible values (only for **DEBIT** transfer):
              * `CONFIRMATION` - Transfer awaiting client confirmation
          type: string
          enum:
            - CONFIRMATION
          example: CONFIRMATION
    ConfirmationData:
      type: object
      required:
        - confirmationType
      properties:
        confirmationType:
          type: string
          enum:
            - OTP
            - 3DS
          description: |
            Confirmation method required to proceed. Possible values:
              * `OTP` - One-time password sent to the client
              * `3DS` - Three-Domain Secure protocol for online payment authentication.
          example: OTP
        confirmationValue:
          type: string
          description: |
            Confirmation value, if provided by Remit Core.
            For `confirmationType = OTP` contains the one-time password.
            May be absent if the OTP is delivered directly to the client
          example: '66549'
        extraFields:
          type: object
          allOf:
            - $ref: '#/components/schemas/ThreeDsExtraFields'
    ThreeDsExtraFields:
      properties:
        acsUrl:
          description: >-
            Link to the issuer bank’s ACS. Required for  `confirmationType =
            3DS`
          type: string
        termUrl:
          description: >-
            Return URL from the issuer bank's ACS. Required for
            `confirmationType = 3DS`
          type: string
        paReq:
          description: >-
            Payment Authentication Request message (base64). Required for
            `confirmationType = 3DS`
          type: string
          nullable: true
    ConfirmTransferResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `0` - Request completed successfully
              * `3003` - The transfer amount exceeds the single transaction limit
              * `3008` - OTP is incorrect. Please resend the code
              * `3012` - The monthly transfer amount limit has been reached or exceeded
              * `3013` - The daily number of transfers exceeds the allowed limit
              * `3014` - The monthly number of transfers exceeds the allowed limit
              * `3017` - Limits are not configured for the partner, or the limits service is unavailable
              * `3018` - Maximum number of OTP attempts exceeded. Operation rejected
              * `3035` - Transfer confirmation is not possible in the current status
              * `3036` - Confirmation performed after the allowed time window — transfer expired
              * `3040` - One-time password has expired. Please request a new code
              * `3041` - Error occurred while debiting funds
              * `3054` - Transfer with the specified ID not found
              * `5003` - Exchange rate has changed since the transfer registration
              * `9000` - Internal error
              * `9100` - External service interaction error
          type: integer
          example: 0
        message:
          description: Response message
          type: string
          example: Request completed successfully
        result:
          description: Transfer details
          allOf:
            - $ref: '#/components/schemas/TransferResultStatusForConfirm'
            - $ref: '#/components/schemas/TransferResult'
    TransferResultStatusForConfirm:
      type: object
      required:
        - status
      properties:
        status:
          description: |
            Current transfer status. 

            Possible values (only for **DEBIT** transfer):
              * `CONFIRMATION` - Transfer awaiting client confirmation (returns with response code `3008` - OTP is incorrect. Please resend the code)
              * `SUCCESS` - Transfer successfully completed
              * `FAILED` - Transfer rejected
          type: string
          enum:
            - CONFIRMATION
            - SUCCESS
            - FAILED
          example: SUCCESS
    ConfirmPendingTransferResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `2000` - Request accepted. Please wait for operation status via Callback or query the status manually
          type: integer
          example: 2000
        message:
          description: Response message
          type: string
          example: >-
            Request accepted. Wait for operation processing information in
            Callback or request status
        result:
          description: Transfer details with current status
          allOf:
            - $ref: '#/components/schemas/TransferResultStatusForConfirmPending'
            - $ref: '#/components/schemas/TransferResult'
    TransferResultStatusForConfirmPending:
      type: object
      required:
        - status
      properties:
        status:
          description: |
            Current transfer status. 

            Possible values (only for **DEBIT** transfer):
              * `CONFIRMING` - Transfer confirmation in progress
          type: string
          enum:
            - CONFIRMING
          example: CONFIRMING
    ResendOtpResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `0` - Request completed successfully
              * `3017` - Limits are not configured for the partner, or the limits service is unavailable
              * `3018` - Maximum number of OTP attempts exceeded. Operation rejected
              * `3035` - Transfer confirmation is not possible in the current status
              * `3036` - Confirmation performed after the allowed time window — transfer expired
              * `3041` - Error occurred while debiting funds
              * `3054` - Transfer with the specified ID not found
              * `9000` - Internal error
              * `9100` - External service interaction error
              * `9051` - Timeout while waiting for response from external service
          type: integer
          example: 0
        message:
          description: Response message
          type: string
          example: Request completed successfully
        result:
          description: Transfer details with current status
          allOf:
            - $ref: '#/components/schemas/TransferResultStatusForResendOtp'
            - $ref: '#/components/schemas/TransferResult'
    TransferResultStatusForResendOtp:
      type: object
      required:
        - status
      properties:
        status:
          description: |
            Current transfer status. 

            Possible values (only for **DEBIT** transfer):
              * `CONFIRMATION` - Transfer awaiting client confirmation
              * `FAILED` - Transfer rejected
          type: string
          enum:
            - CONFIRMATION
            - FAILED
          example: CONFIRMATION
    CancelTransferResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `0` - Request completed successfully
              * `3038` - Transfer status does not allow the requested operation
              * `3054` - Transfer with the specified ID not found
              * `3055` - Cancellation failed. Please retry the request
              * `8003` - Cancellation for credit transfer type prohibited
              * `9000` - Internal error
              * `9100` - External service interaction error
          type: integer
          example: 0
        message:
          description: Response message
          type: string
          example: Request completed successfully
        result:
          description: Transfer details with current status
          allOf:
            - $ref: '#/components/schemas/TransferResultStatusForCancel'
            - $ref: '#/components/schemas/TransferResult'
    TransferResultStatusForCancel:
      type: object
      required:
        - status
      properties:
        status:
          description: |
            Current transfer status. 

            Possible values (only for **DEBIT** transfer):
              * `CANCELLED` - Transfer successfully cancelled
              * `CANCELLING_FAILED` - Transfer cancellation is failed
          type: string
          enum:
            - CANCELLED
            - CANCELLING_FAILED
          example: CANCELLED
    CancelPendingTransferResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `2000` - Request accepted. Please wait for operation status via Callback or query the status manually
          type: integer
          example: 2000
        message:
          description: Response message
          type: string
          example: >-
            Request accepted. Wait for operation processing information in
            Callback or request status
        result:
          description: Transfer details with current status
          allOf:
            - $ref: '#/components/schemas/TransferResultStatusForCancelPending'
            - $ref: '#/components/schemas/TransferResult'
    TransferResultStatusForCancelPending:
      type: object
      required:
        - status
      properties:
        status:
          description: |
            Current transfer status. 

            Possible values (only for **DEBIT** transfer):
              * `CANCELLING` - Transfer cancellation in progress
          type: string
          enum:
            - CANCELLING
          example: CANCELLING
    StatusTransferResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `0` - Request completed successfully
              * `3054` - Transfer with the specified ID not found
              * `9000` - Internal error
          type: integer
          example: 0
        message:
          description: Response message
          type: string
          example: Request completed successfully
        result:
          description: Transfer details with current status
          allOf:
            - $ref: '#/components/schemas/TransferResultStatusForGetStatus'
            - $ref: '#/components/schemas/TransferResult'
        confirmationData:
          description: >
            Confirmation type and value. Returned when transfer confirmation is
            required.


            For **DEBIT** transfers in the `CONFIRMATION` status only.
          allOf:
            - $ref: '#/components/schemas/ConfirmationData'
    TransferResultStatusForGetStatus:
      type: object
      required:
        - status
      properties:
        status:
          description: |
            Current transfer status. 

            Possible values for **CREDIT** transfer:
              * `INIT` - Transfer initiated, registration in progress
              * `REGISTERED` - Transfer successfully registered
              * `PROCESSING` - Transfer processing initiated
              * `SUCCESS` - Transfer successfully completed
              * `FAILED` - Transfer rejected
              * `CANCELLED` - Transfer cancelled

            Possible values for **DEBIT** transfer:
              * `INIT` - Transfer initiated, registration in progress
              * `REGISTERED` - Transfer successfully registered
              * `PROCESSING` - Transfer processing initiated
              * `CONFIRMATION` - Transfer awaiting client confirmation
              * `CONFIRMING` - Transfer confirmation in progress
              * `SUCCESS` - Transfer successfully completed
              * `FAILED` - Transfer rejected
              * `CANCELLING` - Transfer cancellation in progress
              * `CANCELLED` - Transfer cancelled
              * `CANCELLING_FAILED` - Transfer cancellation is failed
          type: string
          enum:
            - INIT
            - REGISTERED
            - PROCESSING
            - CONFIRMATION
            - CONFIRMING
            - SUCCESS
            - FAILED
            - CANCELLING
            - CANCELLING_FAILED
            - CANCELLED
          example: SUCCESS
    TransferResult:
      type: object
      required:
        - transferId
        - externalTransferId
        - senderCurrencyCode
        - receiverCurrencyCode
      properties:
        transferId:
          description: Transfer identifier in Remit Core
          type: string
          format: uuid
          example: 01990610-f6fb-72fd-84c1-ff8cf5840599
        externalTransferId:
          type: string
          description: Transfer identifier in the Partner's system
          example: partner-tx-00123
        senderAmount:
          type: integer
          format: int64
          description: Transfer amount in minor units of sender's currency
          example: 100000
        senderCurrencyCode:
          type: string
          description: Sender's currency code according to ISO 4217 alpha-3
          pattern: ^[A-Z]{3}$
          example: UZS
        senderName:
          description: First name+Last name or cardholder name of transfer sender
          type: string
          example: PETR PETROV
        receiverAmount:
          type: integer
          format: int64
          description: >-
            Amount received by the recipient in minor units of recipient's
            currency
          example: 13900000
        receiverCurrencyCode:
          type: string
          description: Recipient's currency code according to ISO 4217 alpha-3
          pattern: ^[A-Z]{3}$
          example: UZS
        receiverName:
          description: First name+Last name or cardholder name of transfer recipient
          type: string
          example: IVAN IVANOV
        receiverPaymentSystem:
          description: Payment system of transfer recipient's payment instrument
          type: string
          example: UZCARD
        fee:
          type: integer
          format: int64
          description: Fee amount in minor units of settlements currency
          example: 1000
        exchangeRate:
          type: string
          description: >-
            Exchange rate from sender's currency to recipient's currency (with
            exactly 4 decimal places)
          example: '140.0000'
        rrn:
          description: Retrieval Reference Number - unique bank operation number
          type: string
          example: '524818898472'
    TransferIdRequest:
      type: object
      required:
        - transferId
      properties:
        transferId:
          description: >-
            Transfer identifier in Remit Core, received in the response to `POST
            /register`
          type: string
          example: 01990610-f6fb-72fd-84c1-ff8cf5840599
    ConfirmTransferRequest:
      type: object
      required:
        - transferId
        - otp
      properties:
        transferId:
          description: >-
            Transfer identifier in Remit Core, received in the response to `POST
            /register`
          type: string
          example: 01990610-f6fb-72fd-84c1-ff8cf5840599
        otp:
          description: One-time code for confirmation received by the client
          type: string
          example: '766855'
    GetBanksRequest:
      type: object
      required:
        - phoneNumber
        - receiverCountry
      properties:
        phoneNumber:
          description: Recipient's phone number (E.164 format)
          pattern: ^\+[1-9]\d{1,14}$
          type: string
          example: '+998948063815'
        receiverCountry:
          description: |
            Recipient's country code according to ISO 3166-1 alpha-3.
            Currently only `UZB` is supported
          type: string
          pattern: ^[A-Z]{3}$
          example: UZB
          enum:
            - UZB
    GetBanksResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `0` - Request completed successfully
              * `9100` - External service interaction error
          type: integer
          example: 0
        message:
          description: Response status message
          type: string
          example: Request completed successfully
        result:
          description: Response data. Present when `code = 0`
          allOf:
            - $ref: '#/components/schemas/GetBanksResult'
    GetBanksResult:
      type: object
      required:
        - banks
      properties:
        banks:
          description: >
            List of short bank codes where an active card was found for the
            specified phone number.

            May be empty if no active cards were found
          type: array
          items:
            type: string
          example:
            - NBU
            - SQB
            - UZB
    GetBalanceResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `0` - Request completed successfully
              * `3060` - Invalid account number in balance request
              * `9100` - External service interaction error
          type: integer
          example: 0
        message:
          description: Response status message
          type: string
          example: Request completed successfully
        result:
          description: Response data. Present when `code = 0`
          allOf:
            - $ref: '#/components/schemas/GetBalanceResult'
    GetBalanceResult:
      type: object
      required:
        - accountNumber
        - closingBalance
        - currency
      properties:
        accountNumber:
          type: string
          description: |
            Partner's account number to which the balance refers.
          example: '29126840100001190019'
        closingBalance:
          type: integer
          format: int64
          description: >
            Account balance in minor units of the account currency (e.g. cents
            for USD),

            as reflected in the core banking system (ABS) at the moment of the
            request.

            Note: some transactions of the current operational day may not yet
            be reflected

            until the ABS end-of-day processing completes.
          example: 8280085
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: |
            Account currency code according to ISO 4217 alpha-3
          example: USD
    422ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: |
            Response code. Possible values:
              * `1001` - The request body is not a valid JSON or does not match the expected schema structure
              * `1002` - Required fields are missing
              * `1003` - Format/range/enum requirements violated; the 'errors' array contains the fields and descriptions of the issues
              * `1101` - Required header is missing
          type: integer
          example: 1001
        message:
          description: Error message
          type: string
          example: Required field is missing
        errors:
          type: array
          description: List of field-level validation errors
          items:
            $ref: '#/components/schemas/ErrorDetails'
    ErrorDetails:
      type: object
      required:
        - field
        - message
      properties:
        field:
          description: Name of the field containing the error
          type: string
          example: receiverCurrencyCode
        message:
          description: Description of the validation error for this field
          type: string
          example: Currency code must be 3 characters
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: Response code
          type: integer
        message:
          description: Error message
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'
    TransferResultInfoCallback:
      description: Final transfer result delivered asynchronously
      allOf:
        - $ref: '#/components/schemas/TransferResultStatusForInfoCallback'
        - $ref: '#/components/schemas/TransferResult'
        - type: object
          required:
            - status
            - transferId
            - externalTransferId
            - senderAmount
            - senderCurrencyCode
            - receiverAmount
            - receiverCurrencyCode
            - exchangeRate
          properties:
            confirmationData:
              description: >
                Confirmation type and value. Returned when transfer confirmation
                is required.


                For **DEBIT** transfers in the `CONFIRMATION` status only.
              allOf:
                - $ref: '#/components/schemas/ConfirmationData'
    TransferResultStatusForInfoCallback:
      type: object
      required:
        - status
      properties:
        status:
          description: >
            Final transfer status. 


            Possible values for **CREDIT** transfer (for callback after `POST
            /process` with code `2000` in response):
              * `SUCCESS` - Transfer successfully completed
              * `FAILED` - Transfer rejected

            Possible values for **DEBIT** transfer:
              * For callback after `POST /process` or `POST /confirm` with code `2000` in response:
                 * `SUCCESS` - Transfer successfully completed 
                 * `FAILED` - Transfer rejected
              * Only for callback after `POST /process` with code `2000` in response:
                 * `CONFIRMATION` - Transfer awaiting client confirmation
              * For callback after `POST /cancel` with code `2000` in response:
                 * `CANCELLED` - Transfer successfully cancelled
                 * `CANCELLING_FAILED` - Transfer cancellation is failed
          type: string
          enum:
            - CONFIRMATION
            - SUCCESS
            - FAILED
            - CANCELLED
            - CANCELLING_FAILED
          example: SUCCESS
  securitySchemes:
    XApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Partner API key in UUID format. Issued upon onboarding. Required for all
        methods
  callbacks:
    TransferResultInfo:
      '{/callbackUrl}':
        post:
          summary: Transfer result callback
          description: >
            Asynchronous notification sent by Remit Core when transfer
            processing completes.

            Sent after `POST /process`, `POST /confirm` or `POST /cancel`
            returned code `2000`.

            The callback URL is agreed upon during Partner onboarding
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/TransferResultInfoCallback'
          responses:
            '200':
              description: Standard success response
            '500':
              description: Partner-side error while processing the callback
            2XX:
              description: Any other 2xx is also treated as success