> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# MangoPay

> Create MangoPay API keys with the required scopes, then add them to the Portal to ingest settlement and payout data.

<picture noZoom>
  ![MangoPay logo](https://assets.payrails.io/img/logos/mangopay/logo-full-bleed.svg)
</picture>

This guide will help you to obtain API credentials to ingest settlement and payout data from MangoPay into your Payrails account.

## Prerequisites

* A MangoPay account.
* **Role:** Administrator or Developer (required to view/generate API keys and configure permissions).
* Access to the MangoPay Dashboard.
* **Contact:** You must identify the MangoPay account admin to coordinate permissions and report scheduling.

## Environment Selection

When generating your API keys, ensure you are targeting the correct MangoPay environment. Payrails supports both:

* **Sandbox (Test):** `https://api.sandbox.mangopay.com`
* **Production (Live):** `https://api.mangopay.com`

> Note: MangoPay uses separate credentials for each environment. You can configure both in Payrails if needed.

## Step-by-step instructions

### Step 1: Create API keys and Configure Scopes

To create a set of API keys, log in to your MangoPay Dashboard and navigate to the **API** or **Developer** section.

**1. Gather Credentials**

* **Client ID:** Locate your unique MangoPay Client ID.
* **API Key:** Generate a new API Key (often referred to as the "Passphrase" or "Client Password" in some MangoPay contexts).
* **Sandbox Access:** If you have a sandbox account, repeat this process to gather the test credentials for initial integration testing.

**2. Configure Permissions (Scopes)**
Ensure your API key is configured with the following specific scopes to allow Payrails to ingest data:

* **Clients:** `READ` and `WRITE` permissions.
* **Reports:** `Reports` scope (Required for both POST and GET calls to the reports endpoint).
* **Disputes:** `READ` permission on the `Disputes.General` scope (Required if dispute processing is needed).

**3. Verify Reporting Requirements**

* **Data Range:** Confirm availability of historical data (typically 24 to 36 months).

***

### Step 2: Add the credentials to the portal

With the self-serve flow you configure the integration yourself in the Payrails portal. There's no need to share credentials over a vault or PGP-encrypted file.

1. Log in to the Payrails dashboard and open **Settings → Integrations → Data**.
2. Click **Add instance** (top-right).
3. In New instance, select provider: **MangoPay** and click **Continue**.
4. On the **Configure account** screen, fill in:
   * **Account Name:** a unique internal identifier for this instance (e.g. `mangopay_primary`).
   * **Account Display Name:** a human-readable label shown in the Payrails dashboard (e.g. `Mangopay Primary`).
   * **Start Date:** the date of today or tomorrow (currently we can not backfill over the self-serve capability. In the need of backfilling, please reach out to your Payrails account manager).
   * **Client ID:** the MangoPay Client ID gathered in Step 1.
   * **API Key:** the MangoPay API Key (referred as Passphrase/Client Password) gathered in Step 1. This value is masked and stored securely once saved.
5. Click **Save account**. The instance appears in the Data integrations list and Payrails begins ingesting data.


## Related topics

- [Connect your data sources](https://docs.payrails.com/docs/integrations/data-sources.md)
- [PayU](https://docs.payrails.com/docs/integrations/payment-providers/payu.md)
- [QPay](https://docs.payrails.com/docs/integrations/payment-methods/qpay.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.