# List payouts

Returns payouts using the common payment response document, including payouts awaiting confirmation. Filter by funding account, `externalReference`, or status.

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/listPayouts

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

## GET /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

### query: accountId

```json
{
  "name": "accountId",
  "in": "query",
  "description": "Filter by funding account identifier.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### query: externalReference

```json
{
  "name": "externalReference",
  "in": "query",
  "description": "Filter by the reference supplied when the payout was created.",
  "schema": {
    "type": "string"
  }
}
```

### query: status

```json
{
  "name": "status",
  "in": "query",
  "description": "Filter by payout status.",
  "schema": {
    "$ref": "#/components/schemas/PaymentStatus"
  }
}
```

### 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"
    ]
  }
}
```

### query: first

```json
{
  "name": "first",
  "in": "query",
  "description": "Maximum number of items to return (page size).",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 20,
    "examples": [
      20
    ]
  }
}
```

### query: after

```json
{
  "name": "after",
  "in": "query",
  "description": "Cursor for the next page, from the previous response's pageInfo.endCursor.",
  "schema": {
    "type": "string",
    "examples": [
      "eyJvZmZzZXQiOjI1fQ=="
    ]
  }
}
```

## Responses

### 200

```json
{
  "description": "Payout page",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "nodes",
          "pageInfo"
        ],
        "properties": {
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payment"
            }
          },
          "pageInfo": {
            "$ref": "#/components/schemas/PageInfo"
          }
        }
      }
    }
  }
}
```

### 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"
        ]
      }
    }
  }
}
```

### 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": "listPayouts",
  "x-axiym-navigation-order": 10
}
```

## Referenced schemas

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

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