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 an an IBAN `accountNumber`) - `type`

regulatoryFields and paymentPurpose are additional required fields for enabling electronic payments to international vendors (not United States) in specific countries. You can get the required information with GET /v3/vendors/configuration/international-payments.

Field Description

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

paymentPurpose Payment purpose information for compliance with international payment rules of the vendor country.

Either the text field or code object is required for vendor payments in an international currency (not USD). This information is based on vendor country, bill currency, and vendor account type.

NOTE: There are vendor countries, like Japan, that do not require any payment purpose information. For such countries, specifying paymentPurpose in your request results in an error.

Field	Description
`regulatoryFields`	International bank account regulatory information. The `name` and `value` fields are required for each required bank account regulatory field.
`paymentPurpose`	Payment purpose information for compliance with international payment rules of the vendor country. Either the `text` field or `code` object is required for vendor payments in an international currency (not USD). This information is based on vendor country, bill currency, and vendor account type. NOTE: There are vendor countries, like Japan, that do not require any payment purpose information. For such countries, specifying `paymentPurpose` in your request results in an error.

See the /v3/vendors API for more information about the other vendor fields you can set.

Get international payments configuration sample request

In this cURL example, international payments configuration is retrieved for a vendor in Germany. The bill currency is set as euros.

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

Response

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

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

Create an international vendor (not US) sample request

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

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": "Musterstrasse 17",
    "city": "Berlin",
    "zipOrPostalCode": "10115",
    "country": "DE"
  },
  "paymentInformation": {
    "payeeName": "Happy Music Supplies International",
    "bankCountry": "DE",
    "paymentCurrency": "EUR",
    "bankAccount": {
      "nameOnAccount": "Bill Vendorson",
      "accountNumber": "DE89370400440532013000",
      "type": "CHECKING"
    },
    "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": "Musterstrasse 123",
    "city": "Berlin",
    "zipOrPostalCode": "12345",
    "country": "DE"
  },
  "paymentInformation": {
    "payeeName": "Happy Music Supplies International",
    "bankCountry": "DE",
    "paymentCurrency": "EUR",
    "payByType": "INTERNATIONAL_E_PAYMENT",
    "payBySubType": "WIRE",
    "virtualCard": {
      "status": "UNENROLLED"
    },
    "bankAccount": {
      "nameOnAccount": "Bill Vendorson",
      "accountNumber": "******************3000",
      "routingNumber": "37040044",
      "type": "CHECKING",
      "ownerType": "BUSINESS",
      "bankInfo": {
        "swiftBIC": "COBADEFF",
        "countryISO": "DE",
        "institutionName": "Commerzbank",
        "address": {
          "line1": "Venloer Str. 288",
          "city": "Köln",
          "zipOrPostalCode": "50447",
          "country": "Germany"
        }
      }
    },
    "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-30T22:18:22.000Z",
  "updatedTime": "2024-12-30T22:18:22.000Z",
  "balance": {
    "amount": 0
  },
  "autoPay": {
    "enabled": false
  },
  "networkStatus": "NOT_CONNECTED"
}

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