---
title: "Add a payment to an order"
method: POST
path: "/shop/orders/{orderId}/payments"
tags: ["Orders"]
---

# Add a payment to an order

`POST /shop/orders/{orderId}/payments`

Record a payment against an order. Use this endpoint to attach a manual
payment — for example a cash payment taken at the front desk, a bank
transfer that has cleared, or a card transaction taken via a terminal
that is not integrated with Trybe.

The `amount` must be greater than zero, expressed in the lowest
denomination of the order's currency (pennies for `GBP`, cents for
`USD`, and so on). The created payment is returned in the `data`
envelope along with its assigned `id`, status, and refundable amount.

Returns `400 Bad Request` if the payment can't be added — for example
because the amount exceeds the outstanding balance, or the order is
in a state that no longer accepts new payments.

## Request body

- object
  - `amount` integer, required — The amount of the payment, expressed in the lowest denomination of the order's currency (e.g. pennies for `GBP`, cents for `USD`). Must be greater than zero unless `capture_method` is `on_demand` and the request is being used to store a payment method for later charging — in which case `0` is also accepted.
  - `capture_method` string, nullable — When the payment amount should be captured. Use `automatic` for an immediate capture (the default for most manual entries) or `on_demand` when storing a payment method to be charged later.
  - `details_source` string, nullable — How the payment method will be supplied — for example `pay_by_link` for a hosted checkout link, or `terminal` for an in-person card terminal.
  - `processor_data` object — An optional dictionary of processor-specific data. For `on_demand` payments this can include `save_payment_method: true` to persist the payment method against the customer for future use.

## Response `201`

A single payment recorded against an order.

- object
  - `data` Payment, required — An instance of a payment against an order.
    - `id` string, object-id, required — The ID of the item to be added.
    - `amount` integer, required — The amount of the payment, in the lowest denomination
    - `capture_method` string, nullable, required — At what point the payment amount will be captured
    - `chargebacks` Chargeback[]
      - `id` string, object-id, required
      - `amount` string, required
      - `currency` string, required — The ISO-4217 currency code.
      - `payment_id` string, object-id, required — The ID of the payment that was charged back.
      - `processor_data` object, required
      - `reason` string, required — The reason for the chargeback.
      - `status` 'confirmed' | 'pending' | 'processed' | 'reversed', required
      - `created_at` string, date-time, required — When then resource was created.
    - `currency` string, required — The ISO-4217 currency code.
    - `details_source` string, nullable, required — How the payment method will be provided
    - `failure_reason` string, nullable — If present, provides a human-readable explanation for the failure.
    - `item_revenues` PaymentItemRevenue[], nullable, required — How the payment amount is allocated across the order's items and revenue centres. Null for payments taken before item revenue allocation was enabled — such payments cannot support item-level operations like partial charge to room.
      - `basket_item_id` string, object-id, required — The ID of the order item that this allocation covers.
      - `revenue_centre` string, required — The revenue centre of the order item's revenue line that this allocation covers.
      - `gross_amount` integer, required — The gross amount of the payment allocated to this revenue line, in the lowest denomination.
      - `net_amount` integer, required — The net amount of the payment allocated to this revenue line, in the lowest denomination.
      - `refunded_amount` integer, required — The amount of this allocation that has been refunded, in the lowest denomination.
      - `currency` string, required — The ISO-4217 currency code.
    - `order_ref` string, nullable
    - `paid_at` string, date-time, nullable, required — The time and date that the payment was paid.
    - `payable_id` string, object-id, required
    - `payable_type` string, required
    - `processor` string, required — The payment processor to be used for the payment
    - `processor_data` object, required — A dictionary of processor-specific data
    - `processor_id` string, object-id, required
    - `processor_type` string, nullable, required
    - `refundable_amount` number, required — The amount of the payment that may be refunded.
    - `refunds` Refund[], required
      - `id` string, object-id, required — The ID of the refund.
      - `payment_id` string, object-id, required — The ID of the payment that was refunded.
      - `amount` integer, required — The amount of the refund.
      - `currency` string, required — The ISO-4217 currency code.
      - `notes` string, nullable — Notes that were added against the refund.
      - `status` 'pending' | 'complete' | 'failed', required — The current status of the refund.
      - `processor_data` object, required — A dictionary of processor-specific data.
      - `created_at` string, date-time, required — The date and time that the refund was created.
    - `status` 'cancelled' | 'expired' | 'failed' | 'paid' | 'payment_method_charged' | 'payment_method_stored' | 'pending' | 'ready_for_capture' | 'requires_action', required — The current status of the payment
    - `created_at` string, date-time, required — When then resource was created.

## Other responses

- `400` — The request failed.
- `404` — The resource couldn't be found
- `422` — The request didn't pass validation

---

[API](https://skmtc.dev/try/apis/trybe-api.md) · [All operations](https://skmtc.dev/try/apis/trybe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/try/trybe-api/revisions/f37f92702da5/schema)