Payment Allocation

Coming Soon. The specification below is published for early review and may change before release.

Many payments carry more meaning than the amount and the payer. A deposit into a gaming account must be screened for responsible gambling. A wallet top-up requires the recipient’s identity for AML checks. A payment against a bill needs to be applied to that specific record on completion. Payment allocation captures this economic context in a structured, validated form, separate from payer identity and free-form metadata, so Moment can enforce the right compliance rules and automatically settle the right records. To set this context, include the payment_allocation field when creating a Payment Session. It is optional for most integrations. In regulated verticals such as gaming and wallet funding, it is required for compliance screening and regulatory reporting. Once a session is created, the allocation cannot be changed.

How it works

The customer and payment_allocation fields on a Payment Session serve distinct roles. customer identifies who is making the payment. payment_allocation identifies what the payment is for and which record it applies to. Two fields make up a payment allocation:

purpose: the reason the payment is being made, for example wallet_funding or gaming_deposit.
applies_to: the specific record the payment is applied against, identified by type.

These fields are independent. The same purpose can apply to different target types, and the same target type can serve different purposes. Together they determine which fields are required and how the payment is validated.

Examples

Wallet funding (external wallet)

A customer is loading funds into a wallet held in the merchant system or an external platform. Moment has no prior knowledge of the wallet holder, so identity and jurisdiction attributes are required for AML, PEP, and sanctions screening.

{
  "amount": 50000,
  "currency": "ZAR",
  "payment_allocation": {
    "purpose": "wallet_funding",
    "applies_to": {
      "type": "merchant_wallet",
      "id": "wallet_customer_456",
      "attributes": {
        "recipient": {
          "name": "Jane Smith",
          "country": "ZA",
          "identification": {
            "type": "national_id",
            "number": "8001015009087"
          }
        },
        "jurisdiction": "ZA"
      }
    }
  }
}

Wallet funding (Moment-managed wallet)

A customer is loading funds into a wallet managed by Moment. Identity and KYC data was captured at wallet onboarding. No attributes are required.

{
  "amount": 50000,
  "currency": "ZAR",
  "payment_allocation": {
    "purpose": "wallet_funding",
    "applies_to": {
      "type": "wallet",
      "id": "wlt_abc123"
    }
  }
}

Bill settlement

A customer is paying against a specific bill managed on the Moment platform.

{
  "amount": 100000,
  "currency": "ZAR",
  "payment_allocation": {
    "purpose": "settlement",
    "applies_to": {
      "type": "bill",
      "id": "bill_abc123"
    }
  }
}

Gaming deposit with compliance attributes

A customer is depositing funds into a gaming account. Regulatory, identity, and responsible gambling attributes are required.

{
  "amount": 20000,
  "currency": "ZAR",
  "payment_allocation": {
    "purpose": "gaming_deposit",
    "applies_to": {
      "type": "merchant_gaming_account",
      "id": "player_789",
      "attributes": {
        "recipient": {
          "name": "John Doe",
          "country": "ZA",
          "identification": {
            "type": "national_id",
            "number": "9001015009087"
          }
        },
        "gaming": {
          "kyc_status": "verified",
          "player_status": "active",
          "deposit_limit_applied": true
        },
        "jurisdiction": "ZA"
      }
    }
  }
}

Payment Purpose

The purpose field expresses the reason for the payment. It must be permitted by the merchant compliance profile.

Purpose	Description
`purchase`	Standard purchase or checkout payment.
`wallet_funding`	Loading funds into a wallet.
`gaming_deposit`	Deposit into a gaming or gambling account.
`settlement`	Payment against a Moment-managed record: customer, account, bill, or payment request.
`invoice_payment`	Payment against an invoice in the merchant system or an external platform.
`merchant_defined`	Custom purpose defined by the merchant.

The following purposes are planned but not yet available: account_top_up, loan_repayment, subscription_payment, airline_booking, lodging, healthcare, debt_repayment, cruise.Contact us to discuss further.

Payment Target

A payment target is the specific record the payment is applied against: a wallet being funded, a bill being settled, or a gaming account receiving a deposit. The applies_to field sets up the payment target and enables automated application of the funds against that record on completion.

Type

The type field specifies the kind of target, for example a wallet, gaming account, or bill. It determines which fields are required, where id comes from, and which attributes apply. Targets fall into two categories: Moment-managed and merchant-managed. Moment-managed targets. Moment holds identity and compliance context for these objects. No compliance attributes are required at transaction time.

Type	`id`	Description
`wallet`	Moment wallet ID	A Moment-managed wallet.
`customer`	Moment customer ID	A Moment-managed customer. Moment resolves which records to settle.
`account`	Moment account ID	A Moment-managed account. Moment resolves which records to settle.
`bill`	Moment bill ID	A Moment-managed bill.
`payment_request`	Moment payment request ID	A Moment-managed payment request.

Merchant-managed targets. Moment has no prior knowledge of these objects. Identity and compliance context must be supplied in attributes where required.

Type	`id`	Description
`merchant_wallet`	Merchant-defined	A wallet in the merchant system or an external platform.
`merchant_invoice`	Merchant-defined	An invoice in the merchant system or an external platform.
`merchant_gaming_account`	Merchant-defined	A gaming or gambling account in the merchant system.
`merchant_defined`	Merchant-defined	A custom target type defined by the merchant.
`unstructured`	Not applicable	A descriptive-only target with no structured identifier.

Description

An optional human-readable label for the target, available on all target types. For unstructured targets, at least one of description or attributes must be present.

{
  "type": "unstructured",
  "description": "Annual membership renewal for account AC-00123"
}

Attributes

Compliance and identity data about the payment target is passed in attributes. Required fields depend on the target type. For merchant_wallet and merchant_gaming_account targets, attributes is required. Moment has no prior knowledge of the recipient, so identity and jurisdiction data is needed for compliance screening. Unknown fields are rejected. These targets also typically require the customer field to be set on the session, identifying the payer alongside the recipient. For all other target types, attributes is optional.

The Required column reflects API-level defaults.Fields marked Conditional are optional by default but may be required at runtime by the merchant compliance profile, for example identity document for FICA, address for enhanced due diligence, or date of birth for age verification in licensed gaming jurisdictions.

Wallet Funding Fields

recipient (required)

Field	Description	Required
`name`	Full legal name of the recipient.	Yes
`first_name`	First name. Optional complement to `name` for providers that require split name fields.	Conditional
`middle_name`	Middle name. Used for identity disambiguation.	Conditional
`last_name`	Last name. Optional complement to `name` for providers that require split name fields.	Conditional
`country`	Country of residence of the recipient. ISO 3166-1 alpha-2.	Yes

recipient.identification (optional)

Field	Description	Required
`type`	Type of identity document. One of: `national_id`, `passport`, `drivers_license`, `asylum_seeker_permit`, `other`.	Conditional
`number`	Identity document number.	Conditional
`issuing_country`	Country that issued the identity document. May differ from `country` for foreign nationals.	Conditional

recipient.address (optional)

Field	Description	Required
`line1`	First line of the recipient’s address.	Conditional
`line2`	Second line of the recipient’s address.	Conditional
`city`	City.	Conditional
`state`	State, province, or region.	Conditional
`postal_code`	Postal code.	Conditional

jurisdiction (required) Regulatory jurisdiction of the wallet scheme. May differ from recipient.country. account (optional)

Field	Description	Required
`type`	Type of wallet account (for example `savings`, `current`, `ewallet`).	No
`program`	Program or scheme identifier for the wallet.	No

Gaming Deposit Fields

recipient (required)

Field	Description	Required
`name`	Full legal name of the player.	Yes
`first_name`	First name. Optional complement to `name` for providers that require split name fields.	Conditional
`middle_name`	Middle name. Used for identity disambiguation.	Conditional
`last_name`	Last name. Optional complement to `name` for providers that require split name fields.	Conditional
`country`	Country of residence of the player. ISO 3166-1 alpha-2.	Yes
`date_of_birth`	Date of birth in `yyyy-mm-dd` format. Used for age verification in licensed gaming jurisdictions.	Conditional

recipient.identification (optional)

Field	Description	Required
`type`	Type of identity document. One of: `national_id`, `passport`, `drivers_license`, `asylum_seeker_permit`, `other`.	Conditional
`number`	Identity document number.	Conditional
`issuing_country`	Country that issued the identity document. May differ from `country` for foreign nationals.	Conditional

recipient.address (optional)

Field	Description	Required
`line1`	First line of the player’s address.	Conditional
`line2`	Second line of the player’s address.	Conditional
`city`	City.	Conditional
`state`	State, province, or region.	Conditional
`postal_code`	Postal code.	Conditional

gaming (required)

Field	Description	Required
`kyc_status`	KYC verification status. One of: `verified`, `pending`, `unverified`.	Yes
`player_status`	Account status. One of: `active`, `suspended`, `self_excluded`.	Yes
`deposit_limit_applied`	Whether deposit limits have been checked and applied. Boolean.	Yes
`tier`	Player classification or VIP tier.	No

jurisdiction (required) Regulatory jurisdiction of the gaming operator (for example ZA, CW). May differ from recipient.country. account (optional)

Field	Description	Required
`type`	Type of account (for example `savings`, `current`, `ewallet`).	No
`program`	Gaming program or casino identifier.	No

Validation

Validation runs at session creation. The request is rejected if any of the following rules are violated.

Rule	Detail
`payment_allocation` may be required	Optional at the API level. Required for merchants whose compliance profile sets `requires_payment_allocation`. Omitting it on those profiles results in a rejected request.
`purpose` must be permitted	The purpose must be in the merchant compliance profile’s allowed purposes.
`applies_to` required by purpose	Some purposes require `applies_to`. Others make it optional.
`id` required for most types	Required for all target types except `unstructured`.
`unstructured` requires description or attributes	At least one of `description` or `attributes` must be present for `type: unstructured` targets.
Required attributes for `merchant_wallet` and `merchant_gaming_account`	`attributes` is required and all required attribute fields must be present. Unknown attribute keys are rejected.

Getting Started

Collect

Stored Value

Billing

Network

Reconciliation and Reporting

Help

How it works

Examples

Payment Purpose

Payment Target

Type

Description

Attributes

Wallet Funding Fields

Gaming Deposit Fields

Validation

​How it works

​Examples

​Payment Purpose

​Payment Target

​Type

​Description

​Attributes

​Wallet Funding Fields

​Gaming Deposit Fields

​Validation

How it works

Examples

Payment Purpose

Payment Target

Type

Description

Attributes

Wallet Funding Fields

Gaming Deposit Fields

Validation