> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an Intent

> Declare a transaction authorization processed by a third-party PSP

This endpoint allows you to declare a payment authorized by a third-party PSP. Once `AUTHORIZED` (as shown by the `Status` in the response), the Intent's `LineItems` can be:

* Captured using [POST Create an Intent Capture](/api-reference/intents/create-intent-capture)
* Canceled using [POST Cancel an Intent](/api-reference/intents/cancel-intent)

In a mixed-basket flow, you can also use this endpoint to add `LineItems` to an existing Intent by sending the same `ExternalData.ExternalProviderReference` as the existing Intent.

In a hybrid flow, where the `ExternalProviderName` is `Mangopay`, you can define the `LineItems.SplitOriginWalletId` in the Intent, otherwise it must be defined on [POST Create an Intent Split](/api-reference/intents/create-intent-split).

### Body parameters

<ParamField body="Amount" type="integer" required>
  The full amount authorized in the Intent, which must equal the sum of the total amounts of all `LineItems`.
</ParamField>

<ParamField body="Currency" type="integer" required>
  The currency of the intent.
</ParamField>

<ParamField body="PlatformFees" type="integer">
  The amount of fees to be diverted to the platform's Fees Wallet when the Intent is split. This value can be overridden when the Split is created.

  The `PlatformFees` value must the sum of all line item `Seller.FeesAmount` values.
</ParamField>

<ParamField body="ExternalData" type="object" required>
  Information about the transaction authorization processed by the third-party PSP.

  <Expandable>
    <ParamField body="ExternalProcessingDate" type="Unix timestamp" required>
      The date at which the transaction authorization was created.
    </ParamField>

    <ParamField body="ExternalProviderReference" type="string" required>
      The unique identifier of the transaction at the provider level.
    </ParamField>

    <ParamField body="ExternalMerchantReference" type="string">
      The unique identifier of the transaction at the merchant level.
    </ParamField>

    <ParamField body="ExternalProviderName" type="string" required>
      The [supported third-party PSP](/api-reference/echo/supported-providers) processing the transaction.

      **Note:** The uppercase value is expected. The API returns the sentence-case value.
    </ParamField>

    <ParamField body="ExternalProviderPaymentMethod" type="string">
      One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the transaction.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="Buyer" type="object">
  Information about the buyer.

  <Expandable>
    <ParamField body="Id" type="string">
      If it exists, the unique identifier of the Mangopay user making the payment via the third-party PSP. Must be a valid Mangopay `UserId`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="LineItems" type="array (object)" required>
  Information about the items purchased in the transaction.

  The sum of all line item amounts must equal the Intent `Amount` value. The total for each line items is calculated as ((`UnitAmount` x `Quantity`) - `DiscountAmount`), which is shown in the `TotalLineItemAmount` returned. The `TaxAmount` is indicative and included in the `UnitAmount`.

  The sum of all line item `Seller.FeesAmount` values must equal the Intent `PlatformFees` value.

  <Expandable>
    <ParamField body="Seller" type="object" required>
      Information about the seller of the line item.

      <Expandable>
        <ParamField body="AuthorId" type="string">
          The unique identifier of the seller of the line item.

          Required if `WalletId` not sent.
        </ParamField>

        <ParamField body="WalletId" type="string">
          The unique identifier of the wallet to credit the seller's funds.

          Required if `AuthorId` not sent.
        </ParamField>

        <ParamField body="FeesAmount" type="integer">
          The amount of fees that will be diverted to the platform's Fees Wallet when the Intent is split. This value can be overridden when the Split is created.
        </ParamField>

        <ParamField body="TransferDate" type="Unix timestamp">
          The future date when the funds are to be automatically transferred to the seller's wallet.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="Sku" type="string" required>
      The stock keeping unit (SKU) or other unique identifier of the item.
    </ParamField>

    <ParamField body="Name" type="string">
      The name of the item.
    </ParamField>

    <ParamField body="Description" type="string">
      The description of the item.
    </ParamField>

    <ParamField body="Quantity" type="integer" required>
      The number of units in the line item.
    </ParamField>

    <ParamField body="UnitAmount" type="integer" required>
      The cost of each unit, including `TaxAmount` and excluding `DiscountAmount`.
    </ParamField>

    <ParamField body="TaxAmount" type="integer">
      The amount of the `UnitAmount` which is tax.
    </ParamField>

    <ParamField body="DiscountAmount" type="integer">
      The amount of discount applied to the item.
    </ParamField>

    <ParamField body="Category" type="string">
      The category of the item, as defined by the platform.
    </ParamField>

    <ParamField body="ShippingAddress" type="object">
      Information about the shipping address.

      <Expandable>
        <ParamField body="AddressLine1" type="string">
          The first line of the address.
        </ParamField>

        <ParamField body="AddressLine2" type="string">
          The second line of the address.
        </ParamField>

        <ParamField body="City" type="string">
          The city of the address
        </ParamField>

        <ParamField body="Region" type="string">
          The region of the address.
        </ParamField>

        <ParamField body="PostalCode" type="string">
          The postal code of the address
        </ParamField>

        <ParamField body="Country" type="string">
          The country of the address
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="Sku" type="string" required>
      The stock keeping unit (SKU) or other unique identifier of the item.
    </ParamField>

    <ParamField body="SplitOriginWalletId" type="string">
      The unique identifier of the wallet from which the split will be debited.

      This parameter is required for Intents where `ExternalProviderName` is `Mangopay`. If it is not defined in the Intent it must be defined at Split creation.
    </ParamField>
  </Expandable>
</ParamField>

### Responses

<AccordionGroup>
  <Accordion title="200 - Response parameters">
    <ResponseField name="Id" type="string">
      The unique identifier of the intent.
    </ResponseField>

    <ResponseField name="Amount" type="integer">
      The full amount authorized in the Intent, which must equal the sum of the total amounts of all `LineItems`.
    </ResponseField>

    <ResponseField name="AvailableAmountToSplit" type="integer">
      The remaining amount of the Intent that can be split and transferred to the sellers' wallets.
    </ResponseField>

    <ResponseField name="UnfundedAmount" type="integer">
      The amount needing to be settled to the Platform's escrow wallet before the Intent Splits can be executed.
    </ResponseField>

    <ResponseField name="Currency" type="integer">
      The currency of the intent.
    </ResponseField>

    <ResponseField name="PlatformFees" type="integer">
      The amount of fees to be diverted to the platform's Fees Wallet when the Intent is split. This value can be overridden when the Split is created.

      The `PlatformFees` value must the sum of all line item `Seller.FeesAmount` values.
    </ResponseField>

    <ResponseField name="Status" type="string">
      The status of the Intent, as declared by the platform through Intent Captures, Refunds (and reversals), or Disputes (and decisions). Where partial actions occur, the top-level Intent `Status` may differ from the `Status` of Intent `LineItems`.

      Intent `Status` values:

      * `AUTHORIZED` – The Intent `Amount` was authorized for acquisition by the PSP and can be captured or canceled.
      * `PARTIALLY_CAPTURED` – Part of the Intent `Amount` from one or more `LineItems` was captured. The other parts are either still available for capture or cancel.
      * `CAPTURED` – All of the Intent `Amount` was captured. Part of it may have been subsequently refunded or disputed.
      * `CANCELLED` – All of the Intent `Amount` was canceled.
      * `REFUNDED` – All of the `CapturedAmount` of all `LineItems` was refunded.
      * `REFUND_REVERSED` – The refund could not be completed and the funds were returned to the platform.
      * `DISPUTED` – All of the `CapturedAmount` of all `LineItems` was disputed.
      * `DEFENDED` – The dispute is being defended by the platform.
      * `DISPUTED_WON` – The dispute was resolved in favor of the platform.
      * `DISPUTED_LOST` – The dispute was resolved against the platform.
    </ResponseField>

    <ResponseField name="NextActions" type="string">
      The possible next actions on the intent.
    </ResponseField>

    <ResponseField name="ExternalData" type="object">
      Information about the transaction authorization processed by the third-party PSP.

      <Expandable>
        <ResponseField name="ExternalProcessingDate" type="Unix timestamp">
          The date at which the transaction authorization was created.
        </ResponseField>

        <ResponseField name="ExternalProviderReference" type="string">
          The unique identifier of the transaction at the provider level.
        </ResponseField>

        <ResponseField name="ExternalMerchantReference" type="string">
          The unique identifier of the transaction at the merchant level.
        </ResponseField>

        <ResponseField name="ExternalProviderName" type="string">
          The [supported third-party PSP](/api-reference/echo/supported-providers) processing the transaction.

          **Note:** The uppercase value is expected. The API returns the sentence-case value.
        </ResponseField>

        <ResponseField name="ExternalProviderPaymentMethod" type="string">
          One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the transaction.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Buyer" type="object">
      Information about the buyer.

      <Expandable>
        <ResponseField name="Id" type="string">
          If it exists, the unique identifier of the Mangopay user making the payment via the third-party PSP. Must be a valid Mangopay `UserId`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="LineItems" type="array (object)">
      Information about the items purchased in the transaction.

      The sum of all line item amounts must equal the Intent `Amount` value. The total for each line items is calculated as ((`UnitAmount` x `Quantity`) - `DiscountAmount`), which is shown in the `TotalLineItemAmount` returned. The `TaxAmount` is indicative and included in the `UnitAmount`.

      The sum of all line item `Seller.FeesAmount` values must equal the Intent `PlatformFees` value.

      <Expandable>
        <ResponseField name="Seller" type="object">
          Information about the seller of the line item.

          <Expandable>
            <ResponseField name="AuthorId" type="string">
              The unique identifier of the seller of the line item.

              Required if `WalletId` not sent.
            </ResponseField>

            <ResponseField name="WalletId" type="string">
              The unique identifier of the wallet to credit the seller's funds.

              Required if `AuthorId` not sent.
            </ResponseField>

            <ResponseField name="FeesAmount" type="integer">
              The amount of fees that will be diverted to the platform's Fees Wallet when the Intent is split. This value can be overridden when the Split is created.
            </ResponseField>

            <ResponseField name="TransferDate" type="Unix timestamp">
              The future date when the funds are to be automatically transferred to the seller's wallet.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="Id" type="string">
          The unique identifier of the line item in Mangopay's ecosystem.
        </ResponseField>

        <ResponseField name="Sku" type="string">
          The stock keeping unit (SKU) or other unique identifier of the item.
        </ResponseField>

        <ResponseField name="Name" type="string">
          The name of the item.
        </ResponseField>

        <ResponseField name="Description" type="string">
          The description of the item.
        </ResponseField>

        <ResponseField name="Quantity" type="integer">
          The number of units in the line item.
        </ResponseField>

        <ResponseField name="UnitAmount" type="integer">
          The cost of each unit, including `TaxAmount` and excluding `DiscountAmount`.
        </ResponseField>

        <ResponseField name="TaxAmount" type="integer">
          The amount of the `UnitAmount` which is tax.
        </ResponseField>

        <ResponseField name="DiscountAmount" type="integer">
          The amount of discount applied to the line item.
        </ResponseField>

        <ResponseField name="Category" type="string">
          The category of the item, as defined by the platform.
        </ResponseField>

        <ResponseField name="ShippingAddress" type="object">
          Information about the shipping address.

          <Expandable>
            <ResponseField name="AddressLine1" type="string">
              The first line of the address.
            </ResponseField>

            <ResponseField name="AddressLine2" type="string">
              The second line of the address.
            </ResponseField>

            <ResponseField name="City" type="string">
              The city of the address
            </ResponseField>

            <ResponseField name="Region" type="string">
              The region of the address.
            </ResponseField>

            <ResponseField name="PostalCode" type="string">
              The postal code of the address
            </ResponseField>

            <ResponseField name="Country" type="string">
              The country of the address
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="CapturedAmount" type="integer">
          The item total `CAPTURED` amount
        </ResponseField>

        <ResponseField name="RefundedAmount" type="integer">
          The item total `REFUNDED` amount
        </ResponseField>

        <ResponseField name="DisputedAmount" type="integer">
          The item total `DISPUTED` amount.
        </ResponseField>

        <ResponseField name="SplitAmount" type="integer">
          The item total `COMPLETED` amount.
        </ResponseField>

        <ResponseField name="CancelledAmount" type="integer">
          The item total `CANCELLED` amount.
        </ResponseField>

        <ResponseField name="TotalLineItemAmount" type="integer">
          The total amount of the line item calculated as ((`UnitAmount` x `Quantity`) - `DiscountAmount`).
        </ResponseField>

        <ResponseField name="UnfundedSellerAmount" type="integer">
          The amount needing to be settled to the Platform's escrow wallet before the Intent Splits can be executed for this seller.
        </ResponseField>

        <ResponseField name="SplitOriginWalletId" type="string">
          The unique identifier of the wallet from which the split will be debited.

          This parameter is required for Intents where `ExternalProviderName` is `Mangopay`. If it is not defined in the Intent it must be defined at Split creation.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="CreationDate" type="string">
      The date and time at which the Intent was created.
    </ResponseField>

    <ResponseField name="ExecutionDate" type="Unix timestamp">
      The date and time at which the Intent moved to `AUTHORIZED`.
    </ResponseField>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="400 - Intent Amount must equal sum of line items' ">
    ```json theme={null}
    {
        "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Id": "21d7dbc4-beea-4ad2-9f2a-471d683c25b5",
        "Date": 1752053748,
        "Type": "param_error",
        "Errors": {
            "Amount": "The total intent amount does not match the sum of the declared LineItem amounts"
        }
    }
    ```
  </Accordion>

  <Accordion title="400 - LineItems.Seller.WalletId currency must match Intent Currency">
    ```json theme={null}
    {
        "Message": "Error: multi-currency usage is not authorized",
        "Id": "3f67b29b-7cd2-41bd-b753-2acec8781a6d",
        "Date": 1756388392,
        "Type": "currency_incompatibility",
        "Errors": {
            "Currency": "The Wallet's currency USD and the Intent's currency EUR must be the same"
        }
    }
    ```
  </Accordion>

  <Accordion title="400 - SplitOriginWalletId not available third-party acquirers">
    ```json theme={null}
    {
        "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Id": "920f6e41-b577-4ce2-b2b3-6bd194da74ee",
        "Date": 1770908446,
        "Type": "param_error",
        "Errors": {
            "SplitOriginWalletId": "The field is only valid for 'Mangopay' provider."
        }
    }
    ```
  </Accordion>
</AccordionGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
      "Id": "int_019bfa4f-60ba-7842-89c0-382066c072f1",
      "Amount": 20000,
      "AvailableAmountToSplit": 0,
      "UnfundedAmount": 0,
      "Currency": "EUR",
      "PlatformFeesAmount": 0,
      "Status": "AUTHORIZED",
      "NextActions": "CAPTURE, PARTIALLY_CAPTURE, CANCEL",
      "ExternalData": {
          "ExternalProcessingDate": 1769431064,
          "ExternalProviderReference": "auth-stripe-36e34fd5-512f-4fb6-b4c2-3084ba3cd947",
          "ExternalMerchantReference": "order-a790c539-9c63-4166-8595-7b78f06e9215",
          "ExternalProviderName": "Stripe",
          "ExternalProviderPaymentMethod": "MASTERCARD"
      },
      "Buyer": {
          "Id": "user_m_01KF3087EDXEAK8VPD9DTMZW8N"
      },
      "LineItems": [
          {
              "Seller": {
                  "AuthorId": "user_m_01JH2Z9GXCCHGFN65T5HDZG4GB",
                  "WalletId": "wlt_m_01KEYE9ZRT7E1Y8QQF7JKYXMXF",
                  "FeesAmount": 0
              },
              "Id": "int_li_019bfa4f-60c5-7306-b993-bf38153edb6f",
              "Sku": "example-item-123",
              "Name": "Example item name",
              "Description": "Example item description",
              "Quantity": 2,
              "UnitAmount": 6000,
              "TaxAmount": 0,
              "DiscountAmount": 2000,
              "Category": "Example category",
              "ShippingAddress": {
                  "AddressLine1": "7765 Cameron Points",
                  "City": "Paris",
                  "Region": "Ile de France",
                  "PostalCode": "75001",
                  "Country": "FR"
              },
              "CapturedAmount": 0,
              "RefundedAmount": 0,
              "DisputedAmount": 0,
              "SplitAmount": 0,
              "CancelledAmount": 0,
              "TotalLineItemAmount": 10000,
              "UnfundedSellerAmount": 0
          },
          {
              "Seller": {
                  "AuthorId": "user_m_01KF3GT68HDXZ4PX9R4XV4E11P",
                  "WalletId": "wlt_m_01K3K8QFMNRKSNED3S3EN8EF2X",
                  "FeesAmount": 0
              },
              "Id": "int_li_019bfa4f-60c5-7306-b993-bf38153edb70",
              "Sku": "example-item-456",
              "Name": "Example item name",
              "Description": "Example item description",
              "Quantity": 1,
              "UnitAmount": 10000,
              "TaxAmount": 0,
              "DiscountAmount": 0,
              "Category": "Example category",
              "ShippingAddress": {
                  "AddressLine1": "181 Griffin Glens",
                  "City": "Paris",
                  "Region": "Ile de France",
                  "PostalCode": "75001",
                  "Country": "FR"
              },
              "CapturedAmount": 0,
              "RefundedAmount": 0,
              "DisputedAmount": 0,
              "SplitAmount": 0,
              "CancelledAmount": 0,
              "TotalLineItemAmount": 10000,
              "UnfundedSellerAmount": 0
          }
      ],
      "CreationDate": 1769431064,
      "ExecutionDate": 1769431064
  }
  ```
</ResponseExample>

<RequestExample>
  ```json JSON theme={null}
  {
      "Amount": 20000,
      "Currency": "EUR",
      "PlatformFeesAmount": 0,
      "ExternalData": {
          "ExternalProcessingDate": 1752057185,
          "ExternalProviderReference": "auth-stripe-633781e6-bb10-4484-8a29-ff6da7d7464a",
          "ExternalMerchantReference": "order-420bbe60-7f62-4e53-9d64-7cb5188c507f",
          "ExternalProviderName": "Stripe",
          "ExternalProviderPaymentMethod": "MASTERCARD"
      },
      "Buyer": {
          "Id": "user_m_01JZB09HSDZRVN60QH1006TK6E"
      },
      "LineItems": [
          {
              "Seller": {
                  "AuthorId": "user_m_01JZJ42M48CGJ19F2FS5WWKBNH",
                  "WalletId": "wlt_m_01JZ5STM3FDSC5G1WWVS4ZCZFJ",
                  "FeesAmount": 0
              },
              "Sku": "example-item-123",
              "Name": "Example item name",
              "Description": "Example item description",
              "Quantity": 2,
              "UnitAmount": 6000,
              "TaxAmount": 0,
              "DiscountAmount": 2000,
              "Category": "Example category",
              "ShippingAddress": {
                  "AddressLine1": "2226 Balistreri Roads",
                  "AddressLine2": null,
                  "City": "Paris",
                  "Region": "Ile de France",
                  "PostalCode": "75001",
                  "Country": "FR"
              }
          },
          {
              "Seller": {
                  "AuthorId": "user_m_01JZAXD3C31Y543SRKNCVK3V5N",
                  "WalletId": "wlt_m_01JZ8DKE83Y06860JZRKAM259V",
                  "FeesAmount": 0
              },
              "Sku": "example-item-456",
              "Name": "Example item name",
              "Description": "Example item description",
              "Quantity": 1,
              "UnitAmount": 10000,
              "TaxAmount": 0,
              "DiscountAmount": 0,
              "Category": "Example category",
              "ShippingAddress": {
                  "AddressLine1": "771 Koch Mews",
                  "AddressLine2": null,
                  "City": "Paris",
                  "Region": "Ile de France",
                  "PostalCode": "75001",
                  "Country": "FR"
              }
          }
      ]
  }
  ```
</RequestExample>