Loyalty

Loyalty lets your customers pay with points and collect points on what they buy, without you building a separate integration for each programme. It has two halves. Redemption ("burn") spends points as a payment method on the standard intent lifecycle. Earn awards points after a purchase, as an asynchronous call that never blocks your checkout.

Redemption ("burn")

A burn is not a separate product surface. It produces a transaction that appears in your transactions list, fires the usual webhooks (transaction.purchase.successful, intent.processed), and is refunded, reported and investigated exactly like a card payment. The one thing it adds is an authentication step: the loyalty programme sends a one-time password (OTP) to the customer, and the intent waits in an OTP state until that code is submitted. Most of this page is about driving that state correctly.

Choose where the OTP is collected

You have two ways to run a burn, and they are genuinely different integrations - not two names for the same work.

If you use the Embedded Experience, there is nothing on this page you have to implement for the OTP. Create the intent with the loyalty method and the customer's mobile number, put checkout on the page, and the embed collects the code, runs the countdown and offers the resend.

If you use the JavaScript SDK, handle the OTP_FORM state and pass the code to submitOtp():

if (intentDetails.state === "OTP_FORM") {
  const { otpLength, intentOtpData } = intentDetails.stateDetails;
  // Render an input sized to otpLength, then:
  await moneyHash.submitOtp({
    intentId,
    otp: "<CODE_THE_CUSTOMER_ENTERED>",
    intentOtpData,
  });
}

The rest of this page documents the third path: the External API, where you render and submit the OTP yourself.

Start a redemption

There is no separate "burn" endpoint. You start a redemption by creating an External API intent with the loyalty method already selected and the customer's mobile number attached - the same create call you already use, with two extra fields.

{
  "amount": 50,
  "amount_currency": "SAR",
  "operation": "purchase",
  "payment_method": "<LOYALTY_METHOD>",
  "billing_data": {
    "mobile_wallet_number": "+966500000000"
  },
  "webhook_url": "https://merchant.example.com/webhooks/moneyhash"
}

With the method and the mobile number both present, the External API create call can return the OTP state directly in its response. Because the method is already chosen, the intent skips METHOD_SELECTION entirely - there is no update-method call to make. For the rest of the External API state model, see External API.

The OTP intent state

Once the redemption starts, the intent reports an OTP state and the transaction waits for authentication. That payload is the contract for your OTP screen.

{
  "state": "OTP_FORM",
  "state_details": {
    "otp_length": 4,
    "expires_after_seconds": 180,
    "previous_submission_status": null
  }
}

The redemption flow

From the customer choosing loyalty to the confirmation screen, a server-side burn is: create the intent, read the OTP state, submit the code - plus an optional resend.

Here is the same flow in motion, including the path most integrations forget to build - a wrong code that re-prompts on the same transaction.

Identify the customer

A redemption is keyed on the customer's mobile number - not the card, and not your own customer ID. Whatever identity you hold for the customer elsewhere, a burn needs a mobile number that is registered with the loyalty programme.

{
  "billing_data": {
    "mobile_wallet_number": "+966500000000"
  }
}

{
  "loyalty": {
    "provider_id": "<LOYALTY_CONNECTION_ID>",
    "identifier": "+966500000000",
    "identifier_type": "PHONE_NUMBER"
  }
}

Earn and eligibility are not limited to phone numbers. identifier_type accepts PHONE_NUMBER, NATIONAL_ID or EMAIL, and each programme expects one of them. With the JavaScript SDK, getLoyaltyProviders() returns each connected programme's id, name and identifierType, so your UI can ask for the right thing.

A number that is not enrolled in the programme is a normal, expected case, not an edge case. There is no pre-check for redemption - enrolment is discovered when the OTP is requested or the code is submitted. Design the checkout so the customer can correct the number or fall back to another payment method without losing the intent.

Submit the OTP

Send the code the customer entered.

{
  "otp": "1234"
}

If you are on the Embedded Experience or the JavaScript SDK, you do not call this - checkout collects and submits the code for you.

On a valid OTP, the programme executes the redemption, the transaction moves to SUCCESSFUL, the intent reaches PROCESSED, and the standard webhooks fire:

• transaction.purchase.successful
• intent.processed

Treat the webhook as the source of truth for fulfilment, exactly as you would for a card payment.

On an invalid OTP, the transaction stays pending, the intent stays unprocessed, and the OTP state is returned again - see below.

Retry after a bad code

Every response after a submission lands in one of four places. Branch on the state first, then on previous_submission_status.

A wrong code does not end the redemption. The OTP state comes back on the same intent and transaction, with previous_submission_status populated, and the customer can try again:

{
  "state": "OTP_FORM",
  "state_details": {
    "otp_length": 4,
    "expires_after_seconds": 180,
    "previous_submission_status": "INVALID_OTP"
  }
}

previous_submission_status is the only reliable way to tell a retry prompt from a first prompt - the rest of the payload looks identical. If you branch on anything else, your UI shows a blank OTP screen instead of an error message.

When the redemption fails outright

A wrong code re-prompts. Other problems - most often a number that isn't valid for that programme - end the attempt instead. The HTTP response is still 200, so you must branch on the body: state: "TRANSACTION_FAILED" on the External API, or next_action: "FAILED" on the older shape.

There is no retry on this path. The attempt is over, and the operation's latest_status carries the reason. An OTP state means prompt again; a failed state means show the failure and offer another payment method. A checkout that only handles the OTP state hangs on a blank screen whenever this happens.

MoneyHash normalises each programme's error into one taxonomy, so you write one set of error copy regardless of which programme the customer chose:

Request a resend

When the customer says the code never arrived, or it expired, request a fresh one, with an empty body:

curl -X POST https://web.moneyhash.io/api/v1.4/external/payments/intents/<INTENT_ID>/otp-resend/ \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

import requests

response = requests.post(
    f"https://web.moneyhash.io/api/v1.4/external/payments/intents/{intent_id}/otp-resend/",
    headers={"x-api-key": "<YOUR_API_KEY>"},
    json={},
)

const res = await fetch(
  `https://web.moneyhash.io/api/v1.4/external/payments/intents/${intentId}/otp-resend/`,
  {
    method: "POST",
    headers: {
      "x-api-key": "<YOUR_API_KEY>",
      "Content-Type": "application/json",
    },
    body: "{}",
  },
);

The response is the full intent response, so re-render your OTP screen from it exactly as you did the first time - re-reading the OTP length and expiry, neither of which the new code is obliged to match.

Earn: award points after a payment

Earn is the other half of loyalty, and its contract is short but easy to get wrong: it is asynchronous. The payment is already done by the time points are involved, so nothing in your checkout should wait on an earn.

There are two ways to earn, and they behave differently - the difference matters more than it looks:

The standalone earn call

{
  "amount": "150.00",
  "currency": "SAR",
  "loyalty": {
    "provider_id": "<LOYALTY_CONNECTION_ID>",
    "identifier": "+966500000000",
    "identifier_type": "PHONE_NUMBER"
  },
  "merchant_reference": "ORDER-2026-05-12-00481",
  "webhook_url": "https://merchant.example.com/webhooks/moneyhash"
}

{
  "status": { "code": 202, "message": "success", "errors": [] },
  "data": {
    "id": "<EARN_ID>",
    "status": "PENDING",
    "provider_id": "<LOYALTY_CONNECTION_ID>",
    "amount": "150.00",
    "currency": "SAR",
    "merchant_reference": "ORDER-2026-05-12-00481",
    "created": "2026-05-12T14:32:11Z"
  },
  "count": 1,
  "next": null,
  "previous": null
}

amount, currency, loyalty and merchant_reference are required; webhook_url is optional. Full schema: Create loyalty earn.

The result arrives as a webhook - loyalty.earn.earned or loyalty.earn.failed, carrying provider_reference_id and failure_reason. You can also read the current state at any time with GET /api/v1.4/loyalty/earn/{id}/ (Retrieve loyalty earn).

What your integration should wait on: nothing. Do not block checkout, order confirmation, or the customer's success screen on the earn result.

Check eligibility before an earn

Some programmes let you ask whether a customer identifier is enrolled before you send an earn. Most do not - today only one of the connected programmes answers, and the rest return eligible: null. Treat the check as an optimisation for your UI, never as a gate.

curl -X POST https://web.moneyhash.io/api/v1.4/loyalty/eligibility/ \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "<LOYALTY_CONNECTION_ID>",
    "identifier": "+966500000000",
    "identifier_type": "PHONE_NUMBER"
  }'

import requests

response = requests.post(
    "https://web.moneyhash.io/api/v1.4/loyalty/eligibility/",
    headers={"x-api-key": "<YOUR_API_KEY>"},
    json={
        "provider_id": "<LOYALTY_CONNECTION_ID>",
        "identifier": "+966500000000",
        "identifier_type": "PHONE_NUMBER",
    },
)

const res = await fetch("https://web.moneyhash.io/api/v1.4/loyalty/eligibility/", {
  method: "POST",
  headers: {
    "x-api-key": "<YOUR_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    provider_id: "<LOYALTY_CONNECTION_ID>",
    identifier: "+966500000000",
    identifier_type: "PHONE_NUMBER",
  }),
});

Three outcomes, and they mean three different things:

{
  "status": { "code": 200, "message": "success", "errors": [] },
  "data": { "eligible": true },
  "count": 1,
  "next": null,
  "previous": null
}

{
  "status": { "code": 200, "message": "success", "errors": [] },
  "data": { "eligible": false, "reason": "customer_not_registered" },
  "count": 1,
  "next": null,
  "previous": null
}

{
  "status": { "code": 200, "message": "success", "errors": [] },
  "data": { "eligible": null, "reason": "This provider does not support eligibility check." },
  "count": 1,
  "next": null,
  "previous": null
}

A 400 is not a quiet "unknown". Treating it as one hides real integration mistakes. Full schema: Check loyalty eligibility.

Refunds and reversals

How points come back depends on which half of loyalty you are undoing - and in every case, reversal is full or nothing. Loyalty does not support partial reversal today.

{
  "amount": "150.00"
}

The rules are strict:

• amount must equal the original earn amount - a partial reversal is rejected with 400.
• The earn must be in EARNED. Reversing anything else returns 409.
• The call is asynchronous. The status moves to PENDING_REVERSE, then REVERSED or REVERSE_FAILED.

Full schema: Reverse loyalty earn.

Currency

Each loyalty programme decides which currencies it accepts, and the programmes available today operate in SAR. An intent in a currency the programme does not support will not offer its loyalty method, and an earn call in one is rejected at validation with a 400 such as "Currency USD is not supported by this provider."

Common errors and troubleshooting

Related

• External API - the full state model the redemption flow runs on.
• Customers - attaching a customer record to the intents you create.
• Check loyalty eligibility, Create loyalty earn, Retrieve loyalty earn, Reverse loyalty earn - API reference.