> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

# Request a Transfer

Enables marketplaces using Yuno Split Payments to request a transfer based on an existing payment. Request a transfer for a specified amount to one of the recipients participating in the split.


## OpenAPI

````yaml openapi/recipients-for-marketplace/request-a-transfer.json POST /payments/{payment_id}/transactions/{transaction_id}/split-marketplace/transfer-reversal
openapi: 3.1.0
info:
  title: Recipients API
  version: 1.0.0
  description: >-
    API for managing recipients in split payment scenarios. This feature enables
    merchants to split payments among multiple recipients, which is particularly
    beneficial for marketplace models where transactions need to be divided
    among different sellers or stakeholders.
servers:
  - url: https://api-sandbox.y.uno/v1
security:
  - sec0: []
    sec1: []
paths:
  /payments/{payment_id}/transactions/{transaction_id}/split-marketplace/transfer-reversal:
    post:
      operationId: >-
        post_payments-payment-id-transactions-transaction-id-split-marketplace-transfer-reversal
      parameters:
        - in: path
          name: payment_id
          schema:
            type: string
          required: true
          description: The unique identifier of the payment (MAX 64; MIN 36).
        - in: path
          name: transaction_id
          schema:
            type: string
          required: true
          description: The unique identifier of the transaction (MAX 64; MIN 36).
        - in: header
          name: X-Idempotency-Key
          schema:
            type: string
          description: >-
            Unique identifier used in HTTP headers to ensure that a request is
            processed only once, even if it is retried due to network issues or
            timeouts.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: object
                  properties:
                    currency:
                      type: string
                      description: >-
                        Currency of the transaction. Visit the [country
                        reference](/reference/country-reference) for the full
                        list of supported currencies.
                      default: ''
                    value:
                      type: number
                      description: The value amount of the transaction.
                      default: ''
                  description: The payment amount (multiple of 0.0001).
                  required:
                    - currency
                    - value
                description:
                  type: string
                  description: The unique identifier of the transaction (MAX 256; MIN 3).
                  default: ''
              required:
                - amount
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Success:
                  value:
                    id: 94036ceb-5cca-4384-b144-e2a5a908af77
                    recipient_id: e56c3329-f3d9-48e5-a677-284b147abf95
                    amount:
                      currency: USD
                      value: 100
                    status: SUCCEEDED
                    description: test transfer
                    merchant_reference: c19e858a-ffd6-4635-8a31-4f60c5becf4d
                    metadata: []
                    provider: null
                    transactions:
                      - code: 7ac2c5f3-7c79-4e99-b45e-aa5952620188
                        type: SPLIT_TRANSFER
                        status: SUCCEEDED
                        provider_transfer_id: tr_1T9eKVIiMnPsFcbbRTb8ObsZ
                        raw_response: |-
                          {
                            "id": "tr_1T9eKVIiMnPsFcbbRTb8ObsZ",
                            "object": "transfer",
                            "amount": 10000,
                            "amount_reversed": 0,
                            "balance_transaction": "txn_1T9eKVIiMnPsFcbbOPnvz3xM",
                            "created": 1773203107,
                            "currency": "usd",
                            "description": "test transfer",
                            "destination": "acct_1T9PSQIZEg1WWTvj",
                            "destination_payment": "py_1T9eKVIZEg1WWTvjbVjmnzFK",
                            "livemode": false,
                            "metadata": {},
                            "reversals": {
                              "object": "list",
                              "data": [],
                              "has_more": false,
                              "total_count": 0,
                              "url": "/v1/transfers/tr_1T9eKVIiMnPsFcbbRTb8ObsZ/reversals"
                            },
                            "reversed": false,
                            "source_transaction": null,
                            "source_type": "card",
                            "transfer_group": null
                          }
                        created_at: '2026-03-11T04:25:06.229027Z'
                        updated_at: '2026-03-11T04:25:07.917364Z'
                    created_at: '2026-03-11T04:25:06.208761Z'
                    updated_at: '2026-03-11T04:25:07.928000342Z'
                    completed_at: '2026-03-11T04:25:07.927971142Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Transfer Error:
                  value:
                    id: 9778f631-504d-448f-b2c1-f7b903781df7
                    recipient_id: 82b12c8c-7d3d-4a21-a3c6-165cc04ca741
                    amount:
                      currency: USD
                      value: 50000
                    status: ERROR
                    description: test transfer
                    merchant_reference: cb18df20-21ae-4fed-8da9-fb81cfd56797
                    metadata: []
                    provider: null
                    transactions:
                      - code: 9eee65d1-6c3a-4076-9ef9-fa4bff73d597
                        type: SPLIT_TRANSFER
                        status: ERROR
                        provider_transfer_id: tr_1T9PTLIiMnPsFcbbFKyh1Nds
                        provider_response_message: |-
                          {
                            "id": "tr_1T9PTLIiMnPsFcbbFKyh1Nds",
                            "object": "transfer",
                            "amount": 10000,
                            "amount_reversed": 0,
                            "balance_transaction": "txn_1T9PTMIiMnPsFcbbxRKvaZ3G",
                            "created": 1773145996,
                            "currency": "usd",
                            "description": "test transfer"
                          }
                        provider_raw_response: '{.... }'
                        created_at: '2026-03-10T13:39:19.342902Z'
                        updated_at: '2026-03-10T13:39:19.342914Z'
                    created_at: '2026-03-10T13:39:19.241990247Z'
                    updated_at: '2026-03-10T13:39:19.242012664Z'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: INVALID_REQUEST
        messages:
          type: array
          items:
            type: string
            example: Invalid request
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````