Create an international vendor

International vendors are vendors outside the US. See Country information for international payments in the BILL Help Center to learn about supported countries and currencies.

In your POST /v3/vendors request, set the required fields to create an international vendor.

Field	Description
`name`	Vendor name
`accountType`	Vendor account type (`BUSINESS`, `PERSON`, or `NONE`)
`email`	Vendor email address
`address`	Vendor address information. Vendor address details are required for paying the vendor by check or for inviting the vendor to join the BILL network. `line1` `city` `zipOrPostalCode` `country`
`paymentInformation`	Vendor bank account information. Vendor bank account details are required for enabling electronic payments to the vendor. `payeeName` `bankCountry` `paymentCurrency` `nameOnAccount` `accountNumber` `routingNumber` (This field is empty for an IBAN `accountNumber`) `type`

Additional configuration for enabling electronic payments

In your POST/v3/vendors request, paymentPurpose and regulatoryFields are additional required fields for enabling electronic payments to international vendors (not United States) in specific countries. This information is based on vendor country, bill currency, and vendor account type.

You can get the required information with GET /v3/vendors/configuration/international-payments. See the /v3/vendors/configuration/international-payments API for more information.

👍
You have the option to add the required configuration after creating a vendor
If you are adding paymentPurpose and regulatoryFields information after creating an international vendor, use GET /v3/vendors/{vendorId}/configuration to get the required configuration for your created vendor. See the /v3/vendors/{vendorId}/configuration API for more information.

`paymentPurpose`

Payment purpose information for compliance with international payment rules of the vendor country. This information is based on vendor country, bill currency, and vendor account type.

The payment purpose information for international vendors must conform to a set of rules.

textorcode : You must set either the text or code field for vendor payments in an international currency (not USD). You cannot set both fields.
Information source: Learn about which field to set (text or code) with GET /v3/vendors/configuration/international-payments.
Some countries do not require payment purpose: There are vendor countries, like Japan, that do not require any payment purpose information. For such countries, setting paymentPurpose in your request results in an error. This information is available with GET /v3/vendors/configuration/international-payments.

Example: Denmark

In this GET /v3/vendors/configuration/international-payments cURL example, international payments configuration is retrieved for a vendor in Denmark (DK). The bill currency is set as Euro (EUR).

curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/vendors/configuration/international-payments?country=DK&billCurrency=EUR&accountType=BUSINESS' \
--header 'accept: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'

Response

In the response, the required paymentPurpose information is retrieved for a vendor in Denmark. Use this paymentPurpose information for providing required information while creating an international vendor in Denmark.

{
  "paymentPurpose": {
    "required": true,
    "type": "CODE",
    "codes": [
      {
        "name": "Purchase of Good(s)",
        "value": "PURCHASE OF GOOD(S)"
      },
      ...
      // List of other paymentPurpose codes
      ...
    ]
  },
  "validations": {
    "fields": [
      {
        "name": "accountNumber",
        "description": "IBAN",
        "regularExpression": "^(AT)[0-9]{18}$",
        "required": true
      }
    ]
  }
}

👍
Take note of the validations information
In the response, we also learn about the validations information for the country-specific bank account regulatory fields that must be set in your request. We explain how to use the validations information in the next section.

See Create an international vendor (not US) sample request later in this article for the sample cURL request and response.

`regulatoryFields`

International bank account regulatory information. The name and value fields are required for each required bank account regulatory field.

Example 01: Brazil

In this sample GET /v3/vendors/configuration/international-payments response, we see the required regulatory field name values for adding a Brazilian vendor bank account. In addition, the regularExpression for each regulatory field provides information about the required format in which the value must be provided.

{
  "paymentPurpose": {
  ...
  // List of paymentPurpose values
  ...
  },
  "validations": {
    "fields": [
      {
        "name": "regulatory2",
        "description": "Beneficiary CNPJ",
        "regularExpression": "^[0-9]{14}$",
        "required": true
      },
      {
        "name": "regulatory3",
        "description": "Agency Code",
        "regularExpression": "^[0-9]{4}$",
        "required": true
      },
      {
        "name": "regulatory4",
        "description": "Contact Name",
        "regularExpression": "^.{3,30}$",
        "required": true
      },
      {
        "name": "regulatory5",
        "description": "Account Type",
        "regularExpression": "^(|CACC|SVGS)$",
        "required": true
      },
      {
        "name": "regulatory6",
        "description": "Beneficiary Bank Branch Name ",
        "regularExpression": "^.{0,30}$",
        "required": false
      },
      {
        "name": "accountNumber",
        "description": "IBAN",
        "regularExpression": "^(BR)[A-Z0-9]{27}$",
        "required": true
      }
    ]
  }
}

From the response, we learn that in addition to the bank account number, there are 5 sets (4 required) of regulatory field name values for adding a Brazilian vendor bank account.

❗️
Vendor phone is required for certain international vendor countries
If the "name": "phone" requirement is present in the GET /v3/vendors/configuration/international-payments response, you must set the vendor phone field for creating an international vendor.
For example, when the country is CN (China) and billCurrency is CNY (Chinese Yuan), you must set the vendor phone in your POST /v3/vendors request.

In this sample bankAccount object in your POST/v3/vendors request, the accountNumber and other regulatoryFields are set for a Brazilian vendor bank account.

"bankAccount": {
  "nameOnAccount": "Bill Vendorson",
  "accountNumber":"BR1800360305000010009795493C1",
  "type": "CHECKING",
  "regulatoryFields":[
    {
      "name":"regulatory2",
      "value":"13339532000109"
    },
    {
      "name":"regulatory3",
      "value":"0001"
    },
    {
      "name":"regulatory4",
      "value":"Bill Vendorson"
    },
    {
      "name":"regulatory5",
      "value":"CACC"
    },
    {
      "name":"regulatory6",
      "value":"0009795493"
    }
  ]
}

Example 02: Australia

In this sample GET /v3/vendors/configuration/international-payments response, we see the required regulatory field name values for adding an Australian vendor bank account.

{
  "paymentPurpose": {
    "required": false
  },
  "validations": {
    "fields": [
      {
        "name": "accountNumber",
        "regularExpression": "^[0-9]{1,9}$",
        "required": true
      },
      {
        "name": "routingNumber",
        "description": "Bank Code",
        "regularExpression": "^[0-9]{6}$",
        "required": true
      }
    ]
  }
}

From the response, we learn that only the accountNumber and routingNumber fields are required for adding an Australian vendor bank account. The regularExpression field for routingNumber tells us that the field must be 6 digits and refers to the Bank-State-Branch (BSB) code in Australia.

See the /v3/vendors/configuration/international-payments API for more information.