Skip to main content

​
Overview

The ApiRecipients class provides methods for managing payout recipients. Recipients represent individuals or entities that can receive payouts through various payout methods and countries.
Recipients are used with the Echo API for managing international and local bank transfer payouts with dynamic validation based on country and payout method.

​
Methods

​
Create

Create a new recipient for a user. 
public function Create(Recipient $recipient, string $userId, ?string $idempotencyKey = null): Recipient
​
recipient
Recipient
required
Recipient object with payout details
​
userId
string
required
User ID who owns the recipient
​
idempotencyKey
string
Idempotency key for request replication
Returns: Created Recipient object Example: 
$recipient = new MangoPay\Recipient();
$recipient->Type = 'Individual';
$recipient->PayoutMethodType = 'LocalBankTransfer';
$recipient->Country = 'US';
$recipient->Currency = 'USD';
$recipient->FirstName = 'John';
$recipient->LastName = 'Doe';
$recipient->BankAccountNumber = '123456789';
$recipient->BankRoutingNumber = '021000021';

$createdRecipient = $api->Recipients->Create($recipient, $userId);
echo "Recipient created: {$createdRecipient->Id}\n";

​
Get

Retrieve a recipient by ID. 
public function Get(string $recipientId): Recipient
​
recipientId
string
required
Recipient identifier
Returns: Recipient object Example: 
$recipient = $api->Recipients->Get($recipientId);
echo "Recipient: {$recipient->FirstName} {$recipient->LastName}\n";
echo "Country: {$recipient->Country}\n";
echo "Status: {$recipient->Status}\n";

​
GetUserRecipients

Retrieve all recipients for a specific user. 
public function GetUserRecipients(string $userId, ?Pagination $pagination = null, ?Sorting $sorting = null, ?FilterRecipients $filter = null): array
​
userId
string
required
User identifier
​
pagination
Pagination
Pagination parameters
​
sorting
Sorting
Sorting parameters
​
filter
FilterRecipients
Filter recipients
Returns: Array of Recipient objects Example: 
$pagination = new MangoPay\Pagination(1, 20);
$recipients = $api->Recipients->GetUserRecipients($userId, $pagination);

foreach ($recipients as $recipient) {
    echo "Recipient {$recipient->Id}: {$recipient->FirstName} {$recipient->LastName}\n";
}

​
GetPayoutMethods

See available payout methods by currency and country. 
public function GetPayoutMethods(string $country, string $currency): PayoutMethods
​
country
string
required
2-letter ISO country code
​
currency
string
required
3-letter ISO currency code
Returns: PayoutMethods object with available methods Example: 
$payoutMethods = $api->Recipients->GetPayoutMethods('US', 'USD');

foreach ($payoutMethods->Methods as $method) {
    echo "Method: {$method->Type}\n";
    echo "Fee: {$method->Fee}\n";
}

​
GetSchema

Get the recipient schema for specific payout method, type, currency, and country. 
public function GetSchema(string $payoutMethodType, string $recipientType, string $currency, string $country): RecipientSchema
​
payoutMethodType
string
required
Payout method (LocalBankTransfer, InternationalBankTransfer)
​
recipientType
string
required
Recipient type (Individual, Business)
​
currency
string
required
3-letter ISO currency code
​
country
string
required
2-letter ISO country code
Returns: RecipientSchema object with required and optional fields Example: 
$schema = $api->Recipients->GetSchema(
    'LocalBankTransfer',
    'Individual',
    'USD',
    'US'
);

echo "Required fields:\n";
foreach ($schema->RequiredFields as $field) {
    echo "  - {$field->Name} ({$field->Type})\n";
}

​
Validate

Validate recipient data before creating. 
public function Validate(Recipient $recipient, string $userId, ?string $idempotencyKey = null)
​
recipient
Recipient
required
Recipient object to validate
​
userId
string
required
User ID
Example: 
$recipient = new MangoPay\Recipient();
$recipient->Type = 'Individual';
$recipient->PayoutMethodType = 'LocalBankTransfer';
$recipient->Country = 'US';
$recipient->Currency = 'USD';
$recipient->FirstName = 'John';
$recipient->LastName = 'Doe';
$recipient->BankAccountNumber = '123456789';
$recipient->BankRoutingNumber = '021000021';

try {
    $api->Recipients->Validate($recipient, $userId);
    echo "Recipient data is valid\n";
} catch (Exception $e) {
    echo "Validation failed: " . $e->getMessage() . "\n";
}

​
Deactivate

Deactivate a recipient. 
public function Deactivate(string $recipientId): Recipient
​
recipientId
string
required
Recipient identifier
Returns: Deactivated Recipient object Example: 
$recipient = $api->Recipients->Deactivate($recipientId);
echo "Recipient status: {$recipient->Status}\n"; // DEACTIVATED

​
Recipient Entity

​
Id
string
Unique identifier
​
Type
string
Recipient type (Individual, Business)
​
PayoutMethodType
string
Payout method (LocalBankTransfer, InternationalBankTransfer)
​
Country
string
2-letter ISO country code
​
Currency
string
3-letter ISO currency code
​
FirstName
string
First name (for individuals)
​
LastName
string
Last name (for individuals)
​
CompanyName
string
Company name (for businesses)
​
BankAccountNumber
string
Bank account number
​
BankRoutingNumber
string
Bank routing/sort code (country-specific)
​
Status
string
Recipient status (ACTIVE, DEACTIVATED)
​
CreationDate
int
Unix timestamp of creation

​
Complete Workflow: Creating Recipients

// Step 1: Check available payout methods
$payoutMethods = $api->Recipients->GetPayoutMethods('US', 'USD');
echo "Available payout methods for US/USD:\n";
foreach ($payoutMethods->Methods as $method) {
    echo "  - {$method->Type}\n";
}

// Step 2: Get schema for chosen method
$schema = $api->Recipients->GetSchema(
    'LocalBankTransfer',
    'Individual',
    'USD',
    'US'
);

echo "\nRequired fields:\n";
foreach ($schema->RequiredFields as $field) {
    echo "  - {$field->Name} ({$field->Type})\n";
}

// Step 3: Create recipient with required fields
$recipient = new MangoPay\Recipient();
$recipient->Type = 'Individual';
$recipient->PayoutMethodType = 'LocalBankTransfer';
$recipient->Country = 'US';
$recipient->Currency = 'USD';
$recipient->FirstName = 'John';
$recipient->LastName = 'Doe';
$recipient->BankAccountNumber = '123456789';
$recipient->BankRoutingNumber = '021000021';
$recipient->Address = new MangoPay\Address();
$recipient->Address->AddressLine1 = '123 Main St';
$recipient->Address->City = 'New York';
$recipient->Address->PostalCode = '10001';
$recipient->Address->Country = 'US';

// Step 4: Validate before creating
try {
    $api->Recipients->Validate($recipient, $userId);
    
    // Step 5: Create the recipient
    $createdRecipient = $api->Recipients->Create($recipient, $userId);
    echo "\nRecipient created: {$createdRecipient->Id}\n";
    
    // Step 6: Use recipient for payout (see Settlements API)
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

​
International Transfer Example

// Create recipient for international transfer to UK
$recipient = new MangoPay\Recipient();
$recipient->Type = 'Individual';
$recipient->PayoutMethodType = 'InternationalBankTransfer';
$recipient->Country = 'GB';
$recipient->Currency = 'GBP';
$recipient->FirstName = 'Jane';
$recipient->LastName = 'Smith';
$recipient->BankAccountNumber = '12345678'; // UK account number
$recipient->BankRoutingNumber = '123456'; // UK sort code
$recipient->Address = new MangoPay\Address();
$recipient->Address->AddressLine1 = '10 Downing Street';
$recipient->Address->City = 'London';
$recipient->Address->PostalCode = 'SW1A 2AA';
$recipient->Address->Country = 'GB';

$createdRecipient = $api->Recipients->Create($recipient, $userId);

​
Managing Multiple Recipients

// Get all recipients for a user
$recipients = $api->Recipients->GetUserRecipients($userId);

// Filter active recipients
$activeRecipients = array_filter($recipients, function($r) {
    return $r->Status === 'ACTIVE';
});

echo "Active recipients:\n";
foreach ($activeRecipients as $recipient) {
    $name = $recipient->Type === 'Individual'
        ? "{$recipient->FirstName} {$recipient->LastName}"
        : $recipient->CompanyName;
    
    echo "  {$recipient->Id}: {$name} ({$recipient->Country}/{$recipient->Currency})\n";
}

// Deactivate old recipients
foreach ($recipients as $recipient) {
    if (shouldDeactivate($recipient)) {
        $api->Recipients->Deactivate($recipient->Id);
        echo "Deactivated recipient {$recipient->Id}\n";
    }
}
Use the schema endpoint to dynamically build forms that adapt to different countries and payout methods. Required fields vary by country and payment method.
Validate recipient data before creation to avoid errors. Different countries have different validation rules for bank account numbers and routing codes.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us