Mangopay Dispute Settlement API

openapi: 3.2.0
info:
  title: Reference Dispute Settlement API
  version: 1.0.0
servers:
- url: https://api.sandbox.mangopay.com
  description: Sandbox
- url: https://api.mangopay.com
  description: Production
- url: https://api-mtls.sandbox.mangopay.com
  description: mTLS Sandbox
- url: https://api-mtls.mangopay.com
  description: mTLS Production
- url: '%7BCardRegistrationUrl%7D'
  description: "The full dynamic URL returned by the Create a Card Registration call, including host, path, and query parameters. \n"
- url: '%7BSettlementFileUploadUrl%7D'
  description: 'The unique URL returned by the [POST Create a Settlement and secure URL](/api-reference/settlements/create-settlement) endpoint.


    **Note:** Use the full dynamic URL including the host, path, and all query parameters. The URL is already authenticated, so this call does not require an Authorization header.

    '
tags:
- name: disputeSettlement
paths:
  /v2.01/{ClientId}/repudiations/{RepudiationId}/settlementtransfer:
    post:
      operationId: disputeSettlement_create_settlement_transfer
      summary: Create a Settlement Transfer
      tags:
      - disputeSettlement
      parameters:
      - name: ClientId
        in: path
        description: Platform's API account identifier, associated with the API key.
        required: true
        schema:
          type: string
      - name: RepudiationId
        in: path
        description: The unique identifier of the repudiation.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementTransferResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateASettlementTransferRequest'
      security:
      - oauth2: []
  /v2.01/{ClientId}/settlements/{SettlementId}:
    get:
      operationId: disputeSettlement_view_settlement_transfer
      summary: View a Settlement Transfer
      description: '**Note – Settlement transfer data retained for 13 months**


        An API call to retrieve a settlement transfer whose `CreationDate` is older than 13 months may return 404 Not Found.


        For more information, see the Data availability periods article.


        View a Settlement Transfer'
      tags:
      - disputeSettlement
      parameters:
      - name: ClientId
        in: path
        description: Platform's API account identifier, associated with the API key.
        required: true
        schema:
          type: string
      - name: SettlementId
        in: path
        description: The unique identifier of the settlement transfer.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementTransferResponse'
      security:
      - oauth2: []
  /v2.01/{ClientId}/clients/payins/bankwire/direct:
    post:
      operationId: disputeSettlement_create_bank_wire_payin_to_repudiation_wallet
      summary: Create a Bank Wire PayIn to the Repudiation Wallet
      description: '**Warning – Ensure you use the correct reference and bank account**


        The direct bank wire relies on independent action from the platform. You must use the `WireReference` and wire the funds to the bank account identified by the `IBAN` and `BIC`.

        Otherwise, the crediting of your Repudiation Wallet may be delayed or unsuccessful.


        Create a Bank Wire PayIn to the Repudiation Wallet


        This endpoint allows the platform to make a Direct Bank Wire PayIn, instead of a Settlement Transfer, to their Repudiation Wallet in order to settle the negative balance due to a `LOST` dispute.


        The object expires 1 month after creation if no funds are received.'
      tags:
      - disputeSettlement
      parameters:
      - name: ClientId
        in: path
        description: Platform's API account identifier, associated with the API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateABankWirePayInToTheRepudiationWalletResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateABankWirePayInToTheRepudiationWalletRequest'
      security:
      - oauth2: []
components:
  schemas:
    CreateABankWirePayInToTheRepudiationWalletResponse:
      type: object
      properties:
        Id:
          $ref: '#/components/schemas/Id'
        Tag:
          $ref: '#/components/schemas/Tag'
        CreationDate:
          $ref: '#/components/schemas/CreationDate'
        ResultCode:
          $ref: '#/components/schemas/ResultCode'
        ResultMessage:
          $ref: '#/components/schemas/ResultMessage'
        AuthorId:
          type: string
          description: The unique identifier of the user at the source of the transaction. In the case of the direct bank wire to the Repudiation Wallet, the `AuthorId` is automatically set to the platform's `ClientId`.
        CreditedUserId:
          type: string
          description: The unique identifier of the user whose wallet is credited. In the case of the direct bank wire to the Repudiation Wallet, the `CreditedUserId` is automatically set to the platform's `ClientId`.
        DebitedFunds:
          $ref: '#/components/schemas/CreateABankWirePayInToTheRepudiationWalletResponseDebitedFunds'
          description: Information about the debited funds.
        CreditedFunds:
          $ref: '#/components/schemas/CreateABankWirePayInToTheRepudiationWalletResponseCreditedFunds'
          description: Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`).
        Fees:
          $ref: '#/components/schemas/CreateABankWirePayInToTheRepudiationWalletResponseFees'
          description: Information about the fees.
        Status:
          $ref: '#/components/schemas/TransactionStatus'
        ExecutionDate:
          $ref: '#/components/schemas/TransactionExecutionDate'
        Type:
          $ref: '#/components/schemas/TransactionType'
        Nature:
          $ref: '#/components/schemas/TransactionNature'
        CreditedWalletId:
          type: string
          description: The unique identifier of the credited wallet. In the case of the direct bank wire to the Repudiation Wallet, this value has the format `CREDIT_CCY` where `CCY` is the currency of the Client Wallet to be credited (e.g., `CREDIT_EUR`).
        DebitedWalletId:
          type: string
          description: 'The unique identifier of the debited wallet.


            In the case of a pay-in, this value is always `null` since there is no debited wallet.'
        PaymentType:
          type: string
          description: '**Returned values:** `BANK_WIRE`


            The payment type of the pay-in.'
        ExecutionType:
          type: string
          description: '**Returned values:** `DIRECT`


            The execution type of the pay-in.'
        DeclaredDebitedFunds:
          $ref: '#/components/schemas/CreateABankWirePayInToTheRepudiationWalletResponseDeclaredDebitedFunds'
          description: Information about the declared debited funds.
        DeclaredFees:
          $ref: '#/components/schemas/CreateABankWirePayInToTheRepudiationWalletResponseDeclaredFees'
          description: Information about the declared fees.
        WireReference:
          type: string
          description: 'Max. length: 255 characters


            The reference which the end user must provide when making the bank wire. The `WireReference` is used to reconcile the funds that arrive on the bank account with the `DeclaredDebitedFunds` in the Direct Bank Wire PayIn object. **Caution:** This reference is specific to each payment and must be retrieved dynamically.'
        BankAccount:
          $ref: '#/components/schemas/CreateABankWirePayInToTheRepudiationWalletResponseBankAccount'
          description: Information about the bank account to which the bank wire must be made by the end user. **Caution:** Do not hardcode the returned values. Mangopay may change the underlying bank details without prior notice.
      title: CreateABankWirePayInToTheRepudiationWalletResponse
    CreateABankWirePayInToTheRepudiationWalletRequestDeclaredDebitedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      required:
      - Currency
      - Amount
      description: Information about the declared funds to be wired by the platform to the returned bank account.
      title: CreateABankWirePayInToTheRepudiationWalletRequestDeclaredDebitedFunds
    SettlementTransferResponseCreditedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`).
      title: SettlementTransferResponseCreditedFunds
    CreateABankWirePayInToTheRepudiationWalletResponseDeclaredDebitedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the declared debited funds.
      title: CreateABankWirePayInToTheRepudiationWalletResponseDeclaredDebitedFunds
    CreateASettlementTransferRequestFees:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      required:
      - Currency
      - Amount
      description: 'Information about the fees. Please note that:


        - The `Currency` must be identical to that of the initial transaction.

        - The `Amount` cannot exceed the initial''s transaction.'
      title: CreateASettlementTransferRequestFees
    Amount:
      type: integer
      description: The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`.
      title: Amount
    SettlementTransferResponseDebitedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: 'Information about the debited funds. Please note that:


        - The `Currency` must be identical to that of the initial transaction.

        - The `Amount` cannot exceed the initial''s transaction minus the fees.'
      title: SettlementTransferResponseDebitedFunds
    CreateABankWirePayInToTheRepudiationWalletResponseDebitedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the debited funds.
      title: CreateABankWirePayInToTheRepudiationWalletResponseDebitedFunds
    TransactionExecutionDate:
      type: integer
      description: Unix timestamp (UTC) of the date and time the status changed to `SUCCEEDED`, indicating that the transaction occurred. The statuses `CREATED` and `FAILED` return an `ExecutionDate` of `null`.
      title: TransactionExecutionDate
    AuthorId:
      type: string
      description: The unique identifier of the user at the source of the transaction.
      title: AuthorId
    SettlementTransferResponseFees:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: 'Information about the fees. Please note that:


        - The `Currency` must be identical to that of the initial transaction.

        - The `Amount` cannot exceed the initial''s transaction.'
      title: SettlementTransferResponseFees
    TransactionStatus:
      type: string
      description: '**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`


        The status of the transaction.'
      title: TransactionStatus
    CreditedUserId:
      type: string
      description: '**Default value:** The unique identifier of the owner of the credited wallet.


        The unique identifier of the user whose wallet is credited.'
      title: CreditedUserId
    ResultMessage:
      type: string
      description: The explanation of the result code.
      title: ResultMessage
    Currency:
      type: string
      description: '**Allowed values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).


        The currency of the amount.'
      title: Currency
    CreateASettlementTransferRequest:
      type: object
      properties:
        AuthorId:
          $ref: '#/components/schemas/AuthorId'
        DebitedFunds:
          $ref: '#/components/schemas/CreateASettlementTransferRequestDebitedFunds'
          description: 'Information about the debited funds. Please note that:


            - The `Currency` must be identical to that of the initial transaction.

            - The `Amount` cannot exceed the initial''s transaction minus the fees.'
        Fees:
          $ref: '#/components/schemas/CreateASettlementTransferRequestFees'
          description: 'Information about the fees. Please note that:


            - The `Currency` must be identical to that of the initial transaction.

            - The `Amount` cannot exceed the initial''s transaction.'
      required:
      - AuthorId
      - DebitedFunds
      - Fees
      title: CreateASettlementTransferRequest
    SettlementTransferResponse:
      type: object
      properties:
        Id:
          $ref: '#/components/schemas/Id'
        Tag:
          $ref: '#/components/schemas/Tag'
        CreationDate:
          $ref: '#/components/schemas/CreationDate'
        ResultCode:
          $ref: '#/components/schemas/ResultCode'
        ResultMessage:
          $ref: '#/components/schemas/ResultMessage'
        DebitedFunds:
          $ref: '#/components/schemas/SettlementTransferResponseDebitedFunds'
          description: 'Information about the debited funds. Please note that:


            - The `Currency` must be identical to that of the initial transaction.

            - The `Amount` cannot exceed the initial''s transaction minus the fees.'
        Fees:
          $ref: '#/components/schemas/SettlementTransferResponseFees'
          description: 'Information about the fees. Please note that:


            - The `Currency` must be identical to that of the initial transaction.

            - The `Amount` cannot exceed the initial''s transaction.'
        AuthorId:
          $ref: '#/components/schemas/AuthorId'
        CreditedUserId:
          $ref: '#/components/schemas/CreditedUserId'
        CreditedFunds:
          $ref: '#/components/schemas/SettlementTransferResponseCreditedFunds'
          description: Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`).
        Status:
          $ref: '#/components/schemas/TransactionStatus'
        ExecutionDate:
          $ref: '#/components/schemas/TransactionExecutionDate'
        Type:
          $ref: '#/components/schemas/TransactionType'
        Nature:
          $ref: '#/components/schemas/TransactionNature'
        CreditedWalletId:
          type: string
          description: The unique identifier of the credited wallet.
        DebitedWalletId:
          type: string
          description: The unique identifier of the debited wallet.
        RepudiationId:
          type: string
          description: The unique identifier of the repudiation.
      title: SettlementTransferResponse
    CreateABankWirePayInToTheRepudiationWalletResponseDeclaredFees:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the declared fees.
      title: CreateABankWirePayInToTheRepudiationWalletResponseDeclaredFees
    Address:
      type: object
      properties:
        AddressLine1:
          type: string
          description: The first line of the address.
        AddressLine2:
          type: string
          description: The second line of the address.
        City:
          type: string
          description: The city of the address.
        Region:
          type: string
          description: Required if `Country` is US, CA, or MX. The region of the address.
        PostalCode:
          type: string
          description: 'The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.'
        Country:
          type: string
          description: 'Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))


            The country of the address.'
      description: The postal address.
      title: Address
    TransactionNature:
      type: string
      description: '**Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT`


        The nature of the transaction, providing more information about the context in which the transaction occurred:

        - `REGULAR` – Relative to most of the transactions (pay-ins, payouts, and transfers) in a usual workflow.

        - `REPUDIATION` – Automatic withdrawal of funds from the platform''s repudiation wallet as part of the dispute process (when the user has requested a chargeback).

        - `REFUND` – Reimbursement of a transaction to the user (pay-in refund), to a wallet (transfer refund), or of a payout (payout refund, only initiated by Mangopay).

        - `SETTLEMENT` – Transfer made to the repudiation wallet by the platform to settle a lost dispute.'
      title: TransactionNature
    CreateABankWirePayInToTheRepudiationWalletResponseFees:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the fees.
      title: CreateABankWirePayInToTheRepudiationWalletResponseFees
    CreateABankWirePayInToTheRepudiationWalletResponseCreditedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`).
      title: CreateABankWirePayInToTheRepudiationWalletResponseCreditedFunds
    Tag:
      type: string
      description: 'Max. length: 255 characters


        Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: `"{\"id_1\":AB123,\"id_2\":DE456}"`.'
      title: Tag
    CreationDate:
      type: integer
      description: Unix timestamp (UTC) of the date and time the object was created.
      title: CreationDate
    Error:
      type: object
      properties:
        Message:
          type: string
          description: Description of the error.
        Type:
          type: string
          description: 'The category of the error.

            '
        Id:
          type: string
          description: Unique identifier of the error instance, useful when contacting Mangopay for support.
        Date:
          type: number
          format: double
          description: Unix timestamp (UTC) of the date and time the error was triggered.
        errors:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: 'Object containing one or more field-level errors.

            '
      description: 'The error body typically returned by the Mangopay API for any non-2xx HTTP status code.

        '
      title: Error
    CreateABankWirePayInToTheRepudiationWalletRequest:
      type: object
      properties:
        CreditedWalletId:
          type: string
          description: The unique identifier of the credited wallet. In the case of the direct bank wire to the Repudiation Wallet, this value has the format `CREDIT_CCY` where `CCY` is the currency of the Client Wallet to be credited (e.g., `CREDIT_EUR`).
        DeclaredDebitedFunds:
          $ref: '#/components/schemas/CreateABankWirePayInToTheRepudiationWalletRequestDeclaredDebitedFunds'
          description: Information about the declared funds to be wired by the platform to the returned bank account.
      required:
      - CreditedWalletId
      - DeclaredDebitedFunds
      title: CreateABankWirePayInToTheRepudiationWalletRequest
    CreateABankWirePayInToTheRepudiationWalletResponseBankAccount:
      type: object
      properties:
        OwnerAddress:
          $ref: '#/components/schemas/Address'
        Type:
          type: string
          description: '**Returned values:** `IBAN`, `US`, `CA`, `GB`, `OTHER`


            The type of the bank account.'
        OwnerName:
          type: string
          description: The full name of the owner of the bank account.
        IBAN:
          type: string
          description: The IBAN (international bank account number) for the bank account.
        BIC:
          type: string
          description: The BIC (international identifier of the bank) for the bank account.
      description: Information about the bank account to which the bank wire must be made by the end user. **Caution:** Do not hardcode the returned values. Mangopay may change the underlying bank details without prior notice.
      title: CreateABankWirePayInToTheRepudiationWalletResponseBankAccount
    CreateASettlementTransferRequestDebitedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      required:
      - Currency
      - Amount
      description: 'Information about the debited funds. Please note that:


        - The `Currency` must be identical to that of the initial transaction.

        - The `Amount` cannot exceed the initial''s transaction minus the fees.'
      title: CreateASettlementTransferRequestDebitedFunds
    Id:
      type: string
      description: 'Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)


        The unique identifier of the object.'
      title: Id
    ResultCode:
      type: string
      description: The code indicating the result of the operation. This information is mostly used to <a href="/errors/codes">handle errors</a> or for filtering purposes.
      title: ResultCode
    TransactionType:
      type: string
      description: '**Returned values:** `PAYIN`, `TRANSFER`, `CONVERSION`, `PAYOUT`


        The type of the transaction.'
      title: TransactionType
  securitySchemes:
    oauth2:
      type: http
      scheme: bearer
      description: "Bearer authentication of the form `Bearer <token>`, where token is your auth token. \n\nIf your platform is using a [proxy](/guides/sca/proxy-management) to take SCA-triggering action on behalf of users, you also need to integrate [mTLS authentication](/guides/sca/platform) and use the `api-mtls` base URL."
x-provenance:
  method: harvested
  publisher: Mangopay
  source: https://docs.mangopay.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)