# Payment Flows

## Create

**post** `/payment-flows`

Creates a new payment flow.

### Body Parameters

- `external_id: string`

  User-provided unique external ID.

- `invoice: object { id }  or object { external_id }`

  Invoice to settle.

  - `ID = object { id }`

    - `id: string`

      Fragment invoice ID.

  - `ExternalID = object { external_id }`

    - `external_id: string`

      Invoice external ID.

- `type: "single_invoice_settlement"`

  Type of payment flow.

  - `"single_invoice_settlement"`

### Returns

- `data: PaymentFlow`

  Payment flow object.

  - `id: string`

    FRAGMENT generated unique ID.

  - `created: string`

    Timestamp when the payment flow was created.

  - `external_id: string`

    User-provided unique external ID.

  - `invoice: object { id, external_id }`

    Invoice being settled.

    - `id: string`

      Invoice identifier.

    - `external_id: optional string`

      Invoice external ID.

  - `modified: string`

    Timestamp when the payment flow was last modified.

  - `payment_plan: object { batches, generated_at, invoice_id, version }`

    Payment plan for UI rendering.

    - `batches: array of object { batch_id, depends_on, label, 2 more }`

      Payment batches.

      - `batch_id: string`

        Batch identifier.

      - `depends_on: array of string`

        Batches this one depends on.

      - `label: string`

        Human-readable batch label.

      - `payments: array of object { amount, currency, direction, 3 more }`

        Payments in this batch.

        - `amount: string`

          Amount in smallest currency unit.

        - `currency: string`

          Currency code.

        - `direction: string`

          Direction of the payment.

        - `payment_id: string`

          FRAGMENT generated unique ID.

        - `status: string`

          Status of the payment.

        - `user: object { id, external_id }`

          User associated with the payment.

          - `id: string`

            FRAGMENT generated unique ID.

          - `external_id: string`

            User-provided unique ID.

      - `status: string`

        Batch status.

    - `generated_at: string`

      When the plan was generated.

    - `invoice_id: string`

      Invoice identifier.

    - `version: number`

      Plan version.

  - `status: string`

    Status of the payment flow.

  - `type: string`

    Type of payment flow.

### Example

```http
curl https://api.us-west-2.fragment.dev/billing/payment-flows \
    -H 'Content-Type: application/json' \
    -d '{
          "external_id": "pf_123",
          "invoice": {
            "id": "inv_abc123"
          },
          "type": "single_invoice_settlement"
        }'
```

## Retrieve

**get** `/payment-flows/{payment_flow_ref}`

Gets a payment flow by ID or external ID.

### Path Parameters

- `payment_flow_ref: string`

  Payment flow ID or external ID.

### Returns

- `data: PaymentFlow`

  Payment flow object.

  - `id: string`

    FRAGMENT generated unique ID.

  - `created: string`

    Timestamp when the payment flow was created.

  - `external_id: string`

    User-provided unique external ID.

  - `invoice: object { id, external_id }`

    Invoice being settled.

    - `id: string`

      Invoice identifier.

    - `external_id: optional string`

      Invoice external ID.

  - `modified: string`

    Timestamp when the payment flow was last modified.

  - `payment_plan: object { batches, generated_at, invoice_id, version }`

    Payment plan for UI rendering.

    - `batches: array of object { batch_id, depends_on, label, 2 more }`

      Payment batches.

      - `batch_id: string`

        Batch identifier.

      - `depends_on: array of string`

        Batches this one depends on.

      - `label: string`

        Human-readable batch label.

      - `payments: array of object { amount, currency, direction, 3 more }`

        Payments in this batch.

        - `amount: string`

          Amount in smallest currency unit.

        - `currency: string`

          Currency code.

        - `direction: string`

          Direction of the payment.

        - `payment_id: string`

          FRAGMENT generated unique ID.

        - `status: string`

          Status of the payment.

        - `user: object { id, external_id }`

          User associated with the payment.

          - `id: string`

            FRAGMENT generated unique ID.

          - `external_id: string`

            User-provided unique ID.

      - `status: string`

        Batch status.

    - `generated_at: string`

      When the plan was generated.

    - `invoice_id: string`

      Invoice identifier.

    - `version: number`

      Plan version.

  - `status: string`

    Status of the payment flow.

  - `type: string`

    Type of payment flow.

### Example

```http
curl https://api.us-west-2.fragment.dev/billing/payment-flows/$PAYMENT_FLOW_REF
```

## Search

**post** `/payment-flows/search`

Searches payment flows.

### Body Parameters

- `invoice_id: optional string`

  Filter by invoice ID.

- `page_info: optional object { after, limit }`

  Pagination parameters.

  - `after: optional string`

    Pagination cursor.

  - `limit: optional number`

    Maximum number of results.

### Returns

- `data: array of PaymentFlow`

  - `id: string`

    FRAGMENT generated unique ID.

  - `created: string`

    Timestamp when the payment flow was created.

  - `external_id: string`

    User-provided unique external ID.

  - `invoice: object { id, external_id }`

    Invoice being settled.

    - `id: string`

      Invoice identifier.

    - `external_id: optional string`

      Invoice external ID.

  - `modified: string`

    Timestamp when the payment flow was last modified.

  - `payment_plan: object { batches, generated_at, invoice_id, version }`

    Payment plan for UI rendering.

    - `batches: array of object { batch_id, depends_on, label, 2 more }`

      Payment batches.

      - `batch_id: string`

        Batch identifier.

      - `depends_on: array of string`

        Batches this one depends on.

      - `label: string`

        Human-readable batch label.

      - `payments: array of object { amount, currency, direction, 3 more }`

        Payments in this batch.

        - `amount: string`

          Amount in smallest currency unit.

        - `currency: string`

          Currency code.

        - `direction: string`

          Direction of the payment.

        - `payment_id: string`

          FRAGMENT generated unique ID.

        - `status: string`

          Status of the payment.

        - `user: object { id, external_id }`

          User associated with the payment.

          - `id: string`

            FRAGMENT generated unique ID.

          - `external_id: string`

            User-provided unique ID.

      - `status: string`

        Batch status.

    - `generated_at: string`

      When the plan was generated.

    - `invoice_id: string`

      Invoice identifier.

    - `version: number`

      Plan version.

  - `status: string`

    Status of the payment flow.

  - `type: string`

    Type of payment flow.

### Example

```http
curl https://api.us-west-2.fragment.dev/billing/payment-flows/search \
    -X POST
```

## Domain Types

### Payment Flow

- `PaymentFlow = object { id, created, external_id, 5 more }`

  Payment flow object.

  - `id: string`

    FRAGMENT generated unique ID.

  - `created: string`

    Timestamp when the payment flow was created.

  - `external_id: string`

    User-provided unique external ID.

  - `invoice: object { id, external_id }`

    Invoice being settled.

    - `id: string`

      Invoice identifier.

    - `external_id: optional string`

      Invoice external ID.

  - `modified: string`

    Timestamp when the payment flow was last modified.

  - `payment_plan: object { batches, generated_at, invoice_id, version }`

    Payment plan for UI rendering.

    - `batches: array of object { batch_id, depends_on, label, 2 more }`

      Payment batches.

      - `batch_id: string`

        Batch identifier.

      - `depends_on: array of string`

        Batches this one depends on.

      - `label: string`

        Human-readable batch label.

      - `payments: array of object { amount, currency, direction, 3 more }`

        Payments in this batch.

        - `amount: string`

          Amount in smallest currency unit.

        - `currency: string`

          Currency code.

        - `direction: string`

          Direction of the payment.

        - `payment_id: string`

          FRAGMENT generated unique ID.

        - `status: string`

          Status of the payment.

        - `user: object { id, external_id }`

          User associated with the payment.

          - `id: string`

            FRAGMENT generated unique ID.

          - `external_id: string`

            User-provided unique ID.

      - `status: string`

        Batch status.

    - `generated_at: string`

      When the plan was generated.

    - `invoice_id: string`

      Invoice identifier.

    - `version: number`

      Plan version.

  - `status: string`

    Status of the payment flow.

  - `type: string`

    Type of payment flow.