# Create a payout with mapped data

Creates a payout from one payment object using the immutable definition identified by paymentDataMapId. All source paths are relative to payment. The map must be ACTIVE; an archived map is rejected with HTTP 422.

Axiym applies the saved field mappings, connects documents through nesting or exact ID matches and filters, and translates controlled labels. Exact Axiym codes pass unchanged. Other values must match a saved label exactly, including case and whitespace. Each array entry is processed independently. Missing optional paths are omitted; unmapped source fields are ignored. Ambiguous or unmatched files in a configured document collection are rejected.

The map also determines sender handling and the fixed amount side. A map using onboarded-profile uses the account holder profile and skips sender rules. A map using supplied requires the mapped sender data. Amount resolution uses the mapped amount currency, the Axiym funding account currency, and the recipient destination currency, or the saved fixed-side rule.

The resulting data must satisfy the strict PayoutRequest schema and current corridor requirements. Unknown labels, missing required data, incompatible source types, and invalid document or currency associations are rejected with HTTP 422. Axiym then calculates commercial terms.

Creation returns the prepared instruction and commercial terms in PENDING_CONFIRMATION. It does not reserve funds or start processing. Review the returned instruction, then confirm it before termsExpireAt. Confirmation uses the stored instruction without rerunning the map.

Product: Payment API
API reference version: 0.1.0 (current)
OpenAPI contract: https://docs.axiym.io/openapi/payment-api/0.1.0.yaml
Canonical page: https://docs.axiym.io/payment-api/api-reference/0.1.0/payouts/createMappedPayout

[Compact reference](/payment-api/api-reference/0.1.0/payouts/createMappedPayout.md)

## POST /payouts/mapped

## Servers

```json
[
  {
    "url": "https://partner-api.sandbox.axiym.io/api/v1",
    "description": "Sandbox"
  },
  {
    "url": "https://partner-api.axiym.io/api/v1",
    "description": "Production"
  }
]
```

## Authentication

```json
{
  "security": [
    {
      "Default": []
    }
  ],
  "securitySchemes": {
    "Default": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
}
```

## Parameters

### header: X-Request-Id

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional request identifier for tracing and support. A UUID is recommended. Axiym echoes it in `X-Request-Id`, or generates one when omitted.",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

### header: Idempotency-Key

```json
{
  "name": "Idempotency-Key",
  "in": "header",
  "required": true,
  "description": "Identifies one state-changing operation. Retry with the same endpoint, request body, and key to receive the original result without repeating the operation. Use a new key for a new operation, including confirmation after creation.",
  "schema": {
    "type": "string",
    "maxLength": 255,
    "examples": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }
}
```

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MappedPayoutRequest"
      }
    }
  }
}
```

## Responses

### 201

```json
{
  "description": "Payout created with status PENDING_CONFIRMATION and commercial terms valid until termsExpireAt.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Payment"
      }
    }
  }
}
```

### 400

```json
{
  "description": "Malformed or invalid request.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            },
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Malformed JSON body": {
          "summary": "Malformed JSON body",
          "value": {
            "code": 400,
            "message": "Bad Request",
            "errors": {
              "message": "Failed to parse the request body as JSON: expected value at line 1 column 5"
            }
          }
        },
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 400,
            "message": "Invalid cursor",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 401

```json
{
  "description": "Missing, expired, or invalid credentials.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 403

```json
{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 404

```json
{
  "description": "Resource not found or not accessible to this integration.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the missing or inaccessible resource."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 422

```json
{
  "description": "The map or resulting payout data failed validation. Archived maps return payment_data_map_archived at paymentDataMapId. Unrecognized controlled values return unmapped_value at the original request field. Parameters identify the canonical target path and map. Other validation errors use the standard field-error shape.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "`Invalid Parameters` for validation failures; the rejection reason otherwise."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "For validation failures, keys follow the request fields and values contain field errors or nested errors. Business rejections return `null`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ValidationFieldErrors"
            }
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Archived map": {
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "paymentDataMapId": [
                {
                  "code": "payment_data_map_archived",
                  "message": "This map is archived and cannot be used for new payouts.",
                  "params": {
                    "paymentDataMapId": "d2a1c7e4-9b3f-4e6a-8c5d-1f0b2a3c4d5e"
                  }
                }
              ]
            }
          }
        },
        "Unmapped purpose": {
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "payment.instruction.reason": [
                {
                  "code": "unmapped_value",
                  "message": "No saved translation matches this value.",
                  "params": {
                    "value": "new purpose label",
                    "targetPath": "purpose",
                    "paymentDataMapId": "d2a1c7e4-9b3f-4e6a-8c5d-1f0b2a3c4d5e"
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
}
```

### 500

```json
{
  "description": "Unexpected server error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

## Operation metadata

```json
{
  "tags": [
    "Payouts"
  ],
  "operationId": "createMappedPayout",
  "x-axiym-navigation-order": 30
}
```

## Referenced definitions

- [`#/components/parameters/RequestId`](#definition-1)
- [`#/components/parameters/IdempotencyKey`](#definition-2)
- [`#/components/schemas/MappedPayoutRequest`](#definition-3)
- [`#/components/schemas/Payment`](#definition-4)
- [`#/components/schemas/AccountRef`](#definition-5)
- [`#/components/schemas/Currency`](#definition-6)
- [`#/components/schemas/PaymentRailsCode`](#definition-7)
- [`#/components/schemas/PaymentStatus`](#definition-8)
- [`#/components/schemas/Money`](#definition-9)
- [`#/components/schemas/Decimal`](#definition-10)
- [`#/components/schemas/Sender`](#definition-11)
- [`#/components/schemas/CountryCode`](#definition-12)
- [`#/components/schemas/PartyAddress`](#definition-13)
- [`#/components/schemas/PartyContact`](#definition-14)
- [`#/components/schemas/PartyIdentification`](#definition-15)
- [`#/components/schemas/PartyIdentificationType`](#definition-16)
- [`#/components/schemas/SupportingDocument`](#definition-17)
- [`#/components/schemas/SupportingDocumentType`](#definition-18)
- [`#/components/schemas/PartyRelationship`](#definition-19)
- [`#/components/schemas/RelationshipRole`](#definition-20)
- [`#/components/schemas/Recipient`](#definition-21)
- [`#/components/schemas/BusinessRelationship`](#definition-22)
- [`#/components/schemas/Destination`](#definition-23)
- [`#/components/schemas/BankDestination`](#definition-24)
- [`#/components/schemas/Bank`](#definition-25)
- [`#/components/schemas/BankAddress`](#definition-26)
- [`#/components/schemas/WalletDestination`](#definition-27)
- [`#/components/schemas/Network`](#definition-28)
- [`#/components/schemas/SourceOfFunds`](#definition-29)
- [`#/components/schemas/TransactionPurpose`](#definition-30)
- [`#/components/responses/BadRequest`](#definition-31)
- [`#/components/responses/Unauthorized`](#definition-32)
- [`#/components/responses/Forbidden`](#definition-33)
- [`#/components/responses/NotFound`](#definition-34)
- [`#/components/schemas/ValidationFieldErrors`](#definition-35)
- [`#/components/schemas/ValidationError`](#definition-36)
- [`#/components/responses/InternalError`](#definition-37)

### definition-1

`#/components/parameters/RequestId`

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional request identifier for tracing and support. A UUID is recommended. Axiym echoes it in `X-Request-Id`, or generates one when omitted.",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

### definition-2

`#/components/parameters/IdempotencyKey`

```json
{
  "name": "Idempotency-Key",
  "in": "header",
  "required": true,
  "description": "Identifies one state-changing operation. Retry with the same endpoint, request body, and key to receive the original result without repeating the operation. Use a new key for a new operation, including confirmation after creation.",
  "schema": {
    "type": "string",
    "maxLength": 255,
    "examples": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }
}
```

### definition-3

`#/components/schemas/MappedPayoutRequest`

```json
{
  "type": "object",
  "description": "A saved map identifier and one complete payment object in your agreed source structure. The map prepares the strict Axiym payout input, including payment details, parties, documents, and exactly one fixed amount. The prepared result must meet current corridor requirements.",
  "additionalProperties": false,
  "required": [
    "paymentDataMapId",
    "payment"
  ],
  "properties": {
    "paymentDataMapId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the ACTIVE, immutable Payment Data Map defining how payment is transformed."
    },
    "payment": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": true,
      "description": "Your complete payment JSON. Field names and nesting follow the saved map; values and array lengths may vary between payouts. Include all data required to produce the Axiym payout input and satisfy the corridor. Input types must match mapped destination types. Unmapped source fields are ignored. JSON property order does not matter. The names in the example are illustrative, not required fields."
    }
  },
  "examples": [
    {
      "paymentDataMapId": "d2a1c7e4-9b3f-4e6a-8c5d-1f0b2a3c4d5e",
      "payment": {
        "instruction": {
          "account": "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e",
          "total": "1000.00",
          "currency": "USD",
          "reason": "supplier invoice",
          "funding": "business income",
          "reference": "INV-1042"
        },
        "beneficiary": {
          "name": "Example Supplier Corporation",
          "relationship": "supplier",
          "address": {
            "line": "Ayala Avenue",
            "city": "Makati",
            "country": "PH"
          },
          "account": {
            "number": "1234567890",
            "currency": "PHP",
            "bank": {
              "name": "Example Bank",
              "swift": "BNORPHMM",
              "country": "PH"
            }
          }
        },
        "files": [
          {
            "ownerId": "INV-1042",
            "usage": "payment",
            "kind": "invoice",
            "fileName": "INV-1042.pdf",
            "content": "JVBERi0xLjQKJSBBeGl5bSBleGFtcGxlCg=="
          }
        ]
      }
    }
  ]
}
```

### definition-4

`#/components/schemas/Payment`

```json
{
  "type": "object",
  "description": "Common response document for an outgoing payment. Confirmation authorizes this exact document and reserves `sourceAmount`.",
  "additionalProperties": false,
  "required": [
    "paymentId",
    "code",
    "status",
    "sourceAccount",
    "sourceAmount",
    "destinationAmount",
    "fee",
    "sender",
    "recipient",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "paymentId": {
      "type": "string",
      "format": "uuid",
      "description": "Payment identifier (UUID)."
    },
    "sourceAccount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountRef"
        }
      ],
      "description": "Axiym account funding the payment."
    },
    "externalReference": {
      "type": "string",
      "description": "Your reference supplied when the payment was created."
    },
    "status": {
      "$ref": "#/components/schemas/PaymentStatus"
    },
    "sourceAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount debited from the source account, in the source account currency."
    },
    "destinationAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount delivered to the recipient, in the destination currency."
    },
    "rate": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Decimal"
        }
      ],
      "description": "Exchange rate applied to `sourceAmount` less `fee` to obtain `destinationAmount`: units of the destination currency for one unit of the source currency. Omitted when no conversion applies."
    },
    "fee": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Total deducted from `sourceAmount` before delivery, in the source account currency."
    },
    "termsExpireAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the unconfirmed commercial terms expire. A payment still in `PENDING_CONFIRMATION` at this time moves to `CANCELED` with `reasonCode: TERMS_EXPIRED`."
    },
    "code": {
      "type": "string",
      "description": "System payment code, assigned at creation and shown in the account statement.",
      "examples": [
        "AXI00000420"
      ]
    },
    "reasonCode": {
      "type": "string",
      "description": "Reason the payment was canceled or rejected, when present. `TERMS_EXPIRED` means it was not confirmed before `termsExpireAt`.",
      "examples": [
        "TERMS_EXPIRED"
      ]
    },
    "sender": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Sender"
        }
      ],
      "description": "The paying party — the account holder, or the third party the payment is made on behalf of."
    },
    "recipient": {
      "$ref": "#/components/schemas/Recipient"
    },
    "sourceOfFunds": {
      "$ref": "#/components/schemas/SourceOfFunds",
      "description": "Origin of the funds used for this payment, using the canonical Axiym code. Present when supplied during payout creation."
    },
    "purpose": {
      "$ref": "#/components/schemas/TransactionPurpose"
    },
    "reference": {
      "type": "string",
      "description": "Text shown to the recipient, as submitted."
    },
    "supportingDocuments": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SupportingDocument"
      },
      "description": "Documents accepted with the payment. File content is not returned."
    },
    "transactionHash": {
      "type": "string",
      "description": "Transaction hash for an on-chain payment, once available."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time the payment was created, in ISO 8601 format."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time the payment was last updated, in ISO 8601 format."
    }
  },
  "examples": [
    {
      "paymentId": "c3d65312-6575-43de-b8ae-728d8d0a9371",
      "code": "AXI00000420",
      "sourceAccount": {
        "accountId": "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e",
        "currency": "USD",
        "paymentRails": "ZENUS_BANK"
      },
      "externalReference": "PAYOUT-2026-001",
      "status": "PENDING_CONFIRMATION",
      "sourceAmount": {
        "amount": "1010.00",
        "currency": "USD"
      },
      "fee": {
        "amount": "10.00",
        "currency": "USD"
      },
      "destinationAmount": {
        "amount": "56500.00",
        "currency": "PHP"
      },
      "rate": "56.5000",
      "termsExpireAt": "2026-09-07T10:05:00Z",
      "sender": {
        "name": "Acme Pte. Ltd.",
        "countryOfIncorporation": "SG",
        "address": {
          "streetName": "1 Raffles Place",
          "city": "Singapore",
          "postalCode": "048616",
          "country": "SG"
        },
        "contact": {
          "email": "payments@acme.example",
          "phoneNumber": "+6591234567"
        },
        "identification": {
          "type": "REGISTRATION_NUMBER",
          "number": "202612345N",
          "country": "SG",
          "documents": [
            {
              "documentType": "REGISTRY_EXTRACT",
              "fileId": "6c1d0e42-8b7a-4f39-9d21-3a5e7c9b1f08",
              "name": "acme-registry-extract.pdf",
              "contentType": "application/pdf",
              "size": 96311
            }
          ]
        },
        "relationships": [
          {
            "role": "UBO",
            "firstName": "Alex",
            "lastName": "Tan",
            "nationalities": [
              "SG"
            ],
            "address": {
              "streetName": "10 Anson Road",
              "city": "Singapore",
              "postalCode": "079903",
              "country": "SG"
            },
            "identification": {
              "type": "PASSPORT",
              "number": "E1234567A",
              "country": "SG"
            }
          }
        ]
      },
      "recipient": {
        "businessRelationship": "SUPPLIER",
        "name": "Manila Software Services Inc.",
        "countryOfIncorporation": "PH",
        "address": {
          "streetName": "6789 Ayala Avenue",
          "city": "Makati",
          "postalCode": "1226",
          "country": "PH"
        },
        "contact": {
          "email": "accounts@manilasoftware.example",
          "phoneNumber": "+639171234567"
        },
        "destination": {
          "accountNumber": "123456789012",
          "currency": "PHP",
          "bank": {
            "bankName": "Example Bank Philippines",
            "address": {
              "country": "PH"
            },
            "swiftBic": "BNORPHMMXXX"
          }
        }
      },
      "sourceOfFunds": "BUSINESS_INCOME",
      "purpose": "SERVICES_PAYMENT",
      "reference": "INV-2026-0917",
      "supportingDocuments": [
        {
          "documentType": "INVOICE",
          "fileId": "0f6a2c91-4b7e-4d31-9c58-2e8a1f6b3d40",
          "name": "INV-2026-0917.pdf",
          "contentType": "application/pdf",
          "size": 184233
        }
      ],
      "createdAt": "2026-09-07T10:00:00Z",
      "updatedAt": "2026-09-07T10:00:00Z"
    }
  ]
}
```

### definition-5

`#/components/schemas/AccountRef`

```json
{
  "type": "object",
  "description": "Compact account reference. Fetch the account via `GET /accounts/{accountId}` for the current balance and status; deposit instructions serve its payment details.",
  "required": [
    "accountId",
    "currency",
    "paymentRails"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "format": "uuid",
      "description": "Account identifier (UUID).",
      "examples": [
        "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Account currency.",
      "examples": [
        "USD"
      ]
    },
    "paymentRails": {
      "$ref": "#/components/schemas/PaymentRailsCode",
      "description": "Rail the account settles on.",
      "examples": [
        "ZENUS_BANK"
      ]
    }
  }
}
```

### definition-6

`#/components/schemas/Currency`

```json
{
  "type": "string",
  "description": "Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC).",
  "examples": [
    "USD"
  ]
}
```

### definition-7

`#/components/schemas/PaymentRailsCode`

```json
{
  "type": "string",
  "description": "Code identifying the payment rail connected to the Axiym account, such as `ZENUS_BANK` or `TRON`. This is separate from the method used to deliver a payout.",
  "examples": [
    "ZENUS_BANK"
  ]
}
```

### definition-8

`#/components/schemas/PaymentStatus`

```json
{
  "type": "string",
  "description": "- `PENDING_CONFIRMATION` — created with time-limited terms and awaiting confirmation. No funds are reserved.\n- `PENDING` — confirmed and awaiting or undergoing execution.\n- `HELD` — temporarily on hold; no action is required unless Axiym requests information.\n- `COMPLETED` — delivered successfully.\n- `CANCELED` or `REJECTED` — not completed; see `reasonCode` when present.",
  "enum": [
    "PENDING_CONFIRMATION",
    "PENDING",
    "HELD",
    "COMPLETED",
    "CANCELED",
    "REJECTED"
  ],
  "examples": [
    "PENDING_CONFIRMATION"
  ]
}
```

### definition-9

`#/components/schemas/Money`

```json
{
  "type": "object",
  "description": "Monetary amount and its currency.",
  "additionalProperties": false,
  "required": [
    "amount",
    "currency"
  ],
  "properties": {
    "amount": {
      "$ref": "#/components/schemas/Decimal"
    },
    "currency": {
      "$ref": "#/components/schemas/Currency"
    }
  }
}
```

### definition-10

`#/components/schemas/Decimal`

```json
{
  "type": "string",
  "description": "Decimal number serialized as a string to preserve precision.",
  "examples": [
    "1000.00"
  ]
}
```

### definition-11

`#/components/schemas/Sender`

```json
{
  "type": "object",
  "description": "Sender details stored in the prepared payment instruction, using Axiym field names and codes.",
  "additionalProperties": false,
  "required": [
    "name",
    "countryOfIncorporation",
    "address",
    "contact",
    "identification",
    "relationships"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "countryOfIncorporation": {
      "$ref": "#/components/schemas/CountryCode"
    },
    "address": {
      "$ref": "#/components/schemas/PartyAddress"
    },
    "contact": {
      "$ref": "#/components/schemas/PartyContact"
    },
    "identification": {
      "$ref": "#/components/schemas/PartyIdentification"
    },
    "relationships": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PartyRelationship"
      }
    },
    "documents": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SupportingDocument"
      },
      "description": "Documents about the party. File content is not returned."
    }
  }
}
```

### definition-12

`#/components/schemas/CountryCode`

```json
{
  "type": "string",
  "pattern": "^[A-Z]{2}$",
  "description": "ISO 3166-1 alpha-2 country code.",
  "examples": [
    "US"
  ]
}
```

### definition-13

`#/components/schemas/PartyAddress`

```json
{
  "type": "object",
  "description": "Structured postal address. `streetName` accepts the full primary address line; a separate `buildingNumber` is optional. See the field descriptions for supported address forms.",
  "additionalProperties": false,
  "required": [
    "streetName",
    "city",
    "country"
  ],
  "properties": {
    "streetName": {
      "type": "string",
      "minLength": 1,
      "description": "Primary address line. It may contain a street and number, a PO box, or a building or lot description when no street address applies.",
      "examples": [
        "MG Road"
      ]
    },
    "buildingNumber": {
      "type": "string",
      "examples": [
        "14"
      ]
    },
    "city": {
      "type": "string",
      "minLength": 1
    },
    "region": {
      "type": "string"
    },
    "postalCode": {
      "type": "string"
    },
    "country": {
      "$ref": "#/components/schemas/CountryCode"
    }
  }
}
```

### definition-14

`#/components/schemas/PartyContact`

```json
{
  "type": "object",
  "description": "Contact details for a sender, recipient, or related individual.",
  "additionalProperties": false,
  "required": [
    "email",
    "phoneNumber"
  ],
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "phoneNumber": {
      "type": "string",
      "pattern": "^\\+[1-9][0-9]{7,14}$",
      "description": "International phone number in E.164 format."
    }
  }
}
```

### definition-15

`#/components/schemas/PartyIdentification`

```json
{
  "type": "object",
  "description": "Identification details returned in the prepared payment instruction.",
  "additionalProperties": false,
  "required": [
    "type",
    "number"
  ],
  "properties": {
    "type": {
      "$ref": "#/components/schemas/PartyIdentificationType"
    },
    "number": {
      "type": "string",
      "minLength": 1
    },
    "country": {
      "$ref": "#/components/schemas/CountryCode"
    },
    "issueDate": {
      "type": "string",
      "format": "date"
    },
    "expiryDate": {
      "type": "string",
      "format": "date"
    },
    "documents": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SupportingDocument"
      },
      "description": "Documents evidencing this identification. File content is not returned."
    }
  }
}
```

### definition-16

`#/components/schemas/PartyIdentificationType`

```json
{
  "type": "string",
  "description": "Identification document or identifier type. The corridor determines which types are accepted.",
  "enum": [
    "REGISTRATION_NUMBER",
    "TAX_ID",
    "VAT_NUMBER",
    "NATIONAL_ID",
    "PASSPORT",
    "DRIVER_LICENSE",
    "RESIDENCE_PERMIT",
    "LEI",
    "OTHER"
  ],
  "examples": [
    "REGISTRATION_NUMBER"
  ]
}
```

### definition-17

`#/components/schemas/SupportingDocument`

```json
{
  "type": "object",
  "description": "Metadata of a document accepted with the payment. File content is not returned.",
  "additionalProperties": false,
  "required": [
    "documentType",
    "fileId",
    "name",
    "contentType",
    "size"
  ],
  "properties": {
    "documentType": {
      "$ref": "#/components/schemas/SupportingDocumentType"
    },
    "fileId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the stored file."
    },
    "name": {
      "type": "string",
      "description": "File name supplied with the document."
    },
    "contentType": {
      "type": "string",
      "description": "MIME type detected from the file content.",
      "examples": [
        "application/pdf"
      ]
    },
    "size": {
      "type": "integer",
      "description": "File size in bytes."
    }
  }
}
```

### definition-18

`#/components/schemas/SupportingDocumentType`

```json
{
  "type": "string",
  "description": "Axiym classification of evidence supplied with a payout.",
  "enum": [
    "PASSPORT",
    "NATIONAL_ID",
    "DRIVER_LICENSE",
    "RESIDENCE_PERMIT",
    "PROOF_OF_ADDRESS",
    "UTILITY_BILL",
    "BANK_STATEMENT",
    "TAX_CERTIFICATE",
    "CERTIFICATE_OF_INCORPORATION",
    "REGISTRY_EXTRACT",
    "ARTICLES_OF_ASSOCIATION",
    "SHAREHOLDER_REGISTER",
    "DIRECTOR_REGISTER",
    "UBO_DECLARATION",
    "POWER_OF_ATTORNEY",
    "BOARD_RESOLUTION",
    "REGULATORY_LICENSE",
    "BUSINESS_LICENSE",
    "FINANCIAL_STATEMENT",
    "AUDIT_REPORT",
    "SOURCE_OF_FUNDS",
    "INVOICE",
    "CONTRACT",
    "PURCHASE_ORDER",
    "PAYROLL_FILE",
    "LOAN_AGREEMENT",
    "SHIPPING_DOCUMENT",
    "CUSTOMS_DECLARATION",
    "OTHER"
  ],
  "examples": [
    "INVOICE"
  ]
}
```

### definition-19

`#/components/schemas/PartyRelationship`

```json
{
  "type": "object",
  "description": "Related individual details stored in the prepared payment instruction.",
  "additionalProperties": false,
  "required": [
    "role",
    "firstName",
    "lastName",
    "nationalities",
    "address",
    "identification"
  ],
  "properties": {
    "role": {
      "$ref": "#/components/schemas/RelationshipRole"
    },
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "nationalities": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CountryCode"
      }
    },
    "address": {
      "$ref": "#/components/schemas/PartyAddress"
    },
    "identification": {
      "$ref": "#/components/schemas/PartyIdentification"
    }
  }
}
```

### definition-20

`#/components/schemas/RelationshipRole`

```json
{
  "type": "string",
  "description": "Canonical role of an individual in relation to the party.",
  "enum": [
    "UBO",
    "DIRECTOR",
    "OFFICER",
    "SHAREHOLDER",
    "AUTHORIZED_SIGNATORY",
    "EMPLOYEE_OF",
    "OTHER_RELATIONSHIP"
  ],
  "examples": [
    "UBO"
  ]
}
```

### definition-21

`#/components/schemas/Recipient`

```json
{
  "type": "object",
  "description": "The party receiving the payment and its destination account, with canonical controlled values. `recipientId` is present when the recipient comes from the address book.",
  "additionalProperties": false,
  "required": [
    "businessRelationship",
    "name",
    "address",
    "destination"
  ],
  "properties": {
    "recipientId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book recipient identifier, when the payment uses a stored recipient."
    },
    "businessRelationship": {
      "$ref": "#/components/schemas/BusinessRelationship"
    },
    "name": {
      "type": "string"
    },
    "countryOfIncorporation": {
      "$ref": "#/components/schemas/CountryCode"
    },
    "address": {
      "$ref": "#/components/schemas/PartyAddress"
    },
    "contact": {
      "$ref": "#/components/schemas/PartyContact"
    },
    "identification": {
      "$ref": "#/components/schemas/PartyIdentification"
    },
    "relationships": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PartyRelationship"
      }
    },
    "destination": {
      "$ref": "#/components/schemas/Destination"
    },
    "documents": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SupportingDocument"
      },
      "description": "Documents about the recipient. File content is not returned."
    }
  }
}
```

### definition-22

`#/components/schemas/BusinessRelationship`

```json
{
  "type": "string",
  "description": "Relationship of the recipient to the sender.",
  "enum": [
    "SUPPLIER",
    "CUSTOMER",
    "CONTRACTOR",
    "SERVICE_PROVIDER",
    "GROUP_COMPANY",
    "SUBSIDIARY",
    "PARENT",
    "INVESTMENT_TARGET",
    "DEBTOR",
    "CREDITOR",
    "OTHER"
  ],
  "examples": [
    "SUPPLIER"
  ]
}
```

### definition-23

`#/components/schemas/Destination`

```json
{
  "description": "Where the funds are delivered, as recorded on the operation at creation time. This is a snapshot: it carries the account or wallet details and, when the destination was taken from the address book, its `destinationId`. It does not carry the address book entry's status or creation date; read the address book entry for its current state.\n\n- A bank destination contains `accountNumber` and `bank`.\n- A wallet destination contains `walletAddress` and `network`.\n\nThe two field sets never appear together.",
  "oneOf": [
    {
      "$ref": "#/components/schemas/BankDestination"
    },
    {
      "$ref": "#/components/schemas/WalletDestination"
    }
  ]
}
```

### definition-24

`#/components/schemas/BankDestination`

```json
{
  "type": "object",
  "title": "Bank account",
  "required": [
    "currency",
    "accountNumber",
    "bank"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry the destination was taken from, when applicable.",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency delivered to the destination.",
      "examples": [
        "USD"
      ]
    },
    "accountNumber": {
      "type": "string",
      "description": "Bank account number or IBAN.",
      "examples": [
        "0123456789"
      ]
    },
    "bank": {
      "$ref": "#/components/schemas/Bank",
      "description": "Destination bank details."
    }
  }
}
```

### definition-25

`#/components/schemas/Bank`

```json
{
  "type": "object",
  "description": "Receiving bank details returned with the payout, including the applicable clearing system.",
  "additionalProperties": false,
  "required": [
    "bankName",
    "address"
  ],
  "properties": {
    "bankName": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/BankAddress"
    },
    "swiftBic": {
      "type": "string"
    },
    "clearingCode": {
      "type": "string"
    },
    "clearingSystemCode": {
      "type": "string",
      "description": "Clearing system used for bank routing, resolved from the bank country and supplied routing details.",
      "examples": [
        "INFSC"
      ]
    }
  }
}
```

### definition-26

`#/components/schemas/BankAddress`

```json
{
  "type": "object",
  "description": "Receiving bank address. Its country identifies the payout's destination country and determines the applicable bank-routing requirements. Supply additional address fields when required by the corridor.",
  "additionalProperties": false,
  "properties": {
    "streetName": {
      "type": "string",
      "description": "Primary address line. It may contain a street and number, a PO box, or a building or lot description when no street address applies."
    },
    "buildingNumber": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "region": {
      "type": "string"
    },
    "postalCode": {
      "type": "string"
    },
    "country": {
      "$ref": "#/components/schemas/CountryCode"
    }
  },
  "required": [
    "country"
  ]
}
```

### definition-27

`#/components/schemas/WalletDestination`

```json
{
  "type": "object",
  "title": "Wallet address",
  "required": [
    "currency",
    "walletAddress",
    "network"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry the destination was taken from, when applicable.",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency delivered to the destination.",
      "examples": [
        "USDT"
      ]
    },
    "walletAddress": {
      "type": "string",
      "description": "Wallet address on the given network.",
      "examples": [
        "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    }
  }
}
```

### definition-28

`#/components/schemas/Network`

```json
{
  "type": "string",
  "description": "Blockchain network of a wallet address.",
  "enum": [
    "TRON",
    "AVALANCHE"
  ]
}
```

### definition-29

`#/components/schemas/SourceOfFunds`

```json
{
  "type": "string",
  "description": "Origin of the sender's funds used for this payment. Use BUSINESS_INCOME for general business income not covered by a more specific category. INVESTMENT_INCOME covers investment returns such as interest and dividends; proceeds from selling investments use SALE_OF_OTHER_ASSETS. CAPITAL_CONTRIBUTION covers equity funding; shareholder and intercompany loans use LOAN_PROCEEDS.",
  "enum": [
    "BUSINESS_INCOME",
    "SALE_OF_GOODS",
    "SALE_OF_SERVICES",
    "COMMISSION",
    "RENTAL_INCOME",
    "INVESTMENT_INCOME",
    "LOAN_PROCEEDS",
    "CAPITAL_CONTRIBUTION",
    "SALE_OF_REAL_ESTATE",
    "SALE_OF_OTHER_ASSETS",
    "GRANT",
    "DONATION",
    "INSURANCE_PAYOUT"
  ],
  "examples": [
    "BUSINESS_INCOME"
  ]
}
```

### definition-30

`#/components/schemas/TransactionPurpose`

```json
{
  "type": "string",
  "description": "Reason for the payment. Each code corresponds to one ISO 20022 purpose code (ExternalPurpose1Code). SERVICES_PAYMENT covers every kind of service, including contractor, IT, legal and financial services. OWN_ACCOUNT_TRANSFER is between accounts of the same legal entity; INTERCOMPANY_TRANSFER is between separate companies in a group; TREASURY_MANAGEMENT is a group treasury operation. LOAN_REPAYMENT covers principal; INTEREST_PAYMENT covers interest. INVESTMENT is a financial investment; a property purchase uses REAL_ESTATE_PURCHASE. OTHER covers purposes outside the listed codes. Accepted purposes depend on the selected corridor.",
  "enum": [
    "GOODS_PURCHASE",
    "SERVICES_PAYMENT",
    "SUPPLIER_PAYMENT",
    "SALARY_PAYROLL",
    "RENT_LEASE",
    "LOAN_DISBURSEMENT",
    "LOAN_REPAYMENT",
    "INTEREST_PAYMENT",
    "INTERCOMPANY_TRANSFER",
    "OWN_ACCOUNT_TRANSFER",
    "TREASURY_MANAGEMENT",
    "TAX_PAYMENT",
    "INVESTMENT",
    "REAL_ESTATE_PURCHASE",
    "INSURANCE_PAYMENT",
    "BUSINESS_EXPENSES",
    "EDUCATION_TRAINING_FEES",
    "SUBSCRIPTION_MEMBERSHIP_FEES",
    "ROYALTY_LICENSE_FEES",
    "CHARITABLE_DONATION",
    "REFUND",
    "OTHER"
  ],
  "examples": [
    "GOODS_PURCHASE"
  ]
}
```

### definition-31

`#/components/responses/BadRequest`

```json
{
  "description": "Malformed or invalid request.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            },
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Malformed JSON body": {
          "summary": "Malformed JSON body",
          "value": {
            "code": 400,
            "message": "Bad Request",
            "errors": {
              "message": "Failed to parse the request body as JSON: expected value at line 1 column 5"
            }
          }
        },
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 400,
            "message": "Invalid cursor",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-32

`#/components/responses/Unauthorized`

```json
{
  "description": "Missing, expired, or invalid credentials.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-33

`#/components/responses/Forbidden`

```json
{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-34

`#/components/responses/NotFound`

```json
{
  "description": "Resource not found or not accessible to this integration.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the missing or inaccessible resource."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-35

`#/components/schemas/ValidationFieldErrors`

```json
{
  "description": "Nested validation errors keyed by field name or array index. Leaf values are arrays of `ValidationError` objects.",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationError"
      }
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/ValidationFieldErrors"
      },
      "properties": {}
    }
  ]
}
```

### definition-36

`#/components/schemas/ValidationError`

```json
{
  "type": "object",
  "description": "One field-level validation error.",
  "required": [
    "code",
    "params"
  ],
  "properties": {
    "code": {
      "type": "string",
      "description": "Machine-readable validation rule code, such as `length`, `email`, or `invalid_currency`.",
      "examples": [
        "length"
      ]
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Human-readable message.",
      "examples": [
        "string"
      ]
    },
    "params": {
      "type": "object",
      "description": "Rule-specific parameters, including `value`, the submitted input. Values may contain sensitive data; do not log them without redaction.",
      "properties": {
        "value": {
          "description": "The submitted value that failed validation.",
          "examples": [
            "string"
          ]
        }
      }
    }
  }
}
```

### definition-37

`#/components/responses/InternalError`

```json
{
  "description": "Unexpected server error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Request identifier for tracing and support, echoed from the request or generated by Axiym.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```