Outpost Payments API

openapi: 3.2.0
info:
  title: Outpost Ai Payments API
  version: 0.1.0
  description: 'Operations tagged Payments across 2 of this provider''s published API definitions: outpost-ai-stripe-mor.yaml, stripe-billing-mor.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.outpostanywhere.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Payments
  description: 'Payment lifecycle operations — provisioning a SetupIntent at signup,

    confirming the payment after card collection, and refunding in full or

    in part.'
paths:
  /api/payments/stripe/setup-intents:
    post:
      tags:
      - Payments
      summary: Create a SetupIntent for payment-method collection on Outpost
      description: 'Provisions a SetupIntent on Outpost''s PSP account with

        `usage=off_session`. The returned `client_secret` is passed to

        **Stripe Elements** in the browser so the customer can confirm payment

        details directly against Stripe — no sensitive payment data ever

        touches the merchant or Outpost servers.


        The set of payment methods offered to the customer is controlled by

        `payment_method_types` on the request body (defaults to `["card"]`).

        Currently supported: `card`, `us_bank_account`, `sepa_debit`,

        `bacs_debit`, `au_becs_debit`. Mandate text for direct-debit methods

        is rendered by Payment Element automatically.


        The PaymentMethod produced by `confirmSetup()` belongs to Outpost''s

        PSP account, **not** yours. Outpost is informed of the outcome via

        its own `setup_intent.succeeded` webhook and caches the

        PaymentMethod against `mor_customer_id` for renewals — no

        follow-up Outpost API call is required from the merchant.'
      operationId: createSetupIntent
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetupIntentRequest'
            example:
              payment_method_types:
              - card
              tax_calculation_id: taxc_a1b2c3d4e5f6789
      responses:
        '200':
          description: SetupIntent created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupIntentResponse'
              example:
                client_secret: seti_1QwxyzABC_secret_xyzXYZ123
                setup_intent_id: seti_1QwxyzABC
                mor_customer_id: cus_a1b2c3d4e5f6789
                status: requires_payment_method
        '400':
          description: Malformed body, or invalid value in `payment_method_types`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'Merchant account is suspended, or the token lacks the required

            scope.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The `tax_calculation_id` does not resolve to a known calculation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Same `Idempotency-Key` replayed with a different request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'A `payment_method_types` value is not enabled for your account on

            Outpost''s PSP.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Burst exceeded your quota. Retry after backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'Upstream PSP (Stripe) returned 5xx or timed out. Safe to retry

            with the same `Idempotency-Key`.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.outpostanywhere.com
      description: Production
  /api/payments/stripe/payment-intents:
    post:
      tags:
      - Payments
      summary: Create a PaymentIntent for immediate-payment signup
      description: 'Used for the **immediate-payment signup variant** — the customer is

        charged at signup (no free trial). Provisions a PaymentIntent on

        Outpost''s PSP account with `setup_future_usage=off_session` so the

        same card can be charged off-session for future renewals.


        The browser confirms with `stripe.confirmPayment()` (atomic card

        collection, 3DS, and charge). Outpost learns the outcome via its own

        `payment_intent.succeeded` webhook — no follow-up Outpost API call is

        required from the merchant.


        Works for any Stripe payment method that supports off-session reuse —

        cards, `us_bank_account`, `sepa_debit`, `bacs_debit`, `au_becs_debit`.

        Async-settled methods first transition through `processing` and only

        reach `succeeded` after settlement (days later).'
      operationId: createPaymentIntent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
            example:
              amount: 1990
              currency: BRL
              merchant_customer:
                stripe_id: cus_QmerchantSide
                email: jordi@example.com.br
                name: Jordi Silva
                country: BR
                address:
                  line1: Av. Paulista 1234
                  city: São Paulo
              description: Pro Monthly subscription — first payment
              tax_calculation_id: taxc_a1b2c3d4e5f6789
      responses:
        '200':
          description: PaymentIntent created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentIntentResponse'
              example:
                client_secret: pi_3QzABC_secret_xyzXYZ123
                payment_intent_id: pi_3QzABC
                mor_customer_id: cus_a1b2c3d4e5f6789
                status: requires_payment_method
        '400':
          description: Missing or malformed amount / currency / merchant_customer.stripe_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'Merchant account is suspended, or the token lacks the required

            scope.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The `tax_calculation_id` does not resolve to a known calculation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Same `Idempotency-Key` replayed with a different request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'Currency not enabled on Outpost''s PSP, amount below the PSP''s

            minimum, or amount above your per-transaction cap.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Burst exceeded your quota. Retry after backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'Upstream PSP (Stripe) returned 5xx or timed out. Safe to retry

            with the same `Idempotency-Key`.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.outpostanywhere.com
      description: Production
  /api/payments/{paymentId}/refund:
    post:
      tags:
      - Payments
      summary: Refund a previously confirmed payment
      description: 'Refunds a payment in full or in part. Outpost executes the refund on

        its PSP account and emits a `payment.refunded` webhook so you can

        update the corresponding PaymentRecord on Stripe.


        Partial refunds are supported — supply `amount` to refund less than

        the full charge. Multiple refunds are allowed until the cumulative

        amount equals the original payment.


        **Idempotency:** the `Idempotency-Key` header is required.'
      operationId: refundPayment
      parameters:
      - name: paymentId
        in: path
        required: true
        description: 'Outpost-owned payment identifier. For renewal payments this is the

          `payment_id` delivered on the `payment.succeeded` webhook. (Refunds

          on signup-time charges are tracked separately through the merchant

          payment record.)

          '
        schema:
          type: string
          examples:
          - pay_a1b2c3d4e5f6789
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
            example:
              amount: 990
              reason: requested_by_customer
              metadata:
                merchant_invoice_id: in_1QzABC
      responses:
        '200':
          description: Refund attempted. Inspect `status` for the outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
              example:
                id: rfnd_a1b2c3d4e5f6789
                payment_id: pay_a1b2c3d4e5f6789
                amount: 990
                currency: BRL
                status: succeeded
                reason: requested_by_customer
                processor_references:
                  refund_id: re_3QzABC...
                created_at: '2026-05-12T11:00:00Z'
        '400':
          description: amount exceeds the unrefunded remainder, or currency mismatch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No payment exists for the given paymentId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'Payment is not in a refundable state (already fully refunded,

            never succeeded, or charged back).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.outpostanywhere.com
      description: Production
components:
  schemas:
    RefundResponse:
      type: object
      required:
      - id
      - payment_id
      - amount
      - currency
      - status
      - processor_references
      - created_at
      properties:
        id:
          type: string
          description: Outpost-owned refund identifier.
          examples:
          - rfnd_a1b2c3d4e5f6789
        payment_id:
          type: string
          description: The payment this refund applies to.
          examples:
          - pay_a1b2c3d4e5f6789
        amount:
          type: integer
        currency:
          type: string
        status:
          type: string
          description: 'For cards and Link this is synchronous; for bank debits the refund

            starts as `pending` and transitions via the `payment.refunded`

            webhook.

            '
          enum:
          - succeeded
          - pending
          - failed
        reason:
          type: string
          nullable: true
        processor_references:
          type: object
          properties:
            refund_id:
              type: string
              description: Refund ID on Outpost's PSP account.
              examples:
              - re_3QzABC
        created_at:
          type: string
          format: date-time
    PaymentIntentRequest:
      type: object
      required:
      - amount
      - currency
      - merchant_customer
      properties:
        amount:
          type: integer
          description: Smallest currency unit (e.g. cents for USD, centavos for BRL).
          minimum: 1
        currency:
          type: string
          minLength: 3
          maxLength: 3
          examples:
          - BRL
        merchant_customer:
          $ref: '#/components/schemas/MerchantCustomer'
        description:
          type: string
          description: Free-form description shown on the underlying PaymentIntent.
          maxLength: 255
        tax_calculation_id:
          type: string
          description: 'Reference to a tax calculation returned by

            `POST /api/tax/calculate`. Binds the calculated tax breakdown to

            this payment.

            '
          examples:
          - taxc_a1b2c3d4e5f6789
    SetupIntentRequest:
      type: object
      description: 'Optional configuration for the SetupIntent Outpost provisions on its

        PSP account. Defaults to a card-only, off-session SetupIntent if

        the body is empty.

        '
      properties:
        payment_method_types:
          type: array
          description: 'Stripe payment-method types to enable on the SetupIntent.

            Defaults to `["card"]`. Supported values: `card`,

            `us_bank_account`, `sepa_debit`, `bacs_debit`, `au_becs_debit`.

            Mandate text for direct-debit methods is rendered automatically

            by Payment Element.

            '
          items:
            type: string
            enum:
            - card
            - us_bank_account
            - sepa_debit
            - bacs_debit
            - au_becs_debit
          examples:
          - - card
        tax_calculation_id:
          type: string
          description: 'Reference to a tax calculation returned by

            `POST /api/tax/calculate`. Binds the tax breakdown to this

            SetupIntent so it carries through to the first chargeable invoice

            (e.g. at trial end).

            '
          examples:
          - taxc_a1b2c3d4e5f6789
      additionalProperties: true
    PaymentIntentResponse:
      type: object
      required:
      - client_secret
      - payment_intent_id
      - mor_customer_id
      - status
      properties:
        client_secret:
          type: string
          description: 'Pass to Stripe Elements via

            `loadStripe(OUTPOST_PUBLISHABLE_KEY)` and confirm with

            `stripe.confirmPayment({ clientSecret, … })`.

            '
          examples:
          - pi_3QzABC_secret_xyzXYZ123
        payment_intent_id:
          type: string
          description: PaymentIntent ID on Outpost's PSP account.
          examples:
          - pi_3QzABC
        mor_customer_id:
          type: string
          description: 'Outpost''s Stripe Customer ID (empty Customer with metadata

            pointing back at your `merchant_customer.stripe_id`). Persist for

            future reference.

            '
          examples:
          - cus_a1b2c3d4e5f6789
        status:
          type: string
          description: 'PaymentIntent status — typically `requires_payment_method` at

            this point; the browser transitions it via `confirmPayment()`.

            '
          enum:
          - requires_payment_method
          - requires_confirmation
          - requires_action
          - processing
          - succeeded
    SetupIntentResponse:
      type: object
      required:
      - client_secret
      - setup_intent_id
      - mor_customer_id
      - status
      properties:
        client_secret:
          type: string
          description: 'Pass to Stripe Elements via

            `loadStripe(OUTPOST_PUBLISHABLE_KEY)` and confirm with

            `stripe.confirmSetup({ clientSecret, … })`.

            '
          examples:
          - seti_1QwxyzABC_secret_xyzXYZ123
        setup_intent_id:
          type: string
          description: SetupIntent ID on Outpost's PSP account.
          examples:
          - seti_1QwxyzABC
        mor_customer_id:
          type: string
          description: 'Outpost''s Stripe Customer ID (empty Customer with metadata

            pointing back at your `merchant_customer.stripe_id`). Persist for

            future reference.

            '
          examples:
          - cus_a1b2c3d4e5f6789
        status:
          type: string
          enum:
          - requires_payment_method
          - requires_confirmation
          - requires_action
          - processing
          - succeeded
    MerchantCustomer:
      type: object
      description: 'Pointer to the Customer record on **your own Stripe account**.

        Outpost stores this on its empty MoR-side Customer as metadata so the

        renewal flow can map `invoice.created.customer` → saved PaymentMethod.

        '
      required:
      - stripe_id
      properties:
        stripe_id:
          type: string
          description: Customer ID on your Stripe account.
          examples:
          - cus_QmerchantSide
        email:
          type: string
          description: Customer email. Used for receipt routing and fraud signals.
        name:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
        address:
          type: object
          description: Billing address (line1, city, postal_code, etc.).
          additionalProperties: true
    RefundRequest:
      type: object
      description: 'Optional body for `POST /api/payments/{paymentId}/refund`. Omit for a

        full refund of the unrefunded remainder.

        '
      properties:
        amount:
          type: integer
          minimum: 1
          description: 'Smallest currency unit. Defaults to the unrefunded remainder of

            the payment (full refund). Must be ≤ remaining refundable amount.

            '
          examples:
          - 990
        reason:
          type: string
          description: 'One of `requested_by_customer`, `duplicate`, `fraudulent`.

            Free-form strings are also accepted and forwarded to the PSP.

            '
          examples:
          - requested_by_customer
        metadata:
          type: object
          additionalProperties:
            type: string
          description: 'Arbitrary key/value pairs persisted on the refund and forwarded to

            the PSP refund object.

            '
    Error:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          examples:
          - invalid_request
        message:
          type: string
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: 'Required for `POST /api/payments/{paymentId}/refund`. Outpost derives

        downstream PSP idempotency keys from this value, so retries with the

        same key are safe. Idempotency on `POST /api/payments/stripe/setup-intents`

        and `POST /api/payments/stripe/payment-intents` is also supported but

        optional.

        '
      schema:
        type: string
        maxLength: 255
        examples:
        - signup_charge_a1b2c3d4
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Obtain via `POST /oauth/token` with the `client_credentials` grant.

        Send as `Authorization: Bearer <access_token>` on every Outpost API

        endpoint.

        '
x-refined-from:
- outpost-ai-stripe-mor.yaml
- stripe-billing-mor.yaml