Create

POST/payment-flows

Creates a new payment flow.

Body ParametersJSONExpand Collapse

external_id: string

User-provided unique external ID.

invoice: object { id } or object { external_id }

Invoice to settle.

Accepts one of the following:

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.

ReturnsExpand Collapse

data: PaymentFlow { 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.

Create

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"
        }'

{
  "data": {
    "id": "pf_abc123",
    "created": "2024-01-01T00:00:00.000Z",
    "external_id": "pf_123",
    "invoice": {
      "id": "inv_abc123",
      "external_id": "inv_ext_123"
    },
    "modified": "2024-01-01T00:00:00.000Z",
    "payment_plan": {
      "batches": [
        {
          "batch_id": "payins",
          "depends_on": [
            "string"
          ],
          "label": "Payins",
          "payments": [
            {
              "amount": "10000",
              "currency": "USD",
              "direction": "payin",
              "payment_id": "pmt_abc123",
              "status": "settled",
              "user": {
                "id": "user_abc123",
                "external_id": "user_ext_001"
              }
            }
          ],
          "status": "settled"
        }
      ],
      "generated_at": "2024-01-01T00:00:00.000Z",
      "invoice_id": "inv_abc123",
      "version": 1
    },
    "status": "settled",
    "type": "single_invoice_settlement"
  }
}

Returns Examples

{
  "data": {
    "id": "pf_abc123",
    "created": "2024-01-01T00:00:00.000Z",
    "external_id": "pf_123",
    "invoice": {
      "id": "inv_abc123",
      "external_id": "inv_ext_123"
    },
    "modified": "2024-01-01T00:00:00.000Z",
    "payment_plan": {
      "batches": [
        {
          "batch_id": "payins",
          "depends_on": [
            "string"
          ],
          "label": "Payins",
          "payments": [
            {
              "amount": "10000",
              "currency": "USD",
              "direction": "payin",
              "payment_id": "pmt_abc123",
              "status": "settled",
              "user": {
                "id": "user_abc123",
                "external_id": "user_ext_001"
              }
            }
          ],
          "status": "settled"
        }
      ],
      "generated_at": "2024-01-01T00:00:00.000Z",
      "invoice_id": "inv_abc123",
      "version": 1
    },
    "status": "settled",
    "type": "single_invoice_settlement"
  }
}