---
updatedAt: 2026-08-04T12:00:15.000Z
agentTools:
  projectIndex: https://docs.mesta.xyz/llms.txt
---

# Create Internal Transfer

Creates an internal transfer that moves funds between two verified senders belonging to your merchant account. Only enabled for select merchants and use cases, on request — contact our support team to discuss enabling it.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Mesta API",
    "version": "2.0.0",
    "description": "API for cross-border payments and order management."
  },
  "servers": [
    {
      "url": "https://api.stg.mesta.xyz"
    }
  ],
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "description": "Error details",
            "properties": {
              "CODE": {
                "type": "string",
                "description": "Machine-readable error code",
                "example": "INVALID_TOKEN"
              },
              "MESSAGE": {
                "type": "string",
                "description": "Human-readable error message",
                "example": "The token provided is invalid"
              },
              "DETAILS": {
                "type": "array",
                "description": "Additional error details for validation errors",
                "items": {
                  "type": "string"
                },
                "nullable": true
              }
            },
            "required": [
              "CODE",
              "MESSAGE"
            ]
          },
          "requestId": {
            "type": "integer",
            "description": "Unique request identifier for debugging",
            "example": 177021679
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API Key for authentication"
      },
      "apiSecretAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-secret",
        "description": "API Secret for authentication"
      }
    }
  },
  "paths": {
    "/v1/transfers": {
      "post": {
        "x-readme": {
          "code-samples": [
            {
              "language": "node",
              "name": "TypeScript SDK",
              "install": "npm install @mestafi/sdk",
              "code": "import { MestaClient } from \"@mestafi/sdk\";\n\nconst client = new MestaClient({ apiKey: \"YOUR_API_KEY\", apiSecret: \"YOUR_API_SECRET\" });\n\nawait client.transfers.create({\n    senderId: \"877157e3-5433-4a17-b89e-92bb2709fc44\",\n    beneficiarySenderId: \"3f1f8dcb-42a5-4c46-a41b-2f7f2f6a9f10\",\n    acceptedQuoteId: \"ad0d23ef-8482-47a1-bb08-d2556f4347e5\"\n});\n"
            },
            {
              "language": "python",
              "name": "Python SDK",
              "install": "pip install mesta",
              "code": "from mesta import Mesta\n\nclient = Mesta(\n    api_key=\"YOUR_API_KEY\",\n    api_secret=\"YOUR_API_SECRET\",\n)\n\nclient.transfers.create(\n    sender_id=\"877157e3-5433-4a17-b89e-92bb2709fc44\",\n    beneficiary_sender_id=\"3f1f8dcb-42a5-4c46-a41b-2f7f2f6a9f10\",\n    accepted_quote_id=\"ad0d23ef-8482-47a1-bb08-d2556f4347e5\",\n)\n"
            }
          ]
        },
        "tags": [
          "Internal Transfer API"
        ],
        "summary": "Create Internal Transfer",
        "description": "Creates an internal transfer that moves funds between two verified senders belonging to your merchant account. Funds move on Mesta's internal ledger from the source sender's USD balance to the recipient sender's USD balance — no external payment rails are involved.\n\n> 🚧 Limited availability — enabled on request only\n>\n> Internal transfers are **not enabled by default**. This capability is only enabled for select merchants and approved use cases. To discuss enabling internal transfers for your account, please reach out to our [Support Team](mailto:support@mesta.xyz).\n\n**Flow**\n1. Create an internal quote via `POST /v1/quotes` with `transferType: \"internal\"`, `sourceCurrency: \"USD\"` and `targetCurrency: \"USD\"`.\n2. Call this endpoint with the quote id as `acceptedQuoteId` before the quote expires. A quote can fund at most one transfer.\n\nInternal transfers are order-backed: the response is a standard order with `transferType: \"internal\"`, the transfer appears in `GET /v1/orders` and `GET /v1/orders/{orderId}`, and it emits the standard order webhook events. The lifecycle is `created` → `funds_received` → `success`.\n\n**Requirements**\n- Both senders must belong to your merchant account and be verified and active.\n- Both senders must be enabled for internal transfers (USD).\n- The source sender's USD balance must cover the quote's gross source amount (amount + fees).\n- The source and recipient sender must be different (self-transfers are rejected).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "senderId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Identifier of the source sender whose USD balance funds the transfer",
                    "example": "877157e3-5433-4a17-b89e-92bb2709fc44"
                  },
                  "beneficiarySenderId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Identifier of the recipient sender. Must belong to the same merchant and be different from senderId",
                    "example": "3f1f8dcb-42a5-4c46-a41b-2f7f2f6a9f10"
                  },
                  "acceptedQuoteId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Identifier of the internal quote (created with transferType \"internal\") to execute. A quote can fund at most one transfer and must be used before it expires",
                    "example": "ad0d23ef-8482-47a1-bb08-d2556f4347e5"
                  }
                },
                "required": [
                  "senderId",
                  "beneficiarySenderId",
                  "acceptedQuoteId"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Internal transfer created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Unique identifier for the internal transfer (order id)",
                          "example": "258abf6a-5aee-4fb3-92ac-b93ca5a03c64"
                        },
                        "senderId": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Identifier of the source sender",
                          "example": "877157e3-5433-4a17-b89e-92bb2709fc44"
                        },
                        "beneficiarySenderId": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Identifier of the recipient sender",
                          "example": "3f1f8dcb-42a5-4c46-a41b-2f7f2f6a9f10"
                        },
                        "merchantId": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Identifier of the merchant",
                          "example": "ccfbddf1-009d-4b1c-aaa7-1f5eecc4398a"
                        },
                        "transferType": {
                          "type": "string",
                          "enum": [
                            "internal"
                          ],
                          "description": "Always `internal` for internal transfers",
                          "example": "internal"
                        },
                        "sourceCurrency": {
                          "type": "string",
                          "description": "Source currency code",
                          "example": "USD"
                        },
                        "targetCurrency": {
                          "type": "string",
                          "description": "Target currency code",
                          "example": "USD"
                        },
                        "acceptedGrossSourceAmount": {
                          "type": "string",
                          "description": "Amount debited from the source sender in source currency (including fees)",
                          "example": "100.00"
                        },
                        "targetAmount": {
                          "type": "string",
                          "description": "Amount credited to the recipient sender in target currency",
                          "example": "99.50"
                        },
                        "acceptedQuoteId": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Identifier of the accepted internal quote",
                          "example": "ad0d23ef-8482-47a1-bb08-d2556f4347e5"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "created",
                            "funds_received",
                            "in_progress",
                            "success",
                            "failed"
                          ],
                          "description": "Current status of the internal transfer. `created` on creation, `funds_received` once the source sender is debited, `success` once the recipient sender is credited.",
                          "example": "created"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Timestamp when the transfer was created",
                          "example": "2026-08-04T05:06:17.516Z"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Timestamp when the transfer was last updated",
                          "example": "2026-08-04T05:06:17.516Z"
                        }
                      }
                    },
                    "requestId": {
                      "type": "integer",
                      "description": "Unique identifier for the API request",
                      "example": 106597
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - The request was invalid or cannot be served.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - The request requires user authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - The server understood the request, but refuses to authorize it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found - The requested resource could not be found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error - The server encountered an unexpected condition.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "operationId": "post_v1-transfers"
      }
    }
  },
  "security": [
    {
      "apiKeyAuth": [],
      "apiSecretAuth": []
    }
  ],
  "x-readme": {
    "samples-languages": [
      "node",
      "python",
      "shell"
    ],
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  }
}
```