Custom party data maps

Partners often already have stable business and beneficiary records. The data may be complete, but its field names and nesting differ from Axiym's sender and receiver schemas.

A saved party data map connects those existing structures to Axiym's required party fields. Your integration can submit the objects it already produces, while the prepared payout still contains one consistent sender and receiver shape for review and execution.

Why use a party data map

What a party data map covers

The map changes field structure. It does not store real party values or predict the values that later payouts will contain. After the map is applied, Axiym normalizes controlled values separately for each payout and then performs deterministic validation. Exact accepted Axiym values pass through unchanged.

How it works

The Payload Mapping Tool does not identify the partner or store the result. It only produces a portable definition containing sender and receiver field paths. Submit that definition using Store a party data map. The access token associates the stored map with your partnership, and the response supplies its immutable partyDataMapId and contentHash. Partnership maps are integration resources and can be reused across payments created by the same partnership.

Before using the map to create a payment, call Test a payout with its partyDataMapId. The test applies the map to representative party objects, normalizes controlled values across the complete payload, and reports destination-specific validation results.

The test does not require or create a quote. Its context identifies the sell currency, destination country, buy currency, and payout method whose data requirements should be applied. It does not check rates, amount limits, or funding, and it does not reserve funds or persist the submitted payload.

{
  "context": {
    "sellCurrency": "USD",
    "destinationCountry": "PH",
    "buyCurrency": "PHP",
    "payoutMethod": "BANK"
  },
  "partyDataMapId": "eaf72392-b8fb-4ca4-bc42-416445a6acbb",
  "transaction": {
    "purpose": "payment for software development",
    "sourceOfFunds": "revenue from normal operations",
    "supportingDocuments": [
      {
        "documentType": "supplier invoice",
        "documentContentType": "application/pdf",
        "documentData": "JVBERi0xLjQKJcTl8uXrCg=="
      }
    ]
  },
  "sender": {},
  "receiver": {}
}

The response shows the normalized payload and lists each controlled value that changed. Read Test payout data for the behavior that applies with or without a Party Data Map.

Store the resulting partyDataMapId with the integration configuration for the party structures it describes. If either structure changes materially, export and store a new map. Existing maps remain immutable so earlier payments retain the exact mapping identity used to prepare them.

Use a saved map

{
  "quoteId": "978490c4-4227-4a75-9820-5f90482bb78b",
  "clientReference": "PAYOUT-2026-001",
  "partyDataMapId": "eaf72392-b8fb-4ca4-bc42-416445a6acbb",
  "transaction": {
    "purpose": "GOODS_PURCHASE",
    "sourceOfFunds": "BUSINESS_REVENUE",
    "reference": "INV-2026-001",
    "supportingDocuments": [
      {
        "documentType": "INVOICE",
        "documentContentType": "application/pdf",
        "documentData": "JVBERi0xLjQKJcTl8uXrCg=="
      }
    ]
  },
  "sender": {
    "company": {
      "registeredName": "Acme Trading Pte Ltd"
    }
  },
  "receiver": {
    "beneficiary": {
      "registeredName": "Example Supplier Corporation"
    }
  }
}

The abbreviated party objects above illustrate ownership of the structure; the submitted objects must contain every field required by the saved map and the quote corridor.

The create response returns the normalized paymentData.sender and paymentData.receiver, regardless of which input mode was used. Review those objects before confirming the payout.

Interpreting mapping results

A map never bypasses validation. After mapping, the normalized parties must still satisfy the same OpenAPI schemas and destination-specific rules as direct Axiym-shaped input.

Start with The payout payload for the complete request context, then use the Payload Mapping Tool to explore your own sample objects.