Beneficiary

Overview

Beneficiaries are the receivers of the payment. You will always need to specify the beneficiary when using Metaprise's Payment function and related APIs.

When using Transfer Auto Flow:

✅ Beneficiaries are automatically added and managed
✅ You have the option to set default beneficiaries on Metaprise Dashboard. This is a great option if your payments are always received by the same beneficiaries that you know ahead of time.

Begin You start

Sign up the Metaprise developer devhub platform to get your unique Client ID and API key.
Obtain your access token by authenticating to Metaprise using your unique Client ID and API key. You will need the access token to make API calls.
Set up webhooks to receive notifications on Payment events.

Beneficiary profiles

Customer Profile	Description
Beneficiary Company Name	The beneficiary company name
Bank Country	The bank country. Metaprise supports global payments covering US, UK, SG, HK, CA and most EU countries.
Beneficiary Address	Country Address Line1 & Address Line2 City State/Province Zip/Postal code
Payment Type	Metaprise supports two types of payments: "priority", made using the Swift network; and "regular", made using the local bank network.
Account Name	The bank account name
Account Number	The bank account number
SWFIT Code	The bank account swift code
ACH routing number	The ACH routing number
WIRE routing number	The wire routing number
Account Type	The bank account type, only for US banks. Supports Checking and Saving
Bank Name	The bank name
IBAN	The bank account iban
Sort Code	The bank account sort
Account Code	The bank account code
Branch Code	The bank account branch code

Create a Beneficiary

Use dashboard to create a new customer.
1. Sign up and log in the Metaprise dashboard
2. Click 'Add Beneficiary' button.
3. Select Currency which Metaprise support for the payment.
4. Fill the beneficiary details information. Please note the account information might be different based on the currency selected in last step.

Use API to create a new beneficiary.

The following example shows how to create a new beneficiary with different payment method.

Example request

{   "beneficiary_company_name":"",
    "bank_country":"",
    "beneficiary_address": {
       "address_line1": "123",
       "address_line2": "123",
       "city": "123",
       "state_or_province": "123",
       "postcode": "123",
       "country": "123"
    },
    "payment_method": [
        {
            "payment_type": "regular",
            "account_name": "",
            "account_number": "",
            "ach_routing_number": 12386574,
            "bank_address": {
                "address_line1": "123",
                "address_line2": "123",
                "city": "123",
                "state_or_province": "123",
                "postcode": "123",
                "country": "123" 
            } 
        },
        {
            "payment_type": "priority",
            "account_name": "",
            "account_number": "",
            "bic_swift": 12386574
            "bank_address": {
                "address_line1": "123",
                "address_line2": "123",
                "city": "123",
                "state_or_province": "123",
                "postcode": "123",
                "country": "123"
            } 
        },
        {
            "payment_type": "priority",
            "account_name": "",
            "account_number": "",
            "wire_routing_number": 12386574
            "bank_address": {
                "address_line1": "123",
                "address_line2": "123",
                "city": "123",
                "state_or_province": "123",
                "postcode": "123",
                "country": "123" 
            } 
        },

Example response

{
    "id": "dkl7699-6508-421e-b1cf-d4fbe41ed398",
    "created": 1678043844,
}

Update Beneficiary

Use update beneficiary API to update existing beneficiary.

Example request

{
     "beneficiary_id": "7fb35c55-976d-4e77-8f9d-7a152c314222"
     "beneficiary_company_name":"",
     "bank_country":"",
     "beneficiary_address": {
       "address_line1": "123",
       "address_line2": "123",
       "city": "123",
       "state_or_province": "123",
       "postcode": "123",
       "country": "123"
    },

}

Example rsponse

{
		"id": "person_1MqjB62eZvKYlo2CaeEJzKVR"
}

List Beneficiary

Use list all beneficiary API to update existing beneficiary.

Example request

{
    "starting_after": "7fb35c55-976d-4e77-8f9d-7a152c314222",
    "limit": 20
}

Example rsponse

{
    "has_more": "false",
    "data": [
       {
          "id": "dkl7699-6508-421e-b1cf-d4fbe41ed398",
          "created": 1678043844,
          All beneficiary information which is same with 'Add beneficiary' API
     
       },
        {},
        {}
    ]
}

Delete Beneficiary

Use delete beneficiary API to update existing beneficiary.

Example request

{
     "beneficiary_id": "7fb35c55-976d-4e77-8f9d-7a152c314222"
}

Example rsponse

{
		"id": "person_1MqjB62eZvKYlo2CaeEJzKVR"
}