---
title: "Create an Intent"
method: POST
path: "/v3.0/{ClientId}/payins/intents"
tags: ["Intents"]
---

# Create an Intent

`POST /v3.0/{ClientId}/payins/intents`

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).

## Path parameters

- `ClientId` string, required

## Headers

- `Authorization` string, required

## Request body

- CreateAnIntentRequest
  - `Amount` integer, required — The full amount authorized in the Intent, which must equal the sum of the total amounts of all `LineItems`.
  - `Currency` string, required — The currency of the intent.
  - `PlatformFeesAmount` 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 `PlatformFeesAmount` value must the sum of all line item `Seller.FeesAmount` values.
  - `ExternalData` ExternalProcessingDateExternalProviderReferenceExternalMerchantReference2, required — Information about the transaction authorization processed by the third-party PSP.
    - `ExternalProcessingDate` integer, required — The date at which the transaction authorization was created.
    - `ExternalProviderReference` string, required — The unique identifier of the transaction at the provider level.
    - `ExternalMerchantReference` string — The unique identifier of the transaction at the merchant level.
    - `ExternalProviderName` 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.
    - `ExternalProviderPaymentMethod` string — One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the transaction.
  - `Buyer` BuyerId — Information about the buyer.
    - `Id` 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`.
  - `LineItems` CreateAnIntentRequestLineItemsItems[], required — Information about the items purchased in the transaction. A maximum of 100 line items can be created per Intent. 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 `PlatformFeesAmount` value.
    - `Seller` AuthorIdWalletIdFeesAmount, required — Information about the seller of the line item.
      - `AuthorId` string — The unique identifier of the seller of the line item. Required if `WalletId` not sent.
      - `WalletId` string — The unique identifier of the wallet to credit the seller's funds. Required if `AuthorId` not sent.
      - `FeesAmount` 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.
      - `TransferDate` integer — The future date when the funds are to be automatically transferred to the seller's wallet.
    - `Sku` string, required — The stock keeping unit (SKU) or other unique identifier of the item.
    - `Name` string — The name of the item.
    - `Description` string — The description of the item.
    - `Quantity` integer, required — The number of units in the line item.
    - `UnitAmount` integer, required — The cost of each unit, including `TaxAmount` and excluding `DiscountAmount`.
    - `TaxAmount` integer — The amount of the `UnitAmount` which is tax.
    - `DiscountAmount` integer — The amount of discount applied to the item.
    - `Category` string — The category of the item, as defined by the platform.
    - `ShippingAddress` CreateAnIntentRequestLineItemsItemsShippingAddress — The shipping address.
      - `AddressLine1` string — The first line of the address.
      - `AddressLine2` string — The second line of the address.
      - `City` string — The city of the address.
      - `Region` string — The region of the address.
      - `PostalCode` string — The postal code of the address.
      - `Country` string — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The country of the address.
    - `SplitOriginWalletId` 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.
  - `Tag` string — Max. length: 255 characters Custom data that you can add to this object.

## Response `200`

Success

- IntentResponse
  - `Id` string — The unique identifier of the intent.
  - `Amount` integer — The full amount authorized in the Intent, which must equal the sum of the total amounts of all `LineItems`.
  - `AvailableAmountToSplit` integer — The remaining amount of the Intent that can be split and transferred to the sellers' wallets.
  - `UnfundedAmount` integer — The amount needing to be settled to the Platform's technical wallet before the Intent Splits can be executed.
  - `Currency` string — The currency of the intent.
  - `PlatformFeesAmount` 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 `PlatformFeesAmount` value must the sum of all line item `Seller.FeesAmount` values.
  - `Status` 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.
  - `NextActions` string — The possible next actions on the intent.
  - `ExternalData` ExternalProcessingDateExternalProviderReferenceExternalMerchantReference — Information about the transaction authorization processed by the third-party PSP.
    - `ExternalProcessingDate` integer — The date at which the transaction authorization was created.
    - `ExternalProviderReference` string — The unique identifier of the transaction at the provider level.
    - `ExternalMerchantReference` string — The unique identifier of the transaction at the merchant level.
    - `ExternalProviderName` 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.
    - `ExternalProviderPaymentMethod` string — One of the [supported payment methods](/api-reference/echo/supported-payment-methods) used to process the transaction.
  - `Buyer` BuyerId — Information about the buyer.
    - `Id` 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`.
  - `LineItems` LineItemsIntent[] — Information about the items purchased in the transaction. A maximum of 100 line items can be created per Intent. 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 `PlatformFeesAmount` value.
    - `Seller` AuthorIdWalletIdFeesAmount — Information about the seller of the line item.
      - `AuthorId` string — The unique identifier of the seller of the line item. Required if `WalletId` not sent.
      - `WalletId` string — The unique identifier of the wallet to credit the seller's funds. Required if `AuthorId` not sent.
      - `FeesAmount` 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.
      - `TransferDate` integer — The future date when the funds are to be automatically transferred to the seller's wallet.
    - `Id` string — The unique identifier of the line item in Mangopay's ecosystem.
    - `Sku` string — The stock keeping unit (SKU) or other unique identifier of the item.
    - `Name` string — The name of the item.
    - `Description` string — The description of the item.
    - `Quantity` integer — The number of units in the line item.
    - `UnitAmount` integer — The cost of each unit, including `TaxAmount` and excluding `DiscountAmount`.
    - `TaxAmount` integer — The amount of the `UnitAmount` which is tax.
    - `DiscountAmount` integer — The amount of discount applied to the line item.
    - `Category` string — The category of the item, as defined by the platform.
    - `ShippingAddress` LineItemsIntentShippingAddress — The shipping address.
      - `AddressLine1` string — The first line of the address.
      - `AddressLine2` string — The second line of the address.
      - `City` string — The city of the address.
      - `Region` string — The region of the address.
      - `PostalCode` string — The postal code of the address.
      - `Country` string — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The country of the address.
    - `CapturedAmount` integer — The item total `CAPTURED` amount
    - `RefundedAmount` integer — The item total `REFUNDED` amount
    - `DisputedAmount` integer — The item total `DISPUTED` amount.
    - `SplitAmount` integer — The item total `COMPLETED` amount.
    - `CancelledAmount` integer — The item total `CANCELLED` amount.
    - `TotalLineItemAmount` integer — The total amount of the line item calculated as ((`UnitAmount` x `Quantity`) - `DiscountAmount`).
    - `UnfundedSellerAmount` integer — The amount needing to be settled to the Platform's technical wallet before the Intent Splits can be executed for this seller.
    - `SplitOriginWalletId` 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.
  - `Tag` string — Max. length: 255 characters Custom data that you can add to this object.
  - `CreationDate` integer — Unix timestamp (UTC) of the date and time the object was created.
  - `ExecutionDate` integer — Unix timestamp (UTC) of the date and time the Intent moved to `AUTHORIZED`.

## Other responses

- `400` — Bad Request

## Changes

- **2026-07-26** `795281070285` — 2 info
  - added the new optional request property `Tag`
  - added the optional property `Tag` to the response with the `200` status

[Change history](https://skmtc.dev/mangopay/apis/api-reference/changes/v3.0/:ClientId/payins/intents/post.md)

---

[API](https://skmtc.dev/mangopay/apis/api-reference.md) · [All operations](https://skmtc.dev/mangopay/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mangopay/api-reference/revisions/fafbd0c69654/schema)