Create a beneficiary

POST /companies/{company_id}/beneficiaries

Create a beneficiary for your company. A beneficiary is necessary to initiate a payout.

Path parameters

  • company_id string Required

    The Company ID given by Fipto.

    Format should match the following pattern: [0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}.

Body

  • data object Required

    Fields required on all objects.

    Hide data attributes Show data attributes object
    • type string Required

      Default value is beneficiary.

    • attributes object Required
      Hide attributes attributes Show attributes attributes object
      • description string Required

        Description of the beneficiary that you want to add (e.g. "external wallet account").

      • wallet_details object Required

        Any of:
        wallet_details_digital object wallet_details_digital_tag object wallet_details_fiat_iban object

        Minimal info in common about Wallet Details

        Hide attributes Show attributes
        • asset string Required

          The symbol/ticker of the crypto asset.

          Format should match the following pattern: ([A-Z_]){3,}.

        • address string Required

          The public address associated with a wallet details on the blockchain.

        • name string

          The wallet details name

      • beneficiary_info object Required

        One of:
        beneficiary_info_natural object beneficiary_info_legal object beneficiary_is_self object

        Data about Beneficiary of type Natural

        Hide attributes Show attributes
        • type string Required Discriminator

          Value is individual.

        • firstname string Required

          First name of the beneficiary.

          Minimum length is 1.

        • lastname string Required

          Last name of the beneficiary.

          Minimum length is 1.

        • address object Required

          Physical address of the beneficiary

          Hide address attributes Show address attributes object
          • street_address string Required

            Street name and number of the address.

            Minimum length is 1.

          • zip_code string Required

            Zip code of the beneficiary.

            Minimum length is 1.

          • city string Required

            Full city name of the beneficiary.

            Minimum length is 1.

          • country_code string Required

            2 letters representing a country (ISO 3166).

            Minimum length is 2, maximum length is 2.

Responses

  • 201

    Beneficiary successfully created

    Hide response attributes Show response attributes object
    • meta object Required
      Hide meta attributes Show meta attributes object
      • request_id string Required

        Unique identifier generated by the server.

        Format should match the following pattern: [0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}.

      • query_parameters object

        Information about the parameters in the request. All query string parameters provided (or implicit/with default value) will be returned

    • data object

      Fields required on all objects.

      Hide data attributes Show data attributes object
      • id string Required

        Unique identifier generated by the server.

        Format should match the following pattern: [0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}.

      • type string Required

        Default value is beneficiary.

      • attributes object Required
        Hide attributes attributes Show attributes attributes object
        • description string Required

          Description of the beneficiary that you want to add (e.g. "external wallet account").

        • wallet_details object Required

          Any of:
          wallet_details_digital object wallet_details_digital_tag object wallet_details_fiat_iban object

          Minimal info in common about Wallet Details

          Hide attributes Show attributes
          • asset string Required

            The symbol/ticker of the crypto asset.

            Format should match the following pattern: ([A-Z_]){3,}.

          • address string Required

            The public address associated with a wallet details on the blockchain.

          • name string

            The wallet details name

        • beneficiary_info object Required

          One of:
          beneficiary_info_natural object beneficiary_info_legal object beneficiary_is_self object

          Data about Beneficiary of type Natural

          Hide attributes Show attributes
          • type string Required Discriminator

            Value is individual.

          • firstname string Required

            First name of the beneficiary.

            Minimum length is 1.

          • lastname string Required

            Last name of the beneficiary.

            Minimum length is 1.

          • address object Required

            Physical address of the beneficiary

            Hide address attributes Show address attributes object
            • street_address string Required

              Street name and number of the address.

              Minimum length is 1.

            • zip_code string Required

              Zip code of the beneficiary.

              Minimum length is 1.

            • city string Required

              Full city name of the beneficiary.

              Minimum length is 1.

            • country_code string Required

              2 letters representing a country (ISO 3166).

              Minimum length is 2, maximum length is 2.
  • 400

    Bad Request

POST /companies/{company_id}/beneficiaries 
curl \
 -X POST https://api.fipto.app/companies/9de0691c-bc8d-409b-8f40-75d4f45db2f3/beneficiaries \
 -H "Content-Type: application/json" \
 -d '{"data":{"type":"beneficiary","attributes":{"description":"my beneficiary","wallet_details":{"asset":"BTC","address":"bc1***"},"beneficiary_info":{"type":"individual","firstname":"Sam","lastname":"Doe","address":{"street_address":"25 rue François 1er","zip_code":"75008","city":"Paris","country_code":"FR"}}}}}'
Request examples 
{
  "data": {
    "type": "beneficiary",
    "attributes": {
      "description": "my beneficiary",
      "wallet_details": {
        "asset": "BTC",
        "address": "bc1***"
      },
      "beneficiary_info": {
        "type": "individual",
        "firstname": "Sam",
        "lastname": "Doe",
        "address": {
          "street_address": "25 rue François 1er",
          "zip_code": "75008",
          "city": "Paris",
          "country_code": "FR"
        }
      }
    }
  }
}
{
  "data": {
    "type": "beneficiary",
    "attributes": {
      "description": "my beneficiary",
      "wallet_details": {
        "asset": "BTC",
        "address": "bc1***"
      },
      "beneficiary_info": {
        "type": "company",
        "name": "Acme",
        "address": {
          "street_address": "25 rue François 1er",
          "zip_code": "75008",
          "city": "Paris",
          "country_code": "FR"
        }
      }
    }
  }
}
{
  "data": {
    "type": "beneficiary",
    "attributes": {
      "description": "my beneficiary",
      "wallet_details": {
        "asset": "BTC",
        "address": "bc1***"
      },
      "beneficiary_info": {
        "type": "self"
      }
    }
  }
}
Request examples 
{
  "data": {
    "type": "beneficiary",
    "attributes": {
      "description": "string",
      "wallet_details": {
        "asset": "BTC",
        "address": "0x71C*",
        "name": "Acme - Payment Project X"
      },
      "beneficiary_info": {
        "type": "individual",
        "firstname": "Victor",
        "lastname": "Duponthieu",
        "address": {
          "street_address": "25 rue François 1er",
          "zip_code": "75008",
          "city": "Paris",
          "country_code": "FR"
        }
      }
    }
  }
}
Response examples (201) 
{
  "meta": {
    "request_id": "dba2bB95-28eD-E9E9-9ABC-7535831512bb"
  },
  "data": {
    "type": "beneficiary",
    "id": "fea2bB77-54eF-E9E9-9ABC-6535831512aa",
    "attributes": {
      "description": "my beneficiary",
      "wallet_details": {
        "asset": "BTC",
        "address": "bc1***"
      },
      "beneficiary_info": {
        "type": "individual",
        "firstname": "Sam",
        "lastname": "Doe",
        "address": {
          "street_address": "25 rue François 1er",
          "zip_code": "75008",
          "city": "Paris",
          "country_code": "FR"
        }
      }
    }
  }
}
{
  "meta": {
    "request_id": "dba2bB95-28eD-E9E9-9ABC-7535831512bb"
  },
  "data": {
    "type": "beneficiary",
    "id": "fea2bB77-54eF-E9E9-9ABC-6535831512aa",
    "attributes": {
      "description": "my beneficiary",
      "wallet_details": {
        "asset": "BTC",
        "address": "bc1***"
      },
      "beneficiary_info": {
        "type": "company",
        "name": "Acme",
        "address": {
          "street_address": "25 rue François 1er",
          "zip_code": "75008",
          "city": "Paris",
          "country_code": "FR"
        }
      }
    }
  }
}
{
  "meta": {
    "request_id": "dba2bB95-28eD-E9E9-9ABC-7535831512bb"
  },
  "data": {
    "type": "beneficiary",
    "id": "fea2bB77-54eF-E9E9-9ABC-6535831512aa",
    "attributes": {
      "description": "my beneficiary",
      "wallet_details": {
        "asset": "BTC",
        "address": "bc1***"
      },
      "beneficiary_info": {
        "type": "self"
      }
    }
  }
}
Response examples (201) 
{
  "meta": {
    "request_id": "string",
    "query_parameters": {}
  },
  "data": {
    "id": "string",
    "type": "beneficiary",
    "attributes": {
      "description": "string",
      "wallet_details": {
        "asset": "BTC",
        "address": "0x71C*",
        "name": "Acme - Payment Project X"
      },
      "beneficiary_info": {
        "type": "individual",
        "firstname": "Victor",
        "lastname": "Duponthieu",
        "address": {
          "street_address": "25 rue François 1er",
          "zip_code": "75008",
          "city": "Paris",
          "country_code": "FR"
        }
      }
    }
  }
}
Response examples (400) 
{
  "meta": {
    "request_id": "XXXX-XXXX-XXXX-XXXX-XXXX"
  },
  "errors": {
    "code": "invalid_identifier",
    "source": {
      "pointer": "/data/attributes/wallet_details/address"
    },
    "title": "Invalid Address",
    "detail": "This address is not valid for the selected asset network"
  }
}