openapi: 3.1.0
info:
  title: Almond Payout API
  description: >
    The Almond Payout API enables clients to execute domestic payouts by
    leveraging local banking partners and payout networks.


    As a client, you need to:
      - Authenticate to obtain an access token.
      - Discover payout providers by querying supported providers by country and retrieving provider-specific field requirements.
      - Check payout rates and fees for full transparency on send/receive amounts.
      - Create a payout with the required beneficiary and payment details.
      
    Almond then orchestrates the process — verifying balance availability,
    executing the payout through the chosen payout partner, and updating the
    payout status — while providing clients with real-time status updates and
    notifications.
      <p align="center">
        <img src="/images/payout_flow_final.png" alt="System Flow" width="900"/><br>
        <span style="font-size:0.9em;">Figure: Payout Flow</span>
       </p>
  version: 1.1.0
  contact:
    name: Almond Fintech API Support
    url: https://www.almondfintech.com/contact-us
    email: info@almondfintech.com
  license:
    name: Copyright © 2025 Almond FinTech. All rights reserved.
    url: https://almondfintech.com
servers:
  - url: https://api.sandbox.almondfintech.com
    description: Sandbox
  - url: https://api.almondfintech.com
    description: Production
paths:
  /v2/destination-members:
    get:
      tags:
        - Member
      summary: Get Destination Members
      description: >
        Retrieves a list of destination members available for the authenticated
        source member.


        **Response Details:**

        - Returns information about all destination members that have active
        corridors with the member.

        - Each destination member includes:
          - **memberId**: Unique identifier for the destination member
          - **name**: Display name of the destination member/payout partner
          - **supportedCcyList**: List of currencies supported by this destination member
          - **prefundBalance**: Current prefund balances for each supported currency

        **Use Cases:**

        - Discover available payout partners for the  member

        - Check prefund balances before initiating payouts

        - View supported currencies for each destination member


        **Business Context:**

        - Destination members are payout partners that can receive and disburse
        funds in their respective countries

        - Prefund balances represent funds already transferred to the
        destination member for faster payouts
      operationId: getDestinationMembers
      security:
        - OAuth2:
            - member
      responses:
        '200':
          description: Destination members list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DestinationMemberResponse'
              examples:
                multipleDestinationMembers:
                  summary: Multiple destination members with balances
                  description: >-
                    Example response showing multiple destination members with
                    prefund balances
                  value:
                    members:
                      - memberId: DEST_MEMBER_PH
                        name: Philippines Payout Partner
                        supportedCcyList:
                          - PHP
                        prefundBalance:
                          - amount: '150000.50'
                            ccy: PHP
                      - memberId: DEST_MEMBER_IN
                        name: Indonesia Payout Partner
                        supportedCcyList:
                          - IDR
                        prefundBalance:
                          - amount: '500000.00'
                            ccy: INR
                singleDestinationMember:
                  summary: Single destination member
                  description: Example response with a single destination member
                  value:
                    members:
                      - memberId: DEST_MEMBER_MX
                        name: Mexico Payout Partner
                        supportedCcyList:
                          - MXN
                          - USD
                        prefundBalance:
                          - amount: '75000.00'
                            ccy: MXN
                          - amount: '1500.00'
                            ccy: USD
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
  /v2/payout-providers:
    get:
      tags:
        - Payout Providers
      summary: Get Payout Providers
      description: >
        Returns a list of supported payout providers.


        If `countryCode` is provided, only payout providers for the specified

        country are returned. Without `countryCode`, all supported payout
        providers are returned.
      operationId: getPayoutProviders
      security:
        - OAuth2:
            - member
      parameters:
        - name: countryCode
          in: query
          required: false
          description: ISO alpha-2 Country Code of payout provider
          schema:
            type: string
            pattern: ^[A-Za-z]{2}$
            example: ID
        - name: payoutMethod
          in: query
          required: false
          description: Payout Method
          schema:
            $ref: '#/components/schemas/PayoutMethodEnum'
        - name: segment
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SegmentEnum'
      responses:
        '200':
          description: Payout Providers list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutProviderListResponse'
              examples:
                example:
                  value:
                    payoutProviders:
                      - name: BANK ABC INDONESIA
                        payoutProviderId: BANK_ABC_INDONESIA
                        countryCode: ID
                        payoutMethod: BANK_ACCOUNT
                        active: 'Y'
                        supportedSegments:
                          - C2C
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
  /v2/payout-providers/{payout-provider-id}:
    get:
      tags:
        - Payout Providers
      description: >
        This API provides a comprehensive list of fields, including their
        respective data types and validation specifications, necessary for
        initiating a payout API request.
      summary: Get Payout Provider
      operationId: getPayoutProvider
      security:
        - OAuth2:
            - member
      parameters:
        - name: payout-provider-id
          in: path
          required: true
          description: Payout provider Id
          example: BABC
          schema:
            type: string
            pattern: ^[A-Za-z0-9-]*$
        - name: payoutMethod
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/PayoutMethodEnum'
        - name: segment
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SegmentEnum'
      responses:
        '200':
          description: Payout provider response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutProviderResponse'
              examples:
                bankAccountExample:
                  summary: Bank Account Payout Provider
                  description: >-
                    Example response for a bank account payout provider in
                    Indonesia
                  value:
                    name: Bank ABC Indonesia
                    payoutProviderId: BABC
                    countryCode: ID
                    payoutMethod: BANK_ACCOUNT
                    supportedSegments:
                      - C2C
                      - B2B
                    payoutInitiateRequestFields:
                      - name: beneficiary.accountNumber
                        dataType: String
                        mandatory: 'Y'
                        regexPattern: ^[0-9]{10,16}$
                        minLength: 10
                        maxLength: 16
                      - name: beneficiary.firstName
                        dataType: String
                        mandatory: 'Y'
                        regexPattern: ^[A-Za-z ]{1,50}$
                        minLength: 1
                        maxLength: 50
                      - name: beneficiary.lastName
                        dataType: String
                        mandatory: 'Y'
                        regexPattern: ^[A-Za-z ]{1,50}$
                        minLength: 1
                        maxLength: 50
                      - name: payoutAmt
                        dataType: BigDecimal
                        mandatory: 'Y'
                      - name: destinationCcy
                        dataType: String
                        mandatory: 'Y'
                        regexPattern: ^[A-Z]{3}$
                        minLength: 3
                        maxLength: 3
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
  /v2/source-of-funds-codes:
    get:
      tags:
        - Static Fields
      summary: Get Source Of Funds Codes
      description: >
        Returns a list of source of funds codes that can be used when initiating
        payouts.


        These codes indicate where the sender's funds originated from and are
        used for compliance and regulatory purposes.
      operationId: getSourceOfFundsCodes
      security:
        - OAuth2:
            - payouts
      responses:
        '200':
          description: Source of Funds Codes List
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FieldCodeInfo'
              examples:
                sourceOfFundsCodes:
                  summary: Source of Funds Codes
                  description: List of available source of funds codes
                  value:
                    - code: DONATIONS
                      description: Donations
                    - code: LOTTERY
                      description: Lottery
                    - code: SALARY
                      description: Salary
                    - code: FREELANCE_INCOME
                      description: Freelance income
                    - code: RETIREMENT_FUND
                      description: Retirement fund
                    - code: PROPERTY_SALE
                      description: Sale of property
                    - code: FOREX_GAINS
                      description: Forex Gains
                    - code: PENSION
                      description: Pension income/money
                    - code: FAMILY_INCOME
                      description: Family income
                    - code: FINANCIAL_SUPPORT_FROM_SPOUSE
                      description: Financial support from spouse
                    - code: LOANS
                      description: Loan
                    - code: BUSINESS_INCOME
                      description: Income from business
                    - code: COMMISSION
                      description: Commission
                    - code: PROPERTY_INVESTMENT
                      description: Property investment
                    - code: SHARES_INVESTMENT
                      description: Shares investment
                    - code: SAVINGS
                      description: Personal savings
                    - code: BALANCE_FROM_TRAVELLING
                      description: Balance from travelling
  /v2/purpose-codes:
    get:
      tags:
        - Static Fields
      summary: Get Purpose Codes
      description: >
        Returns a list of purpose codes that can be used when initiating
        payouts.


        These codes indicate the purpose or reason for the payout and are
        required for regulatory compliance and reporting.
      operationId: getPurposeCodes
      security:
        - OAuth2:
            - payouts
      responses:
        '200':
          description: Purpose Codes List
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FieldCodeInfo'
              examples:
                purposeCodes:
                  summary: Purpose Codes
                  description: List of available payout purpose codes
                  value:
                    - code: CONSTRUCTION
                      description: Construction costs/expenses
                    - code: SERVICES_PAYMENT
                      description: Services payment
                    - code: EDUCATION
                      description: Education related expenses
                    - code: MEDICAL
                      description: Medical expenses
                    - code: FAMILY_MAINTENANCE
                      description: Family maintenance
                    - code: PROPERTY_PURCHASE
                      description: Purchase of residential property
                    - code: UTILITIES
                      description: Utility bills
                    - code: PERSONAL_EXPENSES
                      description: Personal expenses
                    - code: INVESTMENT_GAINS
                      description: Profits/income from investment
                    - code: SAVINGS
                      description: Personal Savings
                    - code: SALARY
                      description: Salary payment
                    - code: LEGAL_SERVICES
                      description: Legal services
                    - code: GRANTS
                      description: Grants
                    - code: GIFTS
                      description: Gifts
                    - code: DONATIONS
                      description: Donations
                    - code: WEDDING
                      description: Wedding expenses
                    - code: RELIGIOUS_EXPENSES
                      description: Religious expenses
                    - code: FREELANCE_PAYMENT
                      description: freelance payment
  /v2/relationship-codes:
    get:
      tags:
        - Static Fields
      summary: Get Relationship Codes
      description: >
        Returns a list of relationship codes that can be used when initiating
        payouts.


        These codes define the relationship between the sender and the
        beneficiary and are used for compliance verification.
      operationId: getRelationshipCodes
      security:
        - OAuth2:
            - payouts
      responses:
        '200':
          description: Relationship Codes List
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FieldCodeInfo'
              examples:
                relationshipCodes:
                  summary: Relationship Codes
                  description: List of available sender-beneficiary relationship codes
                  value:
                    - code: FAMILY
                      description: Family
                    - code: BUSINESS_PARTNER
                      description: Business partner
                    - code: FRIEND
                      description: Friend
                    - code: FRIENDS_FAMILY
                      description: Friends family
                    - code: EMPLOYEE
                      description: Employee
                    - code: SELF
                      description: Own Account
                    - code: SIBLING
                      description: Sibling
                    - code: PARENT
                      description: Parent
                    - code: SPOUSE
                      description: Spouse
                    - code: CHILDREN
                      description: Children
                    - code: SUPPLIER
                      description: Supplier
                    - code: NOT_RELATED
                      description: Not related
                    - code: RELATIVE
                      description: Relative
                    - code: IN_LAWS
                      description: In laws
                    - code: SERVICE_PROVIDER
                      description: Service provider
                    - code: SPOUSE_EMPLOYEE
                      description: Spouse employee
                    - code: SPOUSE_EMPLOYEE_FAMILY
                      description: Spouse employees family
                    - code: CHARITY_RECIPIENT
                      description: Receiver of charitable funds
  /v2/payout-limits:
    get:
      tags:
        - Payout
      summary: Get Payout Limits
      description: >
        Retrieves the minimum and maximum payout limits for payout providers
        based on the specified country code and/or payout provider ID.


        **Query Parameters:**

        - At least one of `countryCode` or `payoutProviderId` must be provided.


        **Response:**

        - Returns a list of payout limits, each containing the currency code,
        minimum limit, and maximum limit.


        **Use Cases:**

        - Check payout limits before initiating a payout

        - Display available payout limits to end users

        - Validate payout amounts against configured limits
      operationId: getPayoutLimits
      security:
        - OAuth2:
            - payouts
      parameters:
        - name: countryCode
          schema:
            type: string
            pattern: ^[A-Za-z]{2}$
          in: query
          required: false
          description: Country Code
        - name: payoutProviderId
          schema:
            type: string
            pattern: ^[A-Za-z_]*$
          in: query
          required: false
      responses:
        '200':
          description: List of payout limits response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutLimitsResponse'
              examples:
                singleCurrency:
                  summary: Single currency with limits
                  description: >-
                    Example response showing payout limits for a single currency
                    when querying by payout provider ID
                  value:
                    - currency: PHP
                      minimumLimit: 500
                      maximumLimit: 250000
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                missingParameters:
                  summary: Missing required parameters
                  description: >-
                    Error when neither countryCode nor payoutProviderId is
                    provided
                  value:
                    code: BAD_REQUEST
                    message: Bad Request
                    detail: Either 'countryCode' or 'payoutProviderId' is required.
                invalidCountryCode:
                  summary: Invalid country code format
                  description: Error when country code doesn't match the required pattern
                  value:
                    code: INVALID_COUNTRY_CODE
                    message: Invalid country code format
                    detail: >-
                      Country code must be a 2-letter ISO code. Provided value:
                      USA
                invalidPayoutProviderId:
                  summary: Invalid payout provider ID format
                  description: >-
                    Error when payout provider ID doesn't match the required
                    pattern
                  value:
                    code: INVALID_PAYOUT_PROVIDER_ID
                    message: Invalid payout provider ID format
                    detail: >-
                      Payout provider ID must match pattern ^[A-Za-z_ ]*$.
                      Provided value: PROV@123
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                countryNotFound:
                  summary: Country not found
                  description: >-
                    Error when no destination member is found for the specified
                    country code
                  value:
                    code: NOT_FOUND
                    message: Not Found
                    detail: No destination member found for the country code 'XX'.
                payoutProviderNotFound:
                  summary: Payout provider not found
                  description: Error when the specified payout provider ID doesn't exist
                  value:
                    code: NOT_FOUND
                    message: Not Found
                    detail: >-
                      Payout provider(PayoutProviderId) 'INVALID_PROV' does not
                      exist in the system.
                limitsNotFound:
                  summary: Payout limits not configured
                  description: >-
                    Error when payout limits are not configured for the
                    specified country
                  value:
                    code: NOT_FOUND
                    message: Not Found
                    detail: >-
                      Payout limits for country code 'US' does not exist in the
                      system.
  /v2/payouts:
    post:
      tags:
        - Payout
      summary: Initiate Payout
      description: >

        Creates a new payout with the provided request details.  


        - On success, the response includes:  
          * **payoutId** – Unique identifier for the initiated payout. This ID must be used for subsequent operations (e.g., status checks, cancellation).  
          * **payoutStatus** – Will return `"ACCP"` if the payout request is received successfully.  

        This endpoint is the entry point for executing a payment or transfer,
        and serves as the foundation for all subsequent payout lifecycle
        operations.
      operationId: initiatePayout
      security:
        - OAuth2:
            - payouts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutInitiateRequest'
            examples:
              example:
                value:
                  sourceMemberPayoutId: PAYOUT-2024-003
                  payoutProviderId: PAYOUT-PROVIDER-1
                  destinationCcy: PHP
                  payoutAmt: 5500
                  payoutMethod: BANK_ACCOUNT
                  segment: C2C
                  sender:
                    firstName: Jane
                    lastName: Smith
                    countryCode: US
                  beneficiary:
                    firstName: John
                    lastName: Doe
                    accountNumber: '1234567890'
                    countryCode: PH
                  complianceInfo:
                    purpose: FAMILY_MAINTENANCE
        required: true
      responses:
        '201':
          description: Payout Initiated.
          headers:
            Location:
              schema:
                type: string
              description: >-
                Location of the created resource i.e. GET
                /v2/payouts/{payout-id}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutInitiateResponse'
              examples:
                example:
                  value:
                    payoutId: a4685b57-8788-4b4b-a35f-1066b68c23ea
                    sourceMemberPayoutId: PAYOUT-2024-001
                    payoutStatus: ACCP
                    destinationCcy: PHP
                    payoutAmt: 5500
                    transferFee: 5
                    beneficiaryName: John Doe
                    expiryTime: '2026-01-21T08:07:13.597048Z'
                    links:
                      process: >-
                        /v2/payouts/a4685b57-8788-4b4b-a35f-1066b68c23ea/process"
                      status: /v2/payouts/a4685b57-8788-4b4b-a35f-1066b68c23ea/status
                      details: /v2/payouts/a4685b57-8788-4b4b-a35f-1066b68c23ea
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                missingRequiredField:
                  summary: Missing Required Field
                  value:
                    code: 400
                    message: Bad Request
                    detail: Required field payoutProviderId is missing
                invalidCurrencyCode:
                  summary: Invalid Currency Code
                  value:
                    code: 400
                    message: Bad Request
                    detail: Invalid currency code for destinationCcy
        '404':
          description: Payout not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                payoutNotFound:
                  summary: Payout Not Found
                  value:
                    code: 404
                    message: Not Found
                    detail: >-
                      Payout not found with ID:
                      a4685b57-8788-4b4b-a35f-1066b68c23ea
    get:
      tags:
        - Payout
      summary: Get Payouts
      description: >
        Get payouts with filter and pagination support.


        **Example Request:**

        ```

        GET
        /v2/payouts?page=0&size=10&payoutStatus=ACCP&senderCountry=US&beneficiaryCountry=PH

        ```


        **Query Parameters:**

        - `page` - Page number (default: 0)

        - `size` - Number of records per page (default: 10)

        - `sortField` - Field to sort by

        - `sortDirection` - Sort direction (ASC/DESC)

        - `sourceMemberPayoutId` - Filter by source member payout ID (your
        unique payout identifier)

        - `payoutId` - Filter by system payout ID (UUID format)

        - `creationTime` - Filter by creation date (YYYY-MM-DD)

        - `completionTime` - Filter by completion date (YYYY-MM-DD)

        - `senderName` - Filter by sender name

        - `senderCountry` - Filter by sender country code

        - `beneficiaryName` - Filter by beneficiary name

        - `beneficiaryCountry` - Filter by beneficiary country code

        - `payoutProviderId` - Filter by payout provider id

        - `payoutStatus` - Filter by payout status (ACCP, PNDG, PRCD, etc.)
      operationId: getPayouts
      security:
        - OAuth2:
            - payouts
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PayoutSortField'
        - $ref: '#/components/parameters/SortDirection'
        - $ref: '#/components/parameters/SourceMemberPayoutId'
        - $ref: '#/components/parameters/PayoutIdQuery'
        - $ref: '#/components/parameters/CreationTime'
        - $ref: '#/components/parameters/CompletionTime'
        - $ref: '#/components/parameters/SenderName'
        - $ref: '#/components/parameters/SenderCountry'
        - $ref: '#/components/parameters/BeneficiaryName'
        - $ref: '#/components/parameters/BeneficiaryCountry'
        - $ref: '#/components/parameters/PayoutProviderId'
        - $ref: '#/components/parameters/PayoutStatus'
      responses:
        '200':
          description: Payout List Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutListResponse'
              example:
                payouts:
                  - payoutId: a4685b57-8788-4b4b-a35f-1066b68c23ea
                    payoutStatus: ACCP
                    sourceMemberPayoutId: PAYOUT-2024-001
                    sender:
                      firstName: Jane
                      lastName: Smith
                      countryCode: US
                    beneficiary:
                      firstName: John
                      lastName: Doe
                      countryCode: PH
                      accountNumber: '1234567890'
                    payoutAmt: 5500
                    destinationCcy: PHP
                    transferFee: 5
                    payoutProviderId: PAYOUT-PROVIDER-1
                    payoutMethod: BANK_ACCOUNT
                    creationTime: '2026-01-21T08:07:10Z'
                    intiateTime: '2026-01-21T08:07:13Z'
                  - payoutId: b5796c68-9899-5c5c-b46g-2177c79d34fb
                    payoutStatus: PRCD
                    sourceMemberPayoutId: PAYOUT-2024-002
                    sender:
                      firstName: Alice
                    beneficiary:
                      accountNumber: '9876543210'
                    payoutAmt: 11000
                    destinationCcy: PHP
                    transferFee: 5
                    payoutProviderId: PAYOUT-PROVIDER-1
                    payoutMethod: BANK_ACCOUNT
                    creationTime: '2026-01-21T08:07:10Z'
                    intiateTime: '2026-01-21T08:07:13Z'
                    completionTime: '2026-01-21T08:08:13Z'
                totalPages: 5
                totalRecords: 42
                page: 0
                size: 10
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              example:
                code: 400
                message: Bad Request
                detail: >-
                  Invalid date format for creationTime. Expected format:
                  YYYY-MM-DD
  /v2/payouts/{payout-id}/process:
    post:
      tags:
        - Payout
      summary: Process Payout
      operationId: processPayout
      security:
        - OAuth2:
            - payouts
      parameters:
        - $ref: '#/components/parameters/PayoutId'
      responses:
        '200':
          description: Payout Processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutProcessResponse'
              examples:
                successfulProcess:
                  summary: Successful Payout Processing
                  description: Example of a payout processed successfully
                  value:
                    payoutStatus: PRCD
                    cashoutStatus: 'Y'
                cashPickupPending:
                  summary: Cash Pickup Pending
                  description: >-
                    Example when cash pickup passcode is generated but payout is
                    pending
                  value:
                    payoutStatus: PNDG
                    cashoutStatus: 'N'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                invalidPayoutId:
                  summary: Invalid Payout ID Format
                  value:
                    code: 400
                    message: Bad Request
                    detail: Invalid payout ID format
                missingRequiredField:
                  summary: Missing Required Field
                  value:
                    code: 400
                    message: Bad Request
                    detail: Required field payoutStatus is missing
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                payoutNotFound:
                  summary: Payout Not Found
                  value:
                    code: 404
                    message: Not Found
                    detail: 'Payout not found with ID: 123456'
  /v2/payouts/{payout-id}:
    get:
      tags:
        - Payout
      summary: Get Payout Details
      description: >
        Fetches detailed information about a specific payout using its unique
        `payoutId`.


        Returns comprehensive payout information including:

        - Payout details (amount, transfer fee)

        - Sender and beneficiary information

        - Current payout status

        - Timestamps (creation, completion)

        - Compliance information
      operationId: getPayout
      security:
        - OAuth2:
            - payouts
      parameters:
        - $ref: '#/components/parameters/PayoutId'
      responses:
        '200':
          description: Payout response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
              examples:
                successfulPayout:
                  summary: Successful Payout (ACCP Status)
                  description: >-
                    Example of a successfully accepted payout with complete
                    details
                  value:
                    payoutId: a4685b57-8788-4b4b-a35f-1066b68c23ea
                    payoutStatus: ACCP
                    sourceMemberPayoutId: PAYOUT-2024-001
                    sender:
                      firstName: Jane
                      middleName: Marie
                      lastName: Smith
                      countryCode: US
                      phone: +1-555-0123
                      email: jane.smith@example.com
                      entityType: INDIVIDUAL
                    beneficiary:
                      firstName: John
                      middleName: Carlos
                      lastName: Doe
                      countryCode: PH
                      accountNumber: '1234567890'
                      accountName: John C. Doe
                      phone: +63-917-1234567
                      entityType: INDIVIDUAL
                    payoutAmt: 5500
                    destinationCcy: PHP
                    transferFee: 5
                    expiryTime: '2024-12-18T12:00:00Z'
                    payoutProviderId: PAYOUT-PROVIDER-1
                    payoutMethod: BANK_ACCOUNT
                    segment: C2C
                    compliance:
                      sourceOfFunds: SALARY
                      purpose: FAMILY_MAINTENANCE
                      relationship: PARENT
                    creationTime: '2026-01-21T08:07:10Z'
                    intiateTime: '2026-01-21T08:07:13Z'
                pendingPayout:
                  summary: Pending Payout (PNDG Status)
                  description: Example of a payout that is pending processing
                  value:
                    payoutId: b5796c68-9899-5c5c-b46g-2177c79d34fb
                    payoutStatus: PNDG
                    sourceMemberPayoutId: PAYOUT-2024-002
                    sender:
                      firstName: Alice
                      lastName: Johnson
                      countryCode: US
                      entityType: INDIVIDUAL
                    beneficiary:
                      firstName: Maria
                      lastName: Santos
                      countryCode: PH
                      accountNumber: '9876543210'
                      entityType: INDIVIDUAL
                    payoutAmt: 11000
                    destinationCcy: PHP
                    transferFee: 5
                    payoutProviderId: PAYOUT-PROVIDER-1
                    payoutMethod: BANK_ACCOUNT
                    segment: C2C
                    creationTime: '2026-01-21T08:07:10Z'
                    intiateTime: '2026-01-21T08:07:13Z'
                rejectedPayout:
                  summary: Rejected Payout (RJCT Status)
                  description: Example of a payout that was rejected with reason
                  value:
                    payoutId: c6807d79-0a0a-6d6d-c57h-3288d80e45gc
                    payoutStatus: RJCT
                    sourceMemberPayoutId: PAYOUT-2024-003
                    sender:
                      firstName: Bob
                      lastName: Williams
                      countryCode: US
                      entityType: INDIVIDUAL
                    beneficiary:
                      firstName: Pedro
                      lastName: Cruz
                      countryCode: PH
                      accountNumber: '5555555555'
                      entityType: INDIVIDUAL
                    payoutAmt: 8250
                    destinationCcy: PHP
                    transferFee: 5
                    payoutProviderId: PAYOUT-PROVIDER-1
                    payoutMethod: BANK_ACCOUNT
                    segment: C2C
                    rejectReason: Invalid account number
                    creationTime: '2026-01-21T08:07:10Z'
                    intiateTime: '2026-01-21T08:07:13Z'
                    rejectionTime: '2026-01-21T08:08:13Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                invalidPayoutId:
                  summary: Invalid Payout ID Format
                  value:
                    code: 400
                    message: Bad Request
                    detail: Invalid payout ID format
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                payoutNotFound:
                  summary: Payout Not Found
                  value:
                    code: 404
                    message: Not Found
                    detail: >-
                      Payout not found with ID:
                      a4685b57-8788-4b4b-a35f-1066b68c23ea
  /v2/payouts/{payout-id}/status:
    get:
      tags:
        - Payout
      summary: Get Payout Status
      description: >
        Retrieves the current status of a specific payout using its unique
        `payoutId`.


        **Payout Status Values:**

        - `RCVD` - Received: Payout request has been received

        - `ACCP` - Accepted: Payout has been accepted for processing

        - `PNDG` - Pending: Payout is pending processing

        - `PRCD` - Processed: Payout has been successfully processed

        - `RJCT` - Rejected: Payout was rejected

        - `CNCL` - Cancelled: Payout was cancelled

        - `EXPD` - Expired: Payout has expired

        - `FAIL` - Failed: Payout processing failed

        - `RVSD` - Reversed: Payout was reversed


        **Cancellation Status Values (when applicable):**

        - `ACCP` - Cancellation accepted

        - `PNDG` - Cancellation pending

        - `PRCD` - Cancellation processed

        - `RJCT` - Cancellation rejected
      operationId: getPayoutStatus
      security:
        - OAuth2:
            - payouts
      parameters:
        - $ref: '#/components/parameters/PayoutId'
      responses:
        '200':
          description: Payout status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutStatusResponse'
              examples:
                acceptedStatus:
                  summary: Accepted Payout
                  description: Payout has been accepted and is ready for processing
                  value:
                    payoutStatus: ACCP
                pendingStatus:
                  summary: Pending Payout
                  description: Payout is pending processing
                  value:
                    payoutStatus: PNDG
                processedStatus:
                  summary: Processed Payout
                  description: Payout has been successfully processed and completed
                  value:
                    payoutStatus: PRCD
                rejectedStatus:
                  summary: Rejected Payout
                  description: Payout was rejected with a reason
                  value:
                    payoutStatus: RJCT
                    rejectReason: Invalid account number
                cancelledStatus:
                  summary: Cancelled Payout
                  description: Payout was cancelled by the user
                  value:
                    payoutStatus: CNCL
                    payoutCancellationStatus: PRCD
                cancelPendingStatus:
                  summary: Cancellation Pending
                  description: Payout cancellation request is pending
                  value:
                    payoutStatus: ACCP
                    payoutCancellationStatus: PNDG
                expiredStatus:
                  summary: Expired Payout
                  description: Payout has expired
                  value:
                    payoutStatus: EXPD
                failedStatus:
                  summary: Failed Payout
                  description: Payout processing failed
                  value:
                    payoutStatus: FAIL
                    rejectReason: Destination system unavailable
                reversedStatus:
                  summary: Reversed Payout
                  description: Payout was reversed after processing
                  value:
                    payoutStatus: RVSD
                    reversal: Funds returned to sender
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                invalidPayoutId:
                  summary: Invalid Payout ID Format
                  value:
                    code: 400
                    message: Bad Request
                    detail: Invalid payout ID format
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                payoutNotFound:
                  summary: Payout Not Found
                  value:
                    code: 404
                    message: Not Found
                    detail: >-
                      Payout not found with ID:
                      a4685b57-8788-4b4b-a35f-1066b68c23ea
  /v2/payouts/{payout-id}/cancel:
    post:
      tags:
        - Payout
      summary: Cancel Payout
      description: >
        Submits a cancellation request for a specific payout identified by its
        unique `payoutId`.
      operationId: cancelPayout
      security:
        - OAuth2:
            - payouts
      parameters:
        - $ref: '#/components/parameters/PayoutId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutCancellationRequest'
            example:
              cancellationReason: Customer requested cancellation
        required: true
      responses:
        '200':
          description: Payout cancellation initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutCancellationResponse'
              example:
                payoutStatus: ACCP
                payoutCancellationStatus: PNDG
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              example:
                code: 400
                message: Bad Request
                detail: >-
                  Cancellation reason is required and must be between 1-50
                  characters
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              example:
                code: 404
                message: Not Found
                detail: 'Payout not found with ID: a4685b57-8788-4b4b-a35f-1066b68c23ea'
components:
  schemas:
    BalanceInfo:
      type: object
      properties:
        amount:
          type: string
        ccy:
          type: string
    DestinationMemberInfo:
      type: object
      properties:
        memberId:
          type: string
        name:
          type: string
        supportedCcyList:
          type: array
          items:
            type: string
        prefundBalance:
          type: array
          items:
            $ref: '#/components/schemas/BalanceInfo'
    DestinationMemberResponse:
      type: object
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/DestinationMemberInfo'
    ErrorInfo:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        detail:
          type: string
    PayoutMethodEnum:
      type: string
      description: |2-
         BANK_ACCOUNT: Bank Account service,

         CASH_PICKUP: Cash pickup service,

         WALLET: Wallet service
      enum:
        - BANK_ACCOUNT
        - CASH_PICKUP
        - WALLET
      default: BANK_ACCOUNT
    SegmentEnum:
      type: string
      description: |2-
         C2C: From an individual to an individual,

         B2B: From a business to a business
      enum:
        - C2C
        - B2B
      default: C2C
    CashPickupAddress:
      type: object
      properties:
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zipCode:
          type: string
        country:
          type: string
    PayoutProviderInfo:
      type: object
      properties:
        name:
          type: string
        payoutProviderId:
          type: string
        countryCode:
          type: string
        payoutMethod:
          type: string
        active:
          type: string
        supportedSegments:
          type: array
          items:
            $ref: '#/components/schemas/SegmentEnum'
        cashPickupLocation:
          $ref: '#/components/schemas/CashPickupAddress'
    PayoutProviderListResponse:
      type: object
      properties:
        payoutProviders:
          type: array
          items:
            $ref: '#/components/schemas/PayoutProviderInfo'
          default: []
    MandatoryEnum:
      type: string
      description: |2-
         Y: Yes,

         N: No
      enum:
        - 'Y'
        - 'N'
    Field:
      type: object
      properties:
        name:
          type: string
        dataType:
          type: string
        mandatory:
          $ref: '#/components/schemas/MandatoryEnum'
        allowedValues:
          type: string
        minValue:
          type: string
        maxValue:
          type: string
        regexPattern:
          type: string
        minLength:
          type: integer
        maxLength:
          type: integer
    PayoutProviderResponse:
      type: object
      properties:
        name:
          type: string
        payoutProviderId:
          type: string
        countryCode:
          type: string
        payoutMethod:
          type: string
        supportedSegments:
          type: array
          items:
            $ref: '#/components/schemas/SegmentEnum'
        cashPickupLocation:
          $ref: '#/components/schemas/CashPickupAddress'
        payoutInitiateRequestFields:
          type: array
          items:
            $ref: '#/components/schemas/Field'
    FieldCodeInfo:
      type: object
      properties:
        code:
          type: string
          description: The code value
        description:
          type: string
          description: Human-readable description of the code
    PayoutLimit:
      type: object
      properties:
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        minimumLimit:
          type: number
        maximumLimit:
          type: number
    PayoutLimitsResponse:
      type: array
      items:
        $ref: '#/components/schemas/PayoutLimit'
    PayoutSortEnum:
      type: string
      enum:
        - sourceMemberPayoutId
        - payoutId
        - creationTime
        - completionTime
        - senderName
        - senderCountry
        - beneficiaryName
        - beneficiaryCountry
        - payoutProviderId
        - payoutStatus
    SortDirectionEnum:
      type: string
      enum:
        - asc
        - desc
    PayoutStatusEnum:
      type: string
      description: |2-
         RCVD: Received,

         ACCP: Accepted, 

         PNDG: Pending,

         PRCD: Processed,

         RJCT: Rejected,

         CNCL: Cancelled,

         EXPD: Expired,

         FAIL: Failed,

         RVSD: Reversed
      enum:
        - RCVD
        - ACCP
        - PNDG
        - PRCD
        - RJCT
        - CNCL
        - EXPD
        - FAIL
        - RVSD
    GenderEnum:
      type: string
      enum:
        - M
        - F
    AddressInfo:
      type: object
      properties:
        address:
          type: string
        address2:
          type: string
        externalNumber:
          type: string
        internalNumber:
          type: string
        city:
          type: string
        suburb:
          type: string
        county:
          type: string
        state:
          type: string
        postalCode:
          type: string
        street:
          type: string
        country:
          type: string
    Sender:
      type: object
      required:
        - firstName
        - lastName
      properties:
        firstName:
          type: string
          minLength: 1
        middleName:
          type: string
        lastName:
          type: string
        lastName2:
          type: string
        gender:
          $ref: '#/components/schemas/GenderEnum'
        dateOfBirth:
          type: string
          format: date
        countryOfBirth:
          type: string
          pattern: ^[A-Z]{3}$
        idNumber:
          type: string
        idType:
          type: string
        passportNumber:
          type: string
        accountNumber:
          type: string
        nationality:
          type: string
          pattern: ^[A-Za-z ]{2,60}$
        occupation:
          type: string
        phone:
          type: string
        email:
          type: string
          format: email
          example: abc@example.com
        address:
          $ref: '#/components/schemas/AddressInfo'
        countryCode:
          type: string
          pattern: ^[A-Z]{2}$
        companyName:
          type: string
        companyTradingName:
          type: string
        companyRegistrationNumber:
          type: string
        companyRegistrationCountry:
          type: string
    Beneficiary:
      type: object
      required:
        - firstName
        - lastName
      properties:
        firstName:
          type: string
          minLength: 1
        middleName:
          type: string
          minLength: 1
        lastName:
          type: string
        lastName2:
          type: string
        gender:
          $ref: '#/components/schemas/GenderEnum'
        dateOfBirth:
          type: string
          format: date
        countryOfBirth:
          type: string
        stateOfBirth:
          type: string
        phone:
          type: string
        mailAddress:
          type: string
        countryCode:
          type: string
          pattern: ^[A-Z]{2}$
        email:
          type: string
          format: email
          example: abc@example.com
        address:
          $ref: '#/components/schemas/AddressInfo'
        accountName:
          type: string
        accountNumber:
          type: string
        accountType:
          type: string
        transferNumber:
          type: string
        idNumber:
          type: string
        idType:
          type: string
        idIssueState:
          type: string
        idIssueCountry:
          type: string
        pixType:
          type: string
        pixKey:
          type: string
          minLength: 1
          maxLength: 100
        taxId:
          type: string
          minLength: 1
          maxLength: 100
        idExpiryDate:
          type: string
          format: date
        idIssueDate:
          type: string
          format: date
        passportNumber:
          type: string
        nationality:
          type: string
          pattern: ^[A-Za-z ]{2,60}$
        type:
          type: string
        residencyType:
          type: string
        occupation:
          type: string
        companyName:
          type: string
        branchNumber:
          type: string
          minLength: 1
    SourceOfFundsEnum:
      type: string
      enum:
        - DONATIONS
        - LOTTERY
        - SALARY
        - FREELANCE_INCOME
        - RETIREMENT_FUND
        - PROPERTY_SALE
        - FOREX_GAINS
        - PENSION
        - FAMILY_INCOME
        - FINANCIAL_SUPPORT_FROM_SPOUSE
        - LOANS
        - BUSINESS_INCOME
        - COMMISSION
        - PROPERTY_INVESTMENT
        - SHARES_INVESTMENT
        - SAVINGS
        - BALANCE_FROM_TRAVELLING
    PurposeEnum:
      type: string
      enum:
        - CONSTRUCTION
        - SERVICES_PAYMENT
        - EDUCATION
        - MEDICAL
        - FAMILY_MAINTENANCE
        - PROPERTY_PURCHASE
        - UTILITIES
        - PERSONAL_EXPENSES
        - INVESTMENT_GAINS
        - SAVINGS
        - SALARY
        - LEGAL_SERVICES
        - GRANTS
        - GIFTS
        - DONATIONS
        - WEDDING
        - RELIGIOUS_EXPENSES
        - FREELANCE_PAYMENT
    RelationshipEnum:
      type: string
      enum:
        - FAMILY
        - BUSINESS_PARTNER
        - FRIEND
        - FRIENDS_FAMILY
        - EMPLOYEE
        - SELF
        - SIBLING
        - PARENT
        - SPOUSE
        - CHILDREN
        - SUPPLIER
        - NOT_RELATED
        - RELATIVE
        - IN_LAWS
        - SERVICE_PROVIDER
        - SPOUSE_EMPLOYEE
        - SPOUSE_EMPLOYEE_FAMILY
        - CHARITY_RECIPIENT
    ComplianceInfo:
      type: object
      properties:
        sourceOfFunds:
          $ref: '#/components/schemas/SourceOfFundsEnum'
        purpose:
          $ref: '#/components/schemas/PurposeEnum'
        other:
          type: string
        relationship:
          $ref: '#/components/schemas/RelationshipEnum'
    PayoutResponse:
      type: object
      properties:
        payoutId:
          type: string
          description: >-
            Resource identification of the related payout initiation in UUID v04
            format.
        sourceMemberPayoutId:
          type: string
        payoutStatus:
          $ref: '#/components/schemas/PayoutStatusEnum'
        cashoutStatus:
          type: string
        rejectReason:
          type: string
        destinationCcy:
          type: string
        payoutAmt:
          type: number
        transferFee:
          type: number
        expiryTime:
          type: string
          format: date-time
        payoutProviderId:
          type: string
        segment:
          $ref: '#/components/schemas/SegmentEnum'
        payoutMethod:
          $ref: '#/components/schemas/PayoutMethodEnum'
        sender:
          $ref: '#/components/schemas/Sender'
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        complianceInfo:
          $ref: '#/components/schemas/ComplianceInfo'
        creationTime:
          type: string
          format: date-time
        initiateTime:
          type: string
          format: date-time
        completionTime:
          type: string
          format: date-time
        rejectionTime:
          type: string
          format: date-time
        cancellationTime:
          type: string
          format: date-time
    PayoutListResponse:
      type: object
      properties:
        payouts:
          type: array
          items:
            $ref: '#/components/schemas/PayoutResponse'
        page:
          type: integer
        size:
          type: integer
        totalPages:
          type: integer
        totalRecords:
          type: integer
          format: int64
    PayoutInitiateRequest:
      type: object
      required:
        - sender
        - beneficiary
        - payoutAmt
        - destinationCcy
        - sourceMemberPayoutId
        - payoutProviderId
      properties:
        sender:
          $ref: '#/components/schemas/Sender'
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        complianceInfo:
          $ref: '#/components/schemas/ComplianceInfo'
        sourceMemberPayoutId:
          type: string
          minLength: 1
          maxLength: 50
        destinationCcy:
          type: string
          pattern: ^[A-Z]{3}$
        payoutAmt:
          type: number
        payoutProviderId:
          type: string
          pattern: ^[A-Za-z0-9-_ ]*$
        payoutMethod:
          $ref: '#/components/schemas/PayoutMethodEnum'
        segment:
          $ref: '#/components/schemas/SegmentEnum'
    Links:
      type: object
      properties:
        process:
          type: string
          format: uri
          example: /v2/payouts/cc04ef71-085e-468e-87bd-2881d8a03a5d/process
          description: The link to process the payout created in initiation request.
        status:
          type: string
          format: uri
          example: /v2/payouts/cc04ef71-085e-468e-87bd-2881d8a03a5d/status
          description: The link to retrieve the status of the payout.
        details:
          type: string
          format: uri
          example: /v2/payouts/cc04ef71-085e-468e-87bd-2881d8a03a5d
          description: >-
            'The link to the payout initiation resource details created by this
            request.
    PayoutInitiateResponse:
      type: object
      properties:
        payoutId:
          type: string
          description: >-
            Resource identification of the related payout initiation in UUID v04
            format.
        sourceMemberPayoutId:
          type: string
        payoutStatus:
          $ref: '#/components/schemas/PayoutStatusEnum'
        destinationCcy:
          type: string
        payoutAmt:
          type: number
        transferFee:
          type: number
        expiryTime:
          type: string
          format: date-time
        beneficiaryName:
          type: string
        links:
          $ref: '#/components/schemas/Links'
    PayoutProcessResponse:
      type: object
      properties:
        payoutStatus:
          $ref: '#/components/schemas/PayoutStatusEnum'
        cashoutStatus:
          type: string
        rejectReason:
          type: string
    PayoutCancellationStatusEnum:
      type: string
      description: |2-
         ACCP: Accepted, 

         PNDG: Pending,

         PRCD: Processed,

         RJCT: Rejected
      enum:
        - ACCP
        - PNDG
        - PRCD
        - RJCT
    PayoutStatusResponse:
      type: object
      properties:
        payoutStatus:
          $ref: '#/components/schemas/PayoutStatusEnum'
        payoutCancellationStatus:
          $ref: '#/components/schemas/PayoutCancellationStatusEnum'
        cashoutStatus:
          type: string
        rejectReason:
          type: string
    PayoutCancellationRequest:
      type: object
      required:
        - cancellationReason
      properties:
        cancellationReason:
          type: string
          minLength: 1
          maxLength: 50
    PayoutCancellationResponse:
      type: object
      properties:
        payoutStatus:
          $ref: '#/components/schemas/PayoutStatusEnum'
        payoutCancellationStatus:
          $ref: '#/components/schemas/PayoutCancellationStatusEnum'
  parameters:
    Page:
      name: page
      schema:
        type: integer
        default: 0
      in: query
      required: false
      description: page number
    PageSize:
      name: size
      schema:
        type: integer
        default: 10
      in: query
      required: false
      description: page size. default is 10
    PayoutSortField:
      name: sortField
      schema:
        $ref: '#/components/schemas/PayoutSortEnum'
      in: query
      required: false
      description: Payout sort field
    SortDirection:
      name: sortDirection
      schema:
        $ref: '#/components/schemas/SortDirectionEnum'
      in: query
      required: false
      description: sort direction
    SourceMemberPayoutId:
      name: sourceMemberPayoutId
      schema:
        type: string
      in: query
      description: Filter by source member payout ID (your unique payout identifier)
    PayoutIdQuery:
      name: payoutId
      schema:
        type: string
      in: query
      required: false
      description: Filter by system payout ID (UUID format)
    CreationTime:
      name: creationTime
      schema:
        type: string
        format: date
      in: query
    CompletionTime:
      name: completionTime
      schema:
        type: string
        format: date
      in: query
    SenderName:
      name: senderName
      schema:
        type: string
      in: query
    SenderCountry:
      name: senderCountry
      schema:
        type: string
      in: query
    BeneficiaryName:
      name: beneficiaryName
      schema:
        type: string
      in: query
    BeneficiaryCountry:
      name: beneficiaryCountry
      schema:
        type: integer
      in: query
    PayoutProviderId:
      name: payoutProviderId
      schema:
        type: string
      in: query
    PayoutStatus:
      name: payoutStatus
      schema:
        type: string
      in: query
    PayoutId:
      name: payout-id
      schema:
        type: string
      in: path
      required: true
      description: >-
        Identification of payout created (resource identification of the
        generated payout initiation resource).
