Create an Intent

Declare a transaction authorization processed by a third-party PSP

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

JSON

{
    "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"
            }
        }
    ]
}

200

{
    "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
}

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
• Canceled using POST Cancel an 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.

Body parameters

Amount · integer · required

The full amount authorized in the Intent, which must equal the sum of the total amounts of all LineItems.

Currency · integer · required

The currency of the intent.

PlatformFees · 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.

ExternalData · object · required

Information about the transaction authorization processed by the third-party PSP.

Show child attributes

ExternalProcessingDate · Unix timestamp · 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 processing the transaction.

Note: The uppercase value is expected. The API returns the sentence-case value.

ExternalProviderPaymentMethod · string

One of the supported payment methods used to process the transaction.

Buyer · object

Information about the buyer.

Show child attributes

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

Show child attributes

Seller · object · required

Information about the seller of the line item.

Show child attributes

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 · Unix timestamp

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 · object

Information about the shipping address.

Show child attributes

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

The country of the address

Sku · string · required

The stock keeping unit (SKU) or other unique identifier of the item.

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.

Responses

200 - Response parameters

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 escrow wallet before the Intent Splits can be executed.

Currency · integer

The currency of the intent.

PlatformFees · 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.

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 · object

Information about the transaction authorization processed by the third-party PSP.

Show child attributes

ExternalProcessingDate · Unix timestamp

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 processing the transaction.

Note: The uppercase value is expected. The API returns the sentence-case value.

ExternalProviderPaymentMethod · string

One of the supported payment methods used to process the transaction.

Buyer · object

Information about the buyer.

Show child attributes

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

Show child attributes

Seller · object

Information about the seller of the line item.

Show child attributes

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 · Unix timestamp

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 · object

Information about the shipping address.

Show child attributes

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

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

CreationDate · string

The date and time at which the Intent was created.

ExecutionDate · Unix timestamp

The date and time at which the Intent moved to AUTHORIZED.

400 - Intent Amount must equal sum of line items'

{
    "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"
    }
}

400 - LineItems.Seller.WalletId currency must match Intent Currency

{
    "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"
    }
}

400 - SplitOriginWalletId not available third-party acquirers

{
    "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."
    }
}

200

{
    "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
}

JSON

{
    "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"
            }
        }
    ]
}