Skip to main content
Each Partner has exactly one contribution method: loyalty_points or direct_contribution. You do not send or select the method on each request—the server resolves it from Partner configuration. Delivery Emissions is independent of the contribution method. When Delivery Emissions is enabled for your Partner, you may optionally associate an estimate with a confirmed contribution; see Delivery Emissions.
For Loyalty, confirm only after points deduction. For Direct, confirm only after successful partner-side payment collection. Never send payment card or PSP credentials to Akhdar.

​
Supported configurations

​
Loyalty Points

Confirm only after your system has successfully deducted the customer’s loyalty points.

​
Point Conversion (PCV)

Each Loyalty Partner has a Partner-specific Point Conversion Version (PCV). At confirmation, Akhdar applies the active version and returns point_conversion_version and monetary_value_halalas (points multiplied by the version’s Halalas per point).
  • The rate is controlled by Akhdar. It is not a confirmation request field, and Partners cannot set or change it.
  • A new rate takes effect only through a future-effective version. Confirmed contributions keep the version and monetary value recorded at confirmation.
  • The rate is at least 1 Halala per point, using exact integer arithmetic.

​
Loyalty request body

Send POST {baseUrl}/v1/impact-transactions with points (positive whole number, minimum 1). Do not send amount_halalas or partner_payment_reference for Loyalty Partners.
With Delivery Emissions enabled for your Partner, you may include an optional calculation_id from a prior estimate. A missing or invalid optional calculation_id must not invalidate an otherwise valid contribution.

​
Direct Contribution

With Direct Contribution, the customer pays using your own payment infrastructure. You collect funds on your side; Akhdar does not process cards, receive PSP credentials, or integrate with a payment gateway in V1. Confirm to Akhdar only after payment collection succeeds on your side.

​
Direct request body

Send POST {baseUrl}/v1/impact-transactions with X-API-Key, Idempotency-Key, and:
  • partner_event_id — contribution uniqueness and recovery key
  • partner_order_ref — stable, non-PII order correlation
  • amount_halalas — integer Halalas (minimum 100, equal to 1 SAR), within the Partner maximum and platform ceiling
  • partner_payment_reference — opaque reference to your payment; unique per Partner and environment; must not contain card data or credentials
Do not send points for Direct Partners. Sending the other method’s fields returns invalid_request and does not create a contribution. An invalid amount returns invalid_direct_amount and does not create a contribution.
A duplicate partner_payment_reference returns 409 payment_reference_conflict. See Errors & Recovery.

​
Shared identities and headers

Each identity has a distinct purpose:
  • Idempotency-Key — transport request idempotency. The same header with the same canonical payload returns the original result. Conflicting immutable request data returns idempotency_conflict.
  • partner_event_id — contribution uniqueness and recovery key. The same value with the same immutable request data returns the original contribution. Conflicting immutable request data returns partner_event_conflict.
  • partner_order_ref — stable, non-PII order correlation. Only one confirmed contribution is allowed per partner, environment, and order. A conflict returns partner_order_conflict.
Every confirmation request requires X-API-Key, Idempotency-Key, and Content-Type: application/json.

​
Confirm a contribution

Successful confirmation returns HTTP 201.
Full response fields and examples are in Confirm a contribution and the API Reference.

​
Contribution statuses

  • pending is exceptional and non-final.
  • confirmed is terminal and non-refundable.
  • failed is terminal. Only then may the partner reverse the customer value (restore points or refund payment on your side).
confirmed and failed do not interchange. Do not restore points or customer payment while status is pending.

​
Recover a contribution

Use partner_event_id as the primary recovery key: GET {baseUrl}/v1/impact-transactions?partner_event_id=evt_contrib_01HZX5A1B2C3D4E5F6G7H8J9 A secondary lookup is available by transaction ID: GET {baseUrl}/v1/impact-transactions/{transaction_id} See Errors & Recovery before reversing customer value after a timeout or unknown result.