---
title: "Create loyalty earn"
method: POST
path: "/api/v1.4/loyalty/earn/"
tags: ["v1.1"]
---

# Create loyalty earn

`POST /api/v1.4/loyalty/earn/`

## Request

- Base URL: `https://web.moneyhash.io`
- URL: `https://web.moneyhash.io/api/v1.4/loyalty/earn/`
- Auth: one of:
  - API key in header `X-Api-Key`
  - API key in query parameter `access_token`

Creates a loyalty earn transaction for the account and queues processing with the configured provider. The transaction starts in PENDING status.

## Request body

- CreateEarnRequest
  - `merchant_reference` string, required: Your unique reference for this earn
  - `amount` string, decimal, required: Monetary amount driving the earn (provider rules apply).
  - `currency` 'USD' | 'CAD' | 'EUR' | 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ARS' | 'AUD' | 'AZN' | 'BAM' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BND' | 'BOB' | 'BRL' | 'BWP' | 'BYN' | 'BZD' | 'CDF' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EEK' | 'EGP' | 'ERN' | 'ETB' | 'GBP' | 'GEL' | 'GHS' | 'GNF' | 'GTQ' | 'HKD' | 'HNL' | 'HRK' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KHR' | 'KMF' | 'KRW' | 'KWD' | 'KZT' | 'LBP' | 'LKR' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MOP' | 'MUR' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SDG' | 'SEK' | 'SGD' | 'SOS' | 'SYP' | 'THB' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'UYU' | 'UZS' | 'VEF' | 'VND' | 'XAF' | 'XOF' | 'YER' | 'ZAR' | 'ZMK' | 'ZWL' | 'MRU', required: ISO currency code; must be supported by the loyalty provider. * `USD` - USD * `CAD` - CAD * `EUR` - EUR * `AED` - AED * `AFN` - AFN * `ALL` - ALL * `AMD` - AMD * `ARS` - ARS * `AUD` - AUD * `AZN` - AZN * `BAM` - BAM * `BDT` - BDT * `BGN` - BGN * `BHD` - BHD * `BIF` - BIF * `BND` - BND * `BOB` - BOB * `BRL` - BRL * `BWP` - BWP * `BYN` - BYN * `BZD` - BZD * `CDF` - CDF * `CHF` - CHF * `CLP` - CLP * `CNY` - CNY * `COP` - COP * `CRC` - CRC * `CVE` - CVE * `CZK` - CZK * `DJF` - DJF * `DKK` - DKK * `DOP` - DOP * `DZD` - DZD * `EEK` - EEK * `EGP` - EGP * `ERN` - ERN * `ETB` - ETB * `GBP` - GBP * `GEL` - GEL * `GHS` - GHS * `GNF` - GNF * `GTQ` - GTQ * `HKD` - HKD * `HNL` - HNL * `HRK` - HRK * `HUF` - HUF * `IDR` - IDR * `ILS` - ILS * `INR` - INR * `IQD` - IQD * `IRR` - IRR * `ISK` - ISK * `JMD` - JMD * `JOD` - JOD * `JPY` - JPY * `KES` - KES * `KHR` - KHR * `KMF` - KMF * `KRW` - KRW * `KWD` - KWD * `KZT` - KZT * `LBP` - LBP * `LKR` - LKR * `LTL` - LTL * `LVL` - LVL * `LYD` - LYD * `MAD` - MAD * `MDL` - MDL * `MGA` - MGA * `MKD` - MKD * `MMK` - MMK * `MOP` - MOP * `MUR` - MUR * `MXN` - MXN * `MYR` - MYR * `MZN` - MZN * `NAD` - NAD * `NGN` - NGN * `NIO` - NIO * `NOK` - NOK * `NPR` - NPR * `NZD` - NZD * `OMR` - OMR * `PAB` - PAB * `PEN` - PEN * `PHP` - PHP * `PKR` - PKR * `PLN` - PLN * `PYG` - PYG * `QAR` - QAR * `RON` - RON * `RSD` - RSD * `RUB` - RUB * `RWF` - RWF * `SAR` - SAR * `SDG` - SDG * `SEK` - SEK * `SGD` - SGD * `SOS` - SOS * `SYP` - SYP * `THB` - THB * `TND` - TND * `TOP` - TOP * `TRY` - TRY * `TTD` - TTD * `TWD` - TWD * `TZS` - TZS * `UAH` - UAH * `UGX` - UGX * `UYU` - UYU * `UZS` - UZS * `VEF` - VEF * `VND` - VND * `XAF` - XAF * `XOF` - XOF * `YER` - YER * `ZAR` - ZAR * `ZMK` - ZMK * `ZWL` - ZWL * `MRU` - MRU
  - `webhook_url` string, uri, nullable: Optional HTTPS URL for loyalty earn callbacks.
  - `loyalty` LoyaltyDataInput, required
    - `provider_id` string, required: MoneyHash loyalty service id (hashid) connected to the account.
    - `identifier` string, required: Customer identifier in the format required by identifier_type.
    - `identifier_type` 'PHONE_NUMBER' | 'NATIONAL_ID' | 'EMAIL', required: How to interpret identifier (for example PHONE_NUMBER, EMAIL, etc.). * `PHONE_NUMBER` - PHONE_NUMBER * `NATIONAL_ID` - NATIONAL_ID * `EMAIL` - EMAIL

## Response `202`

- EarnCreateResponse: Slim response shape for ``POST /loyalty/earn/`` (mirrors the spec).
  - `id` string, required: UUID is a unique identifier for the loyalty earn transaction.
  - `status` 'PENDING' | 'EARNED' | 'PENDING_REVERSE' | 'REVERSE_FAILED' | 'REVERSED' | 'FAILED': Lifecycle state: pending earn, earned, reversal, terminal failure, etc. * `PENDING` - PENDING * `EARNED` - EARNED * `PENDING_REVERSE` - PENDING_REVERSE * `REVERSE_FAILED` - REVERSE_FAILED * `REVERSED` - REVERSED * `FAILED` - FAILED
  - `provider_id` string, required: MoneyHash loyalty service id (hashid).
  - `amount` string, decimal, required: Earn amount.
  - `currency` string, required: ISO currency code of the earn amount.
  - `merchant_reference` string, required: Merchant-supplied reference.
  - `created` string, date-time, required

## Other responses

- `400`
- `401`

## Changes

- **2026-11-03** `4b67c1cef57d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/moneyhash/apis/moneyhash-api/changes/api/v1.4/loyalty/earn/post.md)

---

[API](https://skmtc.dev/moneyhash/apis/moneyhash-api.md) - [All operations](https://skmtc.dev/moneyhash/apis/moneyhash-api/llms.txt) - [OpenAPI document](https://skmtc.dev/moneyhash/apis/moneyhash-api/revisions/4b67c1cef57d?raw)