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.

FieldDescription
nameVendor name
accountTypeVendor account type (BUSINESS, PERSON, or NONE)
emailVendor email address
phoneVendor phone number
addressVendor 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
paymentInformationVendor 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.

FieldDescription
regulatoryFieldsInternational bank account regulatory information. The name and value fields are required for each required bank account regulatory field.
paymentPurposePayment 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.sandbox.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.sandbox.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",
      "createdBy": "{user_id}",
      "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
  }
}

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