# Order Payments

Retrieve and update payment records attached to orders. Each order can have one or more order payments, each representing a payment attempt or partial payment using a specific payment method.

### `GET /order_payments/{orderPaymentId}` - Get an order payment

Retrieve a single order payment by its ID. Returns the payment details including status, amount, and associated payment method.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| orderPaymentId | integer | Yes | The ID of the order payment to retrieve. |

#### Response

```json
{
  "status": 200,
  "code": "order_payment_found",
  "message": "Order payment has been successfully found.",
  "data": {
    "orderPaymentId": 34210,
    "orderId": 582901,
    "paymentMethodId": 12,
    "amount": 1250,
    "paymentStatus": "OK",
    "metadata": null,
    "createdAt": "2025-03-10T14:22:00.000Z",
    "updatedAt": "2025-03-10T14:22:05.000Z"
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "order\_payment\_found" | Machine-readable application code for the result. |
| message | string | "Order payment has been successfully found." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.orderPaymentId | integer | 34210 | Identifier of the associated order payment. |
| data.orderId | integer | 582901 | Identifier of the order. |
| data.paymentMethodId | integer | 12 | Identifier of the associated payment method. |
| data.amount | integer | 1250 | The amount value. |
| data.paymentStatus | string | "OK" | The payment status value. |
| data.metadata | null | null | Additional metadata supplied with the response. |
| data.createdAt | string | "2025-03-10T14:22:00.000Z" | Timestamp when this resource was created. |
| data.updatedAt | string | "2025-03-10T14:22:05.000Z" | Timestamp when this resource was last updated. |

### `PUT /order_payments/{orderPaymentId}` - Update an order payment

Update the metadata or payment status of an existing order payment. The paymentStatus field accepts: PENDING, OK, KO, or REFUNDED.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| orderPaymentId | integer | Yes | The ID of the order payment to update. |

#### Request Body

```json
{
  "metadata": "{\"transactionRef\":\"txn_abc123\"}",
  "paymentStatus": "OK"
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| metadata | string | "{\\"transactionRef\\":\\"txn\_abc123\\"}" | Additional metadata supplied with the response. |
| paymentStatus | string | "OK" | The payment status value. |

#### Response

```json
{
  "status": 200,
  "code": "order_payment_updated",
  "message": "Order payment has been successfully updated.",
  "data": {
    "orderPaymentId": 34210,
    "orderId": 582901,
    "paymentMethodId": 12,
    "amount": 1250,
    "paymentStatus": "OK",
    "metadata": "{\"transactionRef\":\"txn_abc123\"}",
    "createdAt": "2025-03-10T14:22:00.000Z",
    "updatedAt": "2025-03-10T14:30:12.000Z"
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "order\_payment\_updated" | Machine-readable application code for the result. |
| message | string | "Order payment has been successfully updated." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.orderPaymentId | integer | 34210 | Identifier of the associated order payment. |
| data.orderId | integer | 582901 | Identifier of the order. |
| data.paymentMethodId | integer | 12 | Identifier of the associated payment method. |
| data.amount | integer | 1250 | The amount value. |
| data.paymentStatus | string | "OK" | The payment status value. |
| data.metadata | string | "{\\"transactionRef\\":\\"txn\_abc123\\"}" | Additional metadata supplied with the response. |
| data.createdAt | string | "2025-03-10T14:22:00.000Z" | Timestamp when this resource was created. |
| data.updatedAt | string | "2025-03-10T14:30:12.000Z" | Timestamp when this resource was last updated. |