Create an Intent Refund

Declare the full or partial refund of a payment processed by a third-party PSP

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

Full refund

{   
    "ExternalData": {
        "ExternalProcessingDate": 1769431976,
        "ExternalProviderReference": "refund-stripe-23bdabed-7ba8-488e-822a-ba7d8c8da0d1",
        "ExternalMerchantReference": "order-33419af2-e770-43b8-82ac-512963313811",
        "ExternalProviderName": "Stripe",
        "ExternalProviderPaymentMethod": "MASTERCARD"
    }
}

Full refund

{
    "Id": "int_019bfa5d-33a7-7cd5-9178-627425ff32ee",
    "Amount": 20000,
    "AvailableAmountToSplit": 0,
    "UnfundedAmount": 0,
    "Currency": "EUR",
    "PlatformFeesAmount": 0,
    "Status": "REFUNDED",
    "NextActions": "REVERSE_REFUND",
    "ExternalData": {
        "ExternalProcessingDate": 1769431976,
        "ExternalProviderReference": "refund-stripe-23bdabed-7ba8-488e-822a-ba7d8c8da0d1",
        "ExternalMerchantReference": "order-33419af2-e770-43b8-82ac-512963313811",
        "ExternalProviderName": "Stripe",
        "ExternalProviderPaymentMethod": "MASTERCARD"
    },
    "Buyer": {
        "Id": "user_m_01KF3087EDXEAK8VPD9DTMZW8N"
    },
    "LineItems": [
        {
            "Id": "int_li_019bfa5d-33ae-723e-b257-ce01863b3ce0",
            "TotalLineItemAmount": 10000,
            "CapturedAmount": 10000,
            "RefundedAmount": 10000,
            "DisputedAmount": 0,
            "SplitAmount": 0,
            "CancelledAmount": 0,
            "UnfundedSellerAmount": 0
        },
        {
            "Id": "int_li_019bfa5d-33ae-723e-b257-ce01863b3ce1",
            "TotalLineItemAmount": 10000,
            "CapturedAmount": 10000,
            "RefundedAmount": 10000,
            "DisputedAmount": 0,
            "SplitAmount": 0,
            "CancelledAmount": 0,
            "UnfundedSellerAmount": 0
        }
    ],
    "CreationDate": 1769431970,
    "ExecutionDate": 1769431976,
    "Refund": {
        "Id": "int_refund_019bfa5d-4ad4-79b2-8dcf-5738147affeb"
    }
}

This endpoint allows you to declare that a captured Intent was subject to a refund, in full or in part.

Path parameters

IntentId · string · required

The unique identifier of the Intent.

Body parameters

Full refund

The full Amount of the intent is refunded (all line items) but the ExternalData of the third-party refund must be provided.

ExternalData · object · required

Information about the refund processed by the third-party PSP.

Show child attributes

ExternalProcessingDate · Unix timestamp · required

The date at which the capture was created.

ExternalProviderReference · string · required

The unique identifier of the capture at the provider level.

ExternalMerchantReference · string

The unique identifier of the capture 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 capture.

Partial refund

Part of the original Intent Amount is refunded from one or more line items in a third-party refund (corresponding to the ExternalData). Any amount can be refunded from any line item(s). In this call, the Refund Amount must equal the sum of the LineItems.Amount values sent.

Amount · integer · required

The amount of the Refund, required for a partial refund. The Refund Amount must equal the sum of the Amount values refunded for all line items.

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.

ExternalData · object · required

Information about the refund processed by the third-party PSP.

Show child attributes

ExternalProcessingDate · Unix timestamp · required

The date at which the capture was created.

ExternalProviderReference · string · required

The unique identifier of the capture at the provider level.

ExternalMerchantReference · string

The unique identifier of the capture 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 capture.

LineItems · array (object) · required

Information about the amount refunded for each line item, required for a partial refund.

Hide child attributes

Id · string · required

The unique identifier of the line item in Mangopay ecosystem.

Amount · integer · required

The amount of the refund. The sum of the Refund’s LineItems.Amount values must equal the Amount of the Refund.

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 refund processed by the third-party PSP.

Show child attributes

ExternalProcessingDate · Unix timestamp

The date at which the refund was created.

ExternalProviderReference · string

The unique identifier of the refund at the provider level.

ExternalMerchantReference · string

The unique identifier of the refund 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 refund.

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 line items included in the intent action.

Show child attributes

Id · string

The unique identifier of the line item in Mangopay’s ecosystem.

TotalLineItemAmount · integer

The total amount of the line item calculated as ((UnitAmount x Quantity) - DiscountAmount).

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.

UnfundedSellerAmount · integer

The amount needing to be settled to the Platform’s escrow wallet before the Intent Splits can be executed for this seller.

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.

Refund · object

Information about the Refund.

Show child attributes

Id · string

The unique identifier of the Refund.

Full refund

{
    "Id": "int_019bfa5d-33a7-7cd5-9178-627425ff32ee",
    "Amount": 20000,
    "AvailableAmountToSplit": 0,
    "UnfundedAmount": 0,
    "Currency": "EUR",
    "PlatformFeesAmount": 0,
    "Status": "REFUNDED",
    "NextActions": "REVERSE_REFUND",
    "ExternalData": {
        "ExternalProcessingDate": 1769431976,
        "ExternalProviderReference": "refund-stripe-23bdabed-7ba8-488e-822a-ba7d8c8da0d1",
        "ExternalMerchantReference": "order-33419af2-e770-43b8-82ac-512963313811",
        "ExternalProviderName": "Stripe",
        "ExternalProviderPaymentMethod": "MASTERCARD"
    },
    "Buyer": {
        "Id": "user_m_01KF3087EDXEAK8VPD9DTMZW8N"
    },
    "LineItems": [
        {
            "Id": "int_li_019bfa5d-33ae-723e-b257-ce01863b3ce0",
            "TotalLineItemAmount": 10000,
            "CapturedAmount": 10000,
            "RefundedAmount": 10000,
            "DisputedAmount": 0,
            "SplitAmount": 0,
            "CancelledAmount": 0,
            "UnfundedSellerAmount": 0
        },
        {
            "Id": "int_li_019bfa5d-33ae-723e-b257-ce01863b3ce1",
            "TotalLineItemAmount": 10000,
            "CapturedAmount": 10000,
            "RefundedAmount": 10000,
            "DisputedAmount": 0,
            "SplitAmount": 0,
            "CancelledAmount": 0,
            "UnfundedSellerAmount": 0
        }
    ],
    "CreationDate": 1769431970,
    "ExecutionDate": 1769431976,
    "Refund": {
        "Id": "int_refund_019bfa5d-4ad4-79b2-8dcf-5738147affeb"
    }
}

Full refund

{   
    "ExternalData": {
        "ExternalProcessingDate": 1769431976,
        "ExternalProviderReference": "refund-stripe-23bdabed-7ba8-488e-822a-ba7d8c8da0d1",
        "ExternalMerchantReference": "order-33419af2-e770-43b8-82ac-512963313811",
        "ExternalProviderName": "Stripe",
        "ExternalProviderPaymentMethod": "MASTERCARD"
    }
}