> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akhdar-sa.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use {baseUrl} for the environment-specific base URL provided to the partner integration team. Do not invent an API hostname.
> x-akhdar-* fields are publication provenance only. Do not treat them as partner integration instructions.

# Confirm a loyalty-points contribution

> Confirms a contribution using the Partner's configured method. Loyalty Partners
send `points` after deducting loyalty points. Direct Partners send `amount_halalas`
and `partner_payment_reference` after collecting payment on their own infrastructure.
Do not send the method on the request, and do not send card or PSP credentials.

**Identities**
- `Idempotency-Key` is required. The same key and payload returns the original result.
  A conflicting payload returns `idempotency_conflict`.
- `partner_event_id` is the contribution uniqueness and recovery key.
- `partner_order_ref` allows one confirmed contribution per partner, environment, and order.
- Direct `partner_payment_reference` must be unique per Partner and environment.
- `calculation_id` is optional and only when Delivery Emissions is enabled. A missing or
  invalid value must not fail an otherwise valid contribution.

**Validation**
- Loyalty `points` must be a positive whole number (minimum `1`). Invalid shape returns
  `invalid_point_amount` and does not persist a contribution.
- Direct `amount_halalas` is an integer number of Halalas, minimum `100` (1 SAR), and
  must not exceed the Partner maximum or platform ceiling. Invalid shape or range returns
  `invalid_direct_amount` and does not persist a contribution.
- Fields for the other method return `invalid_request` and do not persist a contribution.
- A duplicate `partner_payment_reference` returns `payment_reference_conflict`.

**Statuses**
- `pending` is exceptional and non-final. `confirmed` and `failed` are terminal and do not interchange.
- A confirmed contribution is non-refundable through this API.
- Do not reverse customer value (loyalty points or collected payment) for `pending`, timeout,
  unknown result, or `contribution_not_found`. Reverse value on your side only after terminal `failed`.
- Recover by `partner_event_id`. Association failure is non-fatal: the contribution stays confirmed.




## API Specification

The full API specification for this endpoint is available in the [documentation index](https://docs.akhdar-sa.com/llms.txt).