🚀 Release #1 - V1.1.0

📚

New API reference v1.1.0 —

https://mipisepaymentservices.readme.io/v1.1/reference/introduction

This release brings major enrichments to the User, Person and Address resources to support enhanced KYC/KYB, AML/CFT (LCB-FT), UBO and FATCA/CRS
requirements. It also introduces automatic credit card commissions, outbound webhook signatures and new webhook events.

📋 At a glance

⚠️ Breaking changes

🚫 Document rejection reason — DOCUMENT_FALSIFIED removed

The reject reason DOCUMENT_FALSIFIED has been replaced by the broader COMPLIANCE_REASON. New rejections will no longer use the old value.

- DOCUMENT_FALSIFIED
+ COMPLIANCE_REASON

🔧

Action required — Update any client filtering or branching on rejection reasons. The change applies to the reject_reasons enum returned on document detail and document list endpoints.

✨ New features

🆔 UBO digitalization

Persons (Ultimate Beneficial Owners and legal representatives) can now be managed through dedicated REST endpoints. UBO information is carried in a new structured role_data object on natural persons.

📍 New endpoints

🧬 role_data object — natural persons only

🏠 Address — structured street components

Three new structured fields are now exposed on the address payload:

• 🔢 number — street number (e.g. "123")
• 🛣️ road_type — street category ("road", "street", "boulevard", …)
• 🏷️ road_name — street name

✅

Backward compatible — nothing breaks today. address_line1 is still accepted on input and still returned on output alongside the new fields. Existing clients keep working for creating, updating and reading addresses, and no validation currently enforces the structured form.

📅

Future direction. The structured fields are intended to replace address_line1. A grace period is in place so platforms can migrate at their own pace; once it ends, address_line1 will be deprecated and the structured form will become required for KYC/KYB. Start populating number / road_type / road_name in your integrations now to be ready.

🪪 LCB-FT user enrichment

A wide set of fields previously unavailable through the API has been opened on persons to support reinforced due-diligence requirements. All fields are accepted on creation and update, and returned in person responses.

👥 Common fields (all person types)

• 💰 annual_revenue — enum of revenue ranges (natural_inf_30000 … legal_sup_50000000)
• 💼 financial_capacity — enum of wealth ranges (natural_inf_50000 … legal_sup_20000000)
• 🌍 country_of_origin — ISO 3166-1 alpha-2
• 💵 source_of_funds — salary_or_professional_income / personal_savings_or_available_funds / capital_income / asset_sale / inheritance_or_donation /
  external_financing / capital_contribution_or_fundraising / other_or_not_disclosed
• ✏️ origin_of_funds_other — free text used when source_of_funds = other_or_not_disclosed
• 🌐 tax_country_code_1 / _2 / _3 — ISO 3166-1 alpha-2
• 🔢 tin_code_1 / _2 / _3 — Tax Identification Number for the matching tax country
• 📝 no_tin_reason_1 / _2 / _3 — alternative to tin_code_* when no TIN is held
• ⭐ is_primary_1 / _2 / _3 — flags the main tax country
• 🤝 is_intermediated_by_third_party — required to validate the user's wallet

👤 Natural-person only

• 👋 civility — mr / mrs / no_gender / unknown
• 📞 phone_number — phone with country code
• 💼 professional_situation — French PCS-2020 code
• 🏙️ birth_city, birth_province — birth location (birth_province enum covers US states, Canadian provinces and Mexican states; required when birth country is US/CA/MX)

🏢 Legal-person only

• 📂 legal_classification_code — French INSEE legal classification
• 🏷️ activity_classification_code — French INSEE activity classification (NAF)
• 📅 registration_date
• 🆔 registration_number — French RCS number (alternative to rna)
• 🆔 rna — French RNA association number (alternative to registration_number)

🇺🇸 FATCA / CRS compliance data

Persons can now carry FATCA and CRS compliance information.

💡

Optional during this release to give agents time to comply. They will become required for KYC/KYB validation in a future release.

📥 Request format — nested under a fatca_crs_data object (depending on the person type):

{
  "type": "Persons::Natural",                                                                                                                                                     
  "fatca_crs_data": {
    "us_citizen_or_resident": false                                                                                                                                               
  }             
}

{
  "type": "Persons::Legal",
  "fatca_crs_data": {                                                                                                                                                             
    "us_legal_us_person": false,
    "is_fatca_fi": false,                                                                                                                                                         
    "is_registered_fatca_fi": false,
    "giin": "98Q96B.00000.LE.250",                                                                                                                                                
    "is_nffe_fatca_active": true,
    "is_nffe_fatca_passive": false,                                                                                                                                               
    "is_crs_fi": false,
    "is_nffe_crs": true                                                                                                                                                           
  }
}                                                                                                                                                                                 

📤 Response format — the same fields are returned flat at the top level of the person object (not nested under fatca_crs_data).

🔗 Conditional rules

• is_registered_fatca_fi is required when is_fatca_fi = true
• giin is required when is_registered_fatca_fi = true

🟢 User qualification status

The user response now exposes the user's compliance lifecycle.

🔔

A new webhook event accompanies this lifecycle: user_qualified (see Webhook events below). The pre-existing user_dequalified event remains unchanged.

💳 Credit card commissions

A commission is now automatically charged on credit card pay-ins, based on the platform's commission settings configured by Mipise.

🛠️ For API consumers

• ✅ No request changes — the commission is computed and applied server-side. Your existing pay-in payloads keep working.
• 🔔 New webhook events — commission_failed and commission_successful allow you to track each commission outcome (see Webhook events below). The commission is delivered as its own financial request of subtype PaymentCommission, separate from the originating pay-in.
• 📦 New response field on credit card pay-ins — monext_credit_card_type: brand of the card used ("VISA", "MASTERCARD", "CB", …).

🔐 Webhook signatures and JSON delivery

Webhook deliveries can now be signed and emitted as JSON.

🔏 HMAC SHA-256 signature

When a signing secret is configured for the platform (managed from the events subscriptions back-office page: generate / regenerate / delete), every notification carries:

X-Mps-Event-Signature: sha256=<hex_digest>                                                                                                                                        

⚙️

The signature is always computed over the JSON serialization of the notification body — regardless of the subscription's transport format.

✅ To verify a notification

1. Compute the HMAC SHA-256 of the JSON-encoded notification body using your secret.
2. Compare the resulting hex digest to the value after sha256=.
3. Reject mismatched or missing signatures whenever a secret is configured.

📦 Notification format

Subscriptions now expose a request_format:

• 📝 form_data (default, backward-compatible) — application/x-www-form-urlencoded
• 🧾 json — application/json

📨 Notification payload

📬

The endpoint must respond with HTTP 200 to acknowledge delivery.

🔔 New webhook events

The following event types can now be subscribed to:

📝 Documentation alignment

The API reference has been aligned with the actual API behavior on a few fields that were already shipped in earlier releases but were still documented under their previous names:

✅

If your client was already integrated against the live API, no change is required on your side — these fields have been returned under their new names for several
months.

🔗 Reference

• 📚 API reference (v1.1.0) — https://mipisepaymentservices.readme.io/v1.1/reference/introduction