> ## Documentation Index
> Fetch the complete documentation index at: https://docs.momentco.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Payment Allocation
> Declare the purpose and target of a payment for compliance enforcement and automated settlement.
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
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.
```json theme={"system"}
{
"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"
}
}
}
}
```
A customer is loading funds into a wallet managed by Moment. Identity and KYC data was captured at wallet onboarding. No attributes are required.
```json theme={"system"}
{
"amount": 50000,
"currency": "ZAR",
"payment_allocation": {
"purpose": "wallet_funding",
"applies_to": {
"type": "wallet",
"id": "wlt_abc123"
}
}
}
```
A customer is paying against a specific bill managed on the Moment platform.
```json theme={"system"}
{
"amount": 100000,
"currency": "ZAR",
"payment_allocation": {
"purpose": "settlement",
"applies_to": {
"type": "bill",
"id": "bill_abc123"
}
}
}
```
A customer is depositing funds into a gaming account. Regulatory, identity, and responsible gambling attributes are required.
```json theme={"system"}
{
"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.
```json theme={"system"}
{
"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. |