# Create a payout

Creates a payout using Axiym field names and exact controlled-value codes. Non-canonical labels are rejected. To use your own field structure or value labels, store a Payment Data Map and use POST /payouts/mapped.

Axiym validates corridor availability, amount limits, and payment requirements, applies any documented deterministic formatting rules, and calculates commercial terms.

Creation returns the prepared instruction and commercial terms in PENDING_CONFIRMATION. It does not reserve funds or start processing. Review the returned document, then confirm it before termsExpireAt.

Product: Payment API
API reference version: 0.1.0 (current)
OpenAPI contract: https://docs.axiym.io/openapi/payment-api/0.1.0.yaml
Canonical page: https://docs.axiym.io/payment-api/api-reference/0.1.0/payouts/createPayout

[Complete reference with related definitions](/payment-api/api-reference/0.1.0/payouts/createPayout.full.md)

## POST /payouts

## Servers

```json
[
  {
    "url": "https://partner-api.sandbox.axiym.io/api/v1",
    "description": "Sandbox"
  },
  {
    "url": "https://partner-api.axiym.io/api/v1",
    "description": "Production"
  }
]
```

## Authentication

```json
{
  "security": [
    {
      "Default": []
    }
  ],
  "securitySchemes": {
    "Default": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
}
```

## Parameters

### header: X-Request-Id

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional request identifier for tracing and support. A UUID is recommended. Axiym echoes it in `X-Request-Id`, or generates one when omitted.",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

### header: Idempotency-Key

```json
{
  "name": "Idempotency-Key",
  "in": "header",
  "required": true,
  "description": "Identifies one state-changing operation. Retry with the same endpoint, request body, and key to receive the original result without repeating the operation. Use a new key for a new operation, including confirmation after creation.",
  "schema": {
    "type": "string",
    "maxLength": 255,
    "examples": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }
}
```

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PayoutRequest"
      }
    }
  }
}
```

## Responses

### 201

```json
{
  "description": "Payout created with status PENDING_CONFIRMATION and commercial terms valid until termsExpireAt.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Payment"
      }
    }
  }
}
```

### 400

```json
{
  "description": "Malformed or invalid request.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            },
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Malformed JSON body": {
          "summary": "Malformed JSON body",
          "value": {
            "code": 400,
            "message": "Bad Request",
            "errors": {
              "message": "Failed to parse the request body as JSON: expected value at line 1 column 5"
            }
          }
        },
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 400,
            "message": "Invalid cursor",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 401

```json
{
  "description": "Missing, expired, or invalid credentials.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 403

```json
{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 404

```json
{
  "description": "Resource not found or not accessible to this integration.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the missing or inaccessible resource."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 422

```json
{
  "description": "The request failed validation or a business rule. Validation failures return `errors` keyed by request field. Business rejections return `errors: null` and explain the reason in `message`.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "`Invalid Parameters` for validation failures; the rejection reason otherwise."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "For validation failures, keys follow the request fields and values contain field errors or nested errors. Business rejections return `null`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ValidationFieldErrors"
            }
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Flat field errors": {
          "summary": "Flat field errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "amount": [
                {
                  "code": "length",
                  "message": null,
                  "params": {
                    "value": "",
                    "min": 1
                  }
                }
              ],
              "recipient": {
                "destination": {
                  "currency": [
                    {
                      "code": "invalid_currency",
                      "message": null,
                      "params": {
                        "value": "ZZZ"
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "Nested struct errors": {
          "summary": "Nested struct errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "sender": {
                "address": {
                  "country": [
                    {
                      "code": "invalid_country",
                      "message": null,
                      "params": {
                        "value": "INVALID"
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "List item errors": {
          "summary": "List item errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "sender": {
                "relationships": {
                  "0": {
                    "firstName": [
                      {
                        "code": "length",
                        "message": null,
                        "params": {
                          "value": "",
                          "min": 1
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "Business rejection": {
          "summary": "Business rejection",
          "value": {
            "code": 422,
            "message": "Documents Not Accepted",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 500

```json
{
  "description": "Unexpected server error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

## Operation metadata

```json
{
  "tags": [
    "Payouts"
  ],
  "operationId": "createPayout",
  "x-axiym-navigation-order": 20
}
```

## Referenced schemas

Fetch the relevant schema to inspect its fields, constraints and related types.

- [`#/components/schemas/PayoutRequest`](/payment-api/api-reference/0.1.0/schemas/PayoutRequest.md)
- [`#/components/schemas/Payment`](/payment-api/api-reference/0.1.0/schemas/Payment.md)
- [`#/components/schemas/ValidationFieldErrors`](/payment-api/api-reference/0.1.0/schemas/ValidationFieldErrors.md)