# Create a forward payment

Trigger a forward payment against an advanced invoice.

Use this endpoint when the customer has already paid you outside Resolve and you want Resolve to
collect its portion from the forwarded amount.

Endpoint: POST /payments
Version: V5
Security: bearerAuth, basicAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer JWT

  - `basicAuth` (unknown)
    http basic

## Request body:

  - `application/json` (unknown)
    Create a forward payment against an advanced invoice.

Send this request when a customer has already paid you outside Resolve and you need to
forward the payment to Resolve.

## Request fields (application/json):

  - `invoice_id` (string, required)
    ID of the advanced invoice to forward payment against.
    Example: PMMlaE5wbg0

  - `amount` (number, required)
    Amount to forward in USD.
    Example: 500

  - `forward_reason_code` (string, required)
    Reason code for the forward payment.

This is the field that triggers the forward-payment flow.
    Enum: "ach", "check", "wire", "credit_card", "other"

  - `forward_reason_message` (string)
    Required when `forward_reason_code` is `other`.
    Example: Customer paid by wire transfer outside Resolve.

## Response 200:

  - `200` (unknown)
    An object representing a payment.

## Response 200 fields (application/json):

  - `id` (string)
    Unique identifier for the payment.
    Example: PMMlaE5wbg0

  - `customer_id` (string)
    Unique identifier of the customer that made the payment.
    Example: X50sgfRd

  - `source` (string)
    Source of the payment.
    Enum: "api", "merchant_user", "admin_user", "customer_user", "payment_gateway", "check", "guest_checkout"

  - `amount` (number)
    Amount of the payment in USD.
    Example: 1000

  - `method` (string)
    Method of payment made by the customer.
    Enum: "check", "ach_debit", "direct_deposit", "card", "merchant", "unapplied_payment_adjustment", "credit_note", "adjustment", "wire"

  - `status` (string)
    Status of the payment.
- `pending` - Payment is pending processing.
- `in_transit` - Payment has been processed and is in transit.
- `in_review` - Payment is being reviewed.
- `paid` - Payment has been confirmed and applied to the customer's account.
- `failed` - Payment failed confirmation (e.g., bank transfer or credit card payment rejected).
- `canceled` - Payment was canceled by request.
    Enum: "pending", "in_transit", "in_review", "paid", "failed", "canceled"

  - `created_at` (string)
    Date the payment was created.
    Example: 2020-01-01T00:00:00.730Z

  - `paid_at` (string)
    Date the payment was confirmed by Resolve and applied to the customer's account.
    Example: 2020-01-02T00:00:00.730Z

  - `canceled_at` (string)
    Date the payment was canceled by request.
    Example: null

  - `failed_at` (string)
    Date the payment failed processing.
    Example: null

  - `processed_at` (string)
    Date the payment was processed by Resolve.
    Example: 2020-01-01T12:00:00.730Z

  - `scheduled_at` (string)
    Date the payment was scheduled for processing, if applicable.
    Example: null

  - `processing_fee` (number)
    Processing fee for the payment.
    Example: 25.5

  - `canceled_code` (string)
    Code indicating the reason the payment was canceled.
    Example: null

  - `failed_code` (string)
    Code indicating the reason the payment failed processing.
    Example: null

  - `dispute_code` (string)
    Code indicating the reason the payment is in dispute.
    Example: null

  - `forward_reason_code` (string)
    Reason code for a forward payment.

Use this field to trigger the forward-payment flow. A forward payment is how you tell Resolve
that the customer already paid you and that Resolve should collect its portion from the forwarded amount.
    Enum: "ach", "check", "wire", "credit_card", "other"

  - `forward_reason_message` (string)
    Free-form reason text for a forward payment.
Required when `forward_reason_code` is `other`.
    Example: Customer paid by wire transfer outside Resolve.

  - `payment_links` (array)
    List of records the payment is applied to.

  - `payment_links.record_id` (string)
    ID of the record.
    Example: PMMlaE5wbg0

  - `payment_links.record_type` (string)
    Type of record the payment is applied to.
    Enum: "invoice"

  - `payment_links.amount` (number)
    Amount applied to this record.
    Example: 500

  - `created_by_user_id` (string)
    ID of the user who created the payment, if applicable.
    Example: null

## Response 400:

  - `400` (unknown)
    Bad request error

## Response 400 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Validation error

  - `error.type` (string)
    A short string, describing error type
    Enum: "validation_error"

  - `error.details` (array)

  - `error.details.path` (string)
    Path to the field failed validation
    Example: path.to.field

  - `error.details.message` (string)
    Detailed description of the error
    Example: `[field]` is required

## Response 401:

  - `401` (unknown)
    Unauthorized error

## Response 401 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Invalid merchant credentials

  - `error.type` (string)
    A short string, describing error type
    Enum: "authentication_error"

## Response 404:

  - `404` (unknown)
    Not found error

## Response 404 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: [entity] not found

  - `error.type` (string)
    A short string, describing error type
    Enum: "not_found_error"

## Response 429:

  - `429` (unknown)
    Rate limit error

## Response 429 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Too many requests

  - `error.type` (string)
    A short string, describing error type
    Enum: "rate_limit_error"