Recipients and payouts

In a payout scenario, as a Requesting PSP, Mangopay will be carrying out VOP checks on recipients and payouts and returning the result in the API response.

Scope

VOP applies to EUR Recipients and Payouts using SCT or SCT Inst.

In terms of Recipient properties, this means:

• Currency is EUR
• PayoutMethod is LocalBankTransfer
• Country is a SEPA country

VOP does not apply to non-EUR payouts in SEPA countries, such as SEK payouts to a bank in Sweden (which uses the local scheme RIX). VOP also does not apply to international payouts, such as EUR to a non-SEPA country or, for example, SEK to a SEPA country that isn’t Sweden, both of which use SWIFT.

VOP result API fields

The following endpoints return the Verification of Payee information in the API response:

• POST Create a Payout, if the owner of the payout’s RecipientId or BankAccountId has at least one User-Owned Virtual Account
• POST Create a Recipient (for all platforms)
• GET View a Recipient (for all platforms)

These endpoints return an object parameter, RecipientVerificationOfPayee, containing:

• RecipientVerificationId – A unique identifier of the VOP check performed by Mangopay.
• RecipientVerificationCheck – The outcome of the VOP check performed by Mangopay, using the details in the Recipient object.
• RecipientVerificationMessage – The explanation of the check outcome.

For example:

1
{
2
    //...
3
    "RecipientVerificationOfPayee": {
4
        "RecipientVerificationId": "623d1eff-f24e-4161-b4d2-1ce8385d1376",
5
        "RecipientVerificationCheck": "MATCH",
6
        "RecipientVerificationMessage": "Account name fully matches account identifier."
7
    }
8
    //...
9
}

The outcome of the check is given in fields give the result of the VOP check:

Temporary result for asynchronous processing

Mangopay may temporarily return MATCH_NOT_POSSIBLE accompanied by the message Verification of payee check in progress and with an empty RecipientVerificationId. For example:

1
{
2
    //...
3
    "RecipientVerificationOfPayee": {
4
        "RecipientVerificationId": null,
5
        "RecipientVerificationCheck": "MATCH_NOT_POSSIBLE",
6
        "RecipientVerificationMessage": "Verification of payee check in progress"
7
    }
8
    //...
9
}

This non-final state resolves to one of two final states:

• A definitive RecipientVerificationCheck value (MATCH, CLOSE_MATCH, or NO_MATCH) with its accompanying message
• The final MATCH_NOT_POSSIBLE message: Account name could not be verified. Payment made to this account may not reach its intended counterparty.

On POST Create a Recipient, this asynchronous behavior allows your platform to redirect the User to complete SCA without undue delay. The temporary message is only returned if no response is received from the Responding PSP within 2 seconds.

To retrieve the final VOP result, call GET View a Recipient.

The final outcome of the VOP check should be established within a matter of minutes, but it may take up to 24 hours in a worst-case scenario.

On POST Create a Payout, if a non-final result is returned, you can retrieve the final one via GET View a Payout.

Implementation recommendations

1. Retrieve and display the RecipientVerificationCheck and RecipientVerificationMessage to your users. These data points are both returned in the RecipientVerificationOfPayee object on GET View a Recipient, POST Create a Recipient, and POST Create a Payout.
2. Check the VOP result of Recipients using GET View a Recipient before initiating payouts, to avoid funds being sent to the wrong account.

Recipients

Mangopay performs a VOP check on the endpoints:

• GET View a Recipient
• POST Create a Recipient

VOP is only performed on Recipients where:

• Currency is EUR
• PayoutMethod is LocalBankTransfer
• Country is a SEPA country

The GET View a Recipient and POST Create a Recipient endpoints return the VOP result in the RecipientVerificationOfPayee parameter of the API response:

1
{
2
    "Id": "rec_01K3V3GWJQBZXQ3HKNWCQCJRXF",
3
    "Status": "ACTIVE",
4
    "CreationDate": 1756477551,
5
    "DisplayName": "ExampleBusinessName EUR FR account",
6
    "PayoutMethodType": "LocalBankTransfer",
7
    "RecipientType": "Business",
8
    "Currency": "EUR",
9
    "Country": "FR",
10
    "UserId": "user_m_01JH2Z9GXCCHGFN65T5HDZG4GB",
11
    "Tag": "Created using the Mangopay API Postman collection",
12
    "RecipientScope": "PAYOUT",
13
    "BusinessRecipient": {
14
        "BusinessName": "ExampleBusinessName",
15
        "Address": {
16
            "AddressLine1": "3929 Dickinson Streets",
17
            "AddressLine2": "Stamm Tunnel",
18
            "City": "Paris",
19
            "Region": "Ile de France",
20
            "PostalCode": "75001",
21
            "Country": "FR"
22
        }
23
    },
24
    "LocalBankTransfer": {
25
        "EUR": {
26
            "IBAN": "FR7630004000031234567890143",
27
            "BIC": "BNPAFRPPXXX"
28
        }
29
    },
30
		"RecipientVerificationOfPayee": {
31
			  "RecipientVerificationId": "123456789",
32
			  "RecipientVerificationCheck": "MATCH",
33
			  "RecipientVerificationMessage": "Account name fully matches account identifier."
34
    }
35
}

The GET View a Recipient endpoint returns the latest VOP check performed for that account. If no check has ever been performed (for existing Recipient objects and Bank Account objects), then a new check will be carried out.

The GET View a Bank Account endpoint will not trigger a VOP check nor return any VOP result. Ensure your platform uses GET View a Recipient object to retrieve account information.

The Recipient endpoint can be used to retrieve legacy Bank Account objects by using the Bank Account Id as the RecipientId path parameter.

Payouts

Mangopay is introducing VOP checks when your platform requests a payout using POST Create a Payout only if the owner of the payout’s BankAccountId has at least one User-Owned Virtual Account.

If the user doesn’t have at least one User-Owned Virtual Account, or if the payout does not use the SCT or SCT Inst rails, then VOP is not performed.

The steps are as follows:

1. Your platform calls POST Create a Payout.
2. Mangopay performs Verification of Payee (VOP) using the associated Recipient or Bank Account data (reference in the BankAccountId) by checking the IBAN and account holder name with the Responding PSP (which is the Payee’s bank).
3. Mangopay returns the VOP result in the API response (which may be a temporary result).
4. Mangopay proceeds with the payment, unless it is blocked as described in the scenarios below.

Payout scenarios

Match or close match

When Mangopay performs the VOP check with the Responding PSP, if the result is MATCH or CLOSE_MATCH, then the payout request continues.

The POST Create a Payout endpoint returns an HTTP 200 result containing the RecipientVerificationOfPayee fields:

1
{
2
    "Id": "po_b_01K3GM8HWNCVDMACCRA0ZZPH02",
3
    "Tag": "Created using Mangopay API Postman Collection",
4
    "CreationDate": 1756126005,
5
    "AuthorId": "user_m_01K075ZBVXGFYAXM7529W2ZS5W",
6
    "CreditedUserId": null,
7
    "DebitedFunds": {
8
        "Currency": "EUR",
9
        "Amount": 1000
10
    },
11
    "CreditedFunds": {
12
        "Currency": "EUR",
13
        "Amount": 900
14
    },
15
    "Fees": {
16
        "Currency": "EUR",
17
        "Amount": 100
18
    },
19
    "Status": "CREATED",
20
    "ResultCode": null,
21
    "ResultMessage": null,
22
    "ExecutionDate": null,
23
    "Type": "PAYOUT",
24
    "Nature": "REGULAR",
25
    "CreditedWalletId": null,
26
    "DebitedWalletId": "wlt_m_01J9KQE9Z2S4G4R867C5H6W5ZV",
27
    "PaymentType": "BANK_WIRE",
28
    "BankAccountId": "rec_01K1ZWF7RJG9MEY8VQ0QE2RQ4D",
29
    "BankWireRef": "Example123",
30
    "ModeRequested": null,
31
    "ModeApplied": "PENDING_RESPONSE",
32
    "FallbackReason": null,
33
    "EndToEndId": "3b891fba337d45ec874646ac48565964",
34
    "PaymentRef": null,
35
    "RecipientVerificationOfPayee": {
36
      "RecipientVerificationId": "123456789",
37
      "RecipientVerificationCheck": "MATCH",
38
      "RecipientVerificationMessage": "Account name fully matches account identifier."
39
    }
40
}

Note that the POST request may return a temporary VOP result.

No match or match not possible

If the final result of the VOP check is NO_MATCH or MATCH_NOT_POSSIBLE, then the behavior depends on whether or not your platform has signed the VOP contract amendment. The VOP contract amendment is only applicable to platforms that offer User-Owned Accounts to their users, and payout VOP checks are only performed for these platforms.

If amendment signed

If the amendment is signed, the payout continues and the NO_MATCH or MATCH_NOT_POSSIBLE result is returned in the RecipientVerificationOfPayee object.

This behavior can serve as a warning to your platform or the user. The NO_MATCH result means that payment may not reach its intended payee, and your platform should inform the user accordingly. In these cases, the user should check their account details and re-register the Recipient if necessary.

If amendment not signed

If the amendment is not signed, then the payout fails if the final VOP result is NO_MATCH or MATCH_NOT_POSSIBLE.

While the POST Create a Payout endpoint may return a 200 OK response, the payout subsequently fails with the ResultCode 121030 – Verification of Payee failed: account name and IBAN do not match. Please provide matching details to proceed with the payout.

Testing

In Sandbox, Mangopay provides testing data to allow you to simulate different VOP results when you call POST Create a Recipient.

FR business recipient

Insert the data above in the relevant fields when you call POST Create a Recipient, ensuring you follow the schema for a LocalBankTransfer payout method with the Country set to FR and the Currency in EUR.

API request

1
{
2
    "DisplayName": "EuroCorp EUR FR account",
3
    "PayoutMethodType": "LocalBankTransfer",
4
    "RecipientType": "Business",
5
    "Currency": "EUR",
6
    "Country": "FR",
7
    "Tag": "Created using the Mangopay API Postman collection",
8
    "RecipientScope": "PAYOUT",
9
    "BusinessRecipient": {
10
        "BusinessName": "EuroCorp", 
11
        "Address": {
12
            "AddressLine1": "6 rue de la Cité",
13
            "AddressLine2": "Appartement 3",
14
            "City": "Paris",
15
            "Region": "île-de-France",
16
            "PostalCode": "75003",
17
            "Country": "FR"
18
        }
19
    },
20
    "LocalBankTransfer": {
21
        "EUR": {        
22
            "IBAN": "FR7630001007941234567890185"
23
        }
24
    }
25
}

API response

1
{
2
    "Id": "rec_01K6CYKD6MW45X0TFXS8GSMNWH",
3
    "Status": "PENDING",
4
    "CreationDate": 1759223854,
5
    "DisplayName": "EuroCorp EUR FR account",
6
    "PayoutMethodType": "LocalBankTransfer",
7
    "RecipientType": "Business",
8
    "Currency": "EUR",
9
    "Country": "FR",
10
    "UserId": "user_m_01K6ATMK6BA01BHGF14P7M1Q95",
11
    "RecipientScope": "PAYOUT",
12
    "Tag": "Created using the Mangopay API Postman collection",
13
    "BusinessRecipient": {
14
        "BusinessName": "EuroCorp",
15
        "Address": {
16
            "AddressLine1": "6 rue de la Cité",
17
            "AddressLine2": "Appartement 3",
18
            "City": "Paris",
19
            "Region": "île-de-France",
20
            "PostalCode": "75003",
21
            "Country": "FR"
22
        }
23
    },
24
    "LocalBankTransfer": {
25
        "EUR": {
26
            "IBAN": "FR7630001007941234567890185",
27
            "BIC": "BDFEFRPPCCT"
28
        }
29
    },
30
    "PendingUserAction": {
31
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_019999e9b6f97eb49e77af2505f5a816"
32
    },
33
    "RecipientVerificationOfPayee": {
34
        "RecipientVerificationId": "383db3d8-2bdd-480d-bed8-28bf5be275a9",
35
        "RecipientVerificationCheck": "MATCH",
36
        "RecipientVerificationMessage": "Account name fully matches account identifier."
37
    }
38
}

DE individual recipient

Insert the data above in the relevant fields when you call POST Create a Recipient, ensuring you follow the schema for a LocalBankTransfer payout method with the Country set to DE and the Currency in EUR.

Follow the examples below.

API request

1
{
2
    "DisplayName": "John Doe EUR DE account",
3
    "PayoutMethodType": "LocalBankTransfer",
4
    "RecipientType": "Individual",
5
    "Currency": "EUR",
6
    "Country": "DE",
7
    "Tag": "Created using the Mangopay API Postman collection",
8
    "RecipientScope": "PAYOUT",
9
    "IndividualRecipient": {
10
        "FirstName": "John",
11
        "LastName": "Doe",
12
        "Address": {
13
            "AddressLine1": "Oranienburger Str. 87",
14
            "City": "Berlin",
15
            "PostalCode": "10178",
16
            "Country": "DE"
17
        }
18
    },
19
    "LocalBankTransfer": {
20
        "EUR": {        
21
            "IBAN": "DE75512108001245126199"
22
        }
23
    }
24
}

API response

1
{
2
    "Id": "rec_01K6CYKD6MW45X0TFXS8GSMNWH",
3
    "Status": "PENDING",
4
    "CreationDate": 1759223854,
5
    "DisplayName": "EuroCorp EUR FR account",
6
    "PayoutMethodType": "LocalBankTransfer",
7
    "RecipientType": "Business",
8
    "Currency": "EUR",
9
    "Country": "FR",
10
    "UserId": "user_m_01K6ATMK6BA01BHGF14P7M1Q95",
11
    "RecipientScope": "PAYOUT",
12
    "Tag": "Created using the Mangopay API Postman collection",
13
    "BusinessRecipient": {
14
        "BusinessName": "EuroCorp",
15
        "Address": {
16
            "AddressLine1": "6 rue de la Cité",
17
            "AddressLine2": "Appartement 3",
18
            "City": "Paris",
19
            "Region": "île-de-France",
20
            "PostalCode": "75003",
21
            "Country": "FR"
22
        }
23
    },
24
    "LocalBankTransfer": {
25
        "EUR": {
26
            "IBAN": "FR7630001007941234567890185",
27
            "BIC": "BDFEFRPPCCT"
28
        }
29
    },
30
    "PendingUserAction": {
31
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_019999e9b6f97eb49e77af2505f5a816"
32
    },
33
    "RecipientVerificationOfPayee": {
34
        "RecipientVerificationId": "383db3d8-2bdd-480d-bed8-28bf5be275a9",
35
        "RecipientVerificationCheck": "MATCH",
36
        "RecipientVerificationMessage": "Account name fully matches account identifier."
37
    }
38
}

Technical error cases

The following IBANs allow you to simulate error cases with any account holder name.

View a Recipient

If you use the testing data above, the GET View a Recipient returns the VOP check that was performed at creation, with the same RecipientVerificationId.

Otherwise, in Sandbox, the GET View a Recipient for a legacy Bank Account or Recipient created before VOP always returns:

1
{
2
//...
3
    "RecipientVerificationOfPayee": {
4
        "RecipientVerificationId": null,
5
        "RecipientVerificationCheck": "MATCH_NOT_POSSIBLE",
6
        "RecipientVerificationMessage": "Account name could not be verified. Payment made to this account may not reach its intended counterparty."
7
    }
8
//...
9
}

In Production, Mangopay performs a VOP check on all active Recipients and legacy Bank Accounts (unless one was already performed at creation or retrieval). The check result is returned on the GET View a Recipient (but not the legacy GET View a Bank Account).

Payouts

If you use the testing data above, the POST Create a Payout returns the VOP check that was performed at recipient creation, with the same RecipientVerificationId.

Otherwise, in Sandbox, the POST Create a Payout returns a nulled object:

1
{
2
//...
3
    "RecipientVerificationOfPayee": null,
4
//...
5
}