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
andregulatoryFields
information after creating an international vendor, useGET /v3/vendors/{vendorId}/configuration
to get the required configuration for your created vendor. See the /v3/vendors/{vendorId}/configuration API for more information.
paymentPurpose
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
orcode
: You must set either thetext
orcode
field for vendor payments in an international currency (not USD). You cannot set both fields. -
Information source: Learn about which field to set (
text
orcode
) withGET /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 withGET /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 thevalidations
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
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.
Updated 11 days ago