Creating 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
`phone`	Vendor phone number
`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.

👍
MORE INFORMATION
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.

text or code: 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.

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

📘
NOTE
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.

{
  "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",
        "regularExpression": "^(AT)[0-9]{18}$",
        "required": true
      }
    ]
  }
}

`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",
        "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 and value pairs for adding a Brazilian vendor bank account.

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",
        "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.

Create an international vendor (not US) sample request

In this cURL example, an international vendor is created in Denmark with the specified details. The address and paymentInformation details are added to enable electronic payments to the vendor. In addition, required paymentPurpose information is added for Denmark.

In the above GET /v3/vendors/configuration/international-payments response, type is set as CODE. From the response, we learn that we must set code in the paymentPurpose object.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/vendors' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "name": "Happy Music Supplies International",
  "accountType": "BUSINESS",
  "email": "[email protected]",
  "phone": "9876543210",
  "address": {
    "line1": "Nørre Voldgade 68",
    "city": "Copenhagen",
    "zipOrPostalCode": "1165",
    "country": "DK"
  },
  "paymentInformation": {
    "payeeName": "Happy Music Supplies International",
    "bankCountry": "DK",
    "bankAccount": {
      "nameOnAccount": "Bill Vendorson",
      "accountNumber": "DK5000400440116243",
      "type": "CHECKING",
      "paymentCurrency": "EUR"
    },
    "paymentPurpose": {
      "code": {
        "name": "PURCHASE OF GOOD(S)"
      }
    }
  },
  "billCurrency": "EUR"
}'

Response

In the response, a BILL-generated vendor id is available. This value begins with 009. You can use this vendor id for other BILL operations.

{
    "id": "{vendor_id}",
    "archived": false,
    "name": "Happy Music Supplies International",
    "accountType": "BUSINESS",
    "email": "[email protected]",
    "phone": "9876543210",
    "address": {
        "line1": "Nørre Voldgade 68",
        "city": "Copenhagen",
        "zipOrPostalCode": "1165",
        "country": "DK"
    },
    "paymentInformation": {
        "payeeName": "Happy Music Supplies International",
        "paymentCurrency": "EUR",
        "payByType": "INTERNATIONAL_E_PAYMENT",
        "payBySubType": "WIRE",
        "virtualCard": {
            "status": "UNKNOWN"
        },
        "bankAccount": {
            "nameOnAccount": "Bill Vendorson",
            "accountNumber": "**************6243",
            "routingNumber": "0040",
            "type": "CHECKING",
            "ownerType": "BUSINESS",
            "bankInfo": {
                "swiftBIC": "NDEADKKKXXX",
                "branchName": "",
                "countryISO": "DK",
                "nationalBankCode": "0040",
                "institutionName": "NORDEA BANK ABP",
                "primaryKey": "000000000351740",
                "address": {
                    "line1": "PRINS JORGENS ALLE 6",
                    "line2": "",
                    "city": "VORDINGBORG",
                    "stateOrProvince": "SJAELLAND",
                    "zipOrPostalCode": "4760",
                    "country": "DENMARK"
                }
            }
        },
        "paymentPurpose": {
            "code": {
                "name": "PURCHASE OF GOOD(S)",
                "value": "Purchase of Good(s)"
            }
        }
    },
    "additionalInfo": {
        "track1099": false,
        "combinePayments": true
    },
    "bankAccountStatus": "NO_NET_LINKED_ACCOUNT",
    "recurringPayments": false,
    "billCurrency": "EUR",
    "createdTime": "2024-12-30T19:28:00.000+00:00",
    "updatedTime": "2024-12-30T19:28:00.000+00:00",
    "balance": {
        "amount": 0.0
    },
    "autoPay": {
        "enabled": false
    }
}

See the /v3/vendors API for more information about the complete list of vendor operations.

Creating an international vendor

Additional configuration for enabling electronic payments

👍
MORE INFORMATION

`paymentPurpose`

Example: Denmark

Response

📘
NOTE

`regulatoryFields`

Example 01: Brazil

Example 02: Australia

Create an international vendor (not US) sample request

Response

Additional configuration for enabling electronic payments

👍MORE INFORMATION

paymentPurpose

Example: Denmark

Response

📘NOTE

regulatoryFields

Example 01: Brazil

Example 02: Australia

Create an international vendor (not US) sample request

Response

👍
MORE INFORMATION

`paymentPurpose`

📘
NOTE

`regulatoryFields`