Sign in

v2

latestOpenAPI 3.1.02026-07-262279731.3 MB
Settlements

View a Settlement

Retrieve the settlement data generated from file upload

get/v3.0/{ClientId}/payins/intents/settlements/{SettlementId}

Path parameters

ClientIdstring required

Platform's API account identifier, associated with the API key.

SettlementIdstring required

The unique identifier of the Settlement object.

Headers

Authorizationstring required

Bearer authentication of the form Bearer <token>, where token is your auth token.

If your platform is using a proxy to take SCA-triggering action on behalf of users, you also need to integrate mTLS authentication and use the api-mtls base URL.

Response

Success

SettlementIdstring

The unique identifier of the Settlement.

Statusstring

The status of the Settlement:

  • PENDING_UPLOAD – Settlement object and SettlementFileUploadUrl generated.
  • UPLOADED – A file was uploaded.
  • CREATED – The uploaded file was considered valid and reconciliation is in progress. A file is considered valid when it includes all required columns and a properly formatted footer.
  • UNMATCHED – None of the entries in the settlement file match the declared intents.
  • PARTIALLY_MATCHED – Settlement file parsed and some lines matched successfully. If at least one line is incorrectly formatted, the file remains in this status and does not progress further. Cancel the Settlement and re-submit.
  • PENDING_FUNDS_RECEPTION – Settlement file parsed and fully matched with Intents; waiting for funds to arrive on the technical wallet.
  • INSUFFICIENT_FUNDS – Partial amount received: FundsMissingAmount shows the shortfall.
  • RECONCILED – Full settlement amount (ActualSettlementAmount) received on the technical wallet.
  • FAILED – Settlement file rejected due to a technical error (e.g. format, timeout).
  • CANCELLED – Settlement file invalidated due to a reconciliation error. Once canceled, no further actions can be taken on this Settlement.

If status becomes FAILED or CANCELLED, then call POST Create a Settlement and secure URL for file upload to create a new object. If the status becomes UNMATCHED or remains in PARTIALLY_MATCHED unexpectedly, then call PUT Update a Settlement and generate a new upload URL only a new URL is required for the existing SettlementId.

CreationDateinteger

The date and time the Settlement was created.

SettlementDateinteger

The creation date of the settlement from the provider.

ExternalProviderNamestring

The supported third-party PSP processing the transaction.

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

DeclaredIntentAmountinteger

The total amount declared through Intent API calls, using the following calculation:

(Sum of captured intents) - (Sum of refunded amounts) + (Sum of refund reversed amounts) - (Sum of DISPUTED disputes) + (Sum of DISPUTED_WON disputes)

ExternalProcessorFeesAmountinteger

The total fees charged by the external provider

ActualSettlementAmountinteger

The total amount due to the platform, to be held in the technical wallet. This amount corresponds to the TotalNetSettlementAmount of the settlement file.

A negative amount results in this parameter being set to zero, indicating no incoming funds to the technical wallet.

FundsMissingAmountinteger

The difference between ActualSettlementAmount and the amount received on the technical wallet

FileNamestring

The FileName submitted to the POST Create a Settlement and generate upload URL endpoint, with a timestamp of the Settlement creation date automatically appended by Mangopay.