Contributions

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.

POST

impact-transactions

curl -X POST "{baseUrl}/v1/impact-transactions" \
  -H "X-API-Key: $AKHDAR_API_KEY" \
  -H "Idempotency-Key: idem_01HZX5Z9Y8X7W6V5U4T3S2R1" \
  -H "Content-Type: application/json" \
  -d '{"partner_event_id":"evt_contrib_01HZX5A1B2C3D4E5F6G7H8J9","partner_order_ref":"ord_9f3c2a71","points":500,"opaque_customer_ref":"cust_ref_8a1b2c3d"}'

{
  "contribution": {
    "transaction_id": "txn_01HZX6M4N5P6Q7R8S9T0U1V2",
    "partner_event_id": "evt_contrib_01HZX5A1B2C3D4E5F6G7H8J9",
    "partner_order_ref": "ord_9f3c2a71",
    "status": "confirmed",
    "contribution_method": "loyalty_points",
    "monetary_value_halalas": 500,
    "tree_cost_version": "TCV-2026-10-01",
    "expected_environmental_support": {
      "summary_en": "Support tree planting",
      "summary_ar": "ادعم زراعة الشجر"
    },
    "non_refundable": true,
    "environment": "sandbox",
    "created_at": "2026-08-03T12:00:00.000Z",
    "points": 500,
    "point_conversion_version": "PCV-partner-a-2026-10-01",
    "contribution_rule_version": "CRV-v1.0.0",
    "amount_halalas": 500,
    "partner_payment_reference": "pay_ref_abc123xyz",
    "opaque_customer_ref": "cust_ref_8a1b2c3d",
    "delivery_emissions_id": "emi_01HZX...",
    "confirmed_at": "2026-08-03T12:05:00Z",
    "failed_at": null
  },
  "association": {
    "status": "associated",
    "link": {
      "association_id": "link_01HZX7A1B2C3D4E5F6G7H8J9",
      "transaction_id": "txn_01HZX6M4N5P6Q7R8S9T0U1V2",
      "calculation_id": "calc_01HZX4K9M2Q8R7N6P5T4V3W2X1",
      "partner_order_ref": "ord_9f3c2a71",
      "estimated_emissions_kgco2e": "1.059902",
      "estimated_emissions_unit": "kgco2e",
      "distance_km": "7.400",
      "distance_unit": "km",
      "vehicle_category": "motorcycle_gasoline",
      "methodology_version": "DEM-WTW-v1.0.0",
      "emission_factor_version": "EF-DESNZ-2026-MOTORCYCLE-GASOLINE-AVG-WTW-v1.0.0",
      "calculated_at": "2026-08-03T12:00:00.000Z",
      "associated_at": "2026-08-03T12:00:00.000Z",
      "environment": "sandbox",
      "immutable": true
    }
  },
  "request": {
    "correlation_id": "corr_7c2e9b1a4d6f8e0c",
    "idempotency_key": "idem_01HZX5Z9Y8X7W6V5U4T3S2R1"
  }
}

Authorizations

X-API-Key

string

header

required

Canonical server-to-server API key header name: X-API-Key. Partner customer applications must not use this credential. Examples must never include raw API secrets.

Headers

Idempotency-Key

string

required

Transport/request idempotency key required for delivery-emissions estimate creation, contribution confirmation, and emissions-association creation. Same key + same canonical payload returns the original result. Same key + conflicting canonical payload returns idempotency_conflict.

Non-PII transport idempotency key.

Required string length: 8 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Example:

"idem_01HZX5Z9Y8X7W6V5U4T3S2R1"

X-Correlation-ID

string

Optional request correlation header. If omitted, Akhdar generates one. Every success and error response includes X-Correlation-ID. Error payloads include correlation_id.

Non-PII request correlation identifier.

Required string length: 8 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Example:

"corr_7c2e9b1a4d6f8e0c"

Body

application/json

Method-discriminated contribution confirmation request. The Partner's configured contribution_method determines which fields are required: - loyalty_points: requires points; amount_halalas and partner_payment_reference must be absent or null.

direct_contribution: requires amount_halalas and partner_payment_reference; points must be absent or null. The API validates the request against the Partner's stored method and returns 400 invalid_request if required method-specific fields are missing or forbidden fields are present.

partner_event_id

string

required

Stable contribution idempotency and recovery key supplied by the partner. Distinct from partner_order_ref.

Required string length: 8 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Example:

"evt_contrib_01HZX5A1B2C3D4E5F6G7H8J9"

partner_order_ref

string

required

Stable non-PII partner order correlation reference. Enforces one confirmed contribution per partner order within partner and environment. Must not contain direct personal data.

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Example:

"ord_9f3c2a71"

points

integer<int64>

Loyalty points contributed. Required when Partner contribution_method is loyalty_points. Must be absent or null for direct_contribution Partners.

Required range: x >= 1

Example:

500

amount_halalas

integer<int64>

Direct Contribution amount in Halalas. Required when Partner contribution_method is direct_contribution. Must be absent or null for loyalty_points Partners.

Required range: x >= 100

Example:

500

partner_payment_reference

string

Partner-supplied payment reference for Direct Contribution. Required when Partner contribution_method is direct_contribution. Must be unique within Partner and Environment. Must be absent or null for loyalty_points Partners.

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Example:

"pay_ref_abc123xyz"

calculation_id

string

Optional Delivery Emissions estimate identifier for association. Only valid when Partner has delivery_emissions_enabled: true. Missing, invalid, or capability- disabled values must not invalidate an otherwise valid contribution.

Required string length: 8 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Example:

"calc_01HZX4K9M2Q8R7N6P5T4V3W2X1"

opaque_customer_ref

string

Optional opaque partner-internal customer reference. Must not contain email, phone, full name, national identifier, or other direct personal data.

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Example:

"cust_ref_8a1b2c3d"

Response

Idempotent replay returned the original contribution and association outcome.

contribution

object

required

Method-discriminated contribution record. Loyalty contributions include points and point_conversion_version. Direct contributions include amount_halalas and partner_payment_reference. monetary_value_halalas is the canonical amount in Halalas.

Show child attributes

association

object

required

Closed association outcomes. associated includes link. rejected includes rejection. not_requested includes neither.

Option 1
Option 2
Option 3

Show child attributes

request

object

required

Show child attributes

curl -X POST "{baseUrl}/v1/impact-transactions" \
  -H "X-API-Key: $AKHDAR_API_KEY" \
  -H "Idempotency-Key: idem_01HZX5Z9Y8X7W6V5U4T3S2R1" \
  -H "Content-Type: application/json" \
  -d '{"partner_event_id":"evt_contrib_01HZX5A1B2C3D4E5F6G7H8J9","partner_order_ref":"ord_9f3c2a71","points":500,"opaque_customer_ref":"cust_ref_8a1b2c3d"}'

{
  "contribution": {
    "transaction_id": "txn_01HZX6M4N5P6Q7R8S9T0U1V2",
    "partner_event_id": "evt_contrib_01HZX5A1B2C3D4E5F6G7H8J9",
    "partner_order_ref": "ord_9f3c2a71",
    "status": "confirmed",
    "contribution_method": "loyalty_points",
    "monetary_value_halalas": 500,
    "tree_cost_version": "TCV-2026-10-01",
    "expected_environmental_support": {
      "summary_en": "Support tree planting",
      "summary_ar": "ادعم زراعة الشجر"
    },
    "non_refundable": true,
    "environment": "sandbox",
    "created_at": "2026-08-03T12:00:00.000Z",
    "points": 500,
    "point_conversion_version": "PCV-partner-a-2026-10-01",
    "contribution_rule_version": "CRV-v1.0.0",
    "amount_halalas": 500,
    "partner_payment_reference": "pay_ref_abc123xyz",
    "opaque_customer_ref": "cust_ref_8a1b2c3d",
    "delivery_emissions_id": "emi_01HZX...",
    "confirmed_at": "2026-08-03T12:05:00Z",
    "failed_at": null
  },
  "association": {
    "status": "associated",
    "link": {
      "association_id": "link_01HZX7A1B2C3D4E5F6G7H8J9",
      "transaction_id": "txn_01HZX6M4N5P6Q7R8S9T0U1V2",
      "calculation_id": "calc_01HZX4K9M2Q8R7N6P5T4V3W2X1",
      "partner_order_ref": "ord_9f3c2a71",
      "estimated_emissions_kgco2e": "1.059902",
      "estimated_emissions_unit": "kgco2e",
      "distance_km": "7.400",
      "distance_unit": "km",
      "vehicle_category": "motorcycle_gasoline",
      "methodology_version": "DEM-WTW-v1.0.0",
      "emission_factor_version": "EF-DESNZ-2026-MOTORCYCLE-GASOLINE-AVG-WTW-v1.0.0",
      "calculated_at": "2026-08-03T12:00:00.000Z",
      "associated_at": "2026-08-03T12:00:00.000Z",
      "environment": "sandbox",
      "immutable": true
    }
  },
  "request": {
    "correlation_id": "corr_7c2e9b1a4d6f8e0c",
    "idempotency_key": "idem_01HZX5Z9Y8X7W6V5U4T3S2R1"
  }
}

Overview

Contributions

Delivery Emissions

Webhooks

Confirm a loyalty-points contribution

Authorizations

Headers

Body

Response