Request Money (Invoice)

The Request Money (Send Invoice) feature allows for a user to "request payment" from a party using an email. Users of the API can use this functionality as part of an existing invoicing capability for a different provider.

Request Money from a business in your local currency (or USD, Euro, GBP)

You can request payment from a business and attach an invoiced using createInvoice. For example:

POST https://sandbox-api.veem.com/veem/v1.2/invoices

📘
Headers
Three headers are required to use this endpoint.
Required Headers
Name
Type
Required
Description
Authorization
string
Yes
Bearer token (OAuth 2.0) This header holds the bearer token required to use Veem's public API, and belongs to the owner account. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows: Bearer c047594b-082c-4da1-be89-08fe3770f4b3
See Get Access Token section to generate your Bearer token
X-Request-Id
string
Yes
This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows:
48855846-628d-4177-b071-80332a116f0a
Content-Type
string
Yes
The content type of the request. Must be application/json

Name	Type	Required	Description
`Authorization`	`string`	Yes	Bearer token (OAuth 2.0) This header holds the bearer token required to use Veem's public API, and belongs to the owner account. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows: `Bearer c047594b-082c-4da1-be89-08fe3770f4b3` See Get Access Token section to generate your Bearer token
`X-Request-Id`	`string`	Yes	This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows: `48855846-628d-4177-b071-80332a116f0a`
`Content-Type`	`string`	Yes	The content type of the request. Must be `application/json`

Request payload

{
    "notes": "Invoice test",
    "payer": {
        "type": "Business",
        "email": "[email protected]",
        "phone": "5511941618581",
        "lastName": "last_name",
        "firstName": "first_name",
        "countryCode": "US",
        "businessName": "US Payer",
        "bank": {
            "bankAccountNumber": "12345678",
            "bankInstitutionNumber": "879",
            "bankName": "Bank of France",
            "currencyCode": "USD",
            "iban": "FR1420041010050500013M02606",
            "isoCountryCode": "US",
            "routingNumber": "041215032",
            "swiftBic": "CUCXCATT",
            "transitCode": "45622"
        },
        "business": {
            "address":{
                "countryCode":"CA",
                "street":"123 Main",
                "postalCode":"123456",
                "province":"Cognac",
                "city":"Marcel"
            },
            "entity": "Corporation",
            "taxIdNumber": "XAXX010101000",
            "websiteUrl": "https://test.com"
        },
        "phoneCountryCode": "+1",
        "subIndustry": "Software",
        "industry": "Software, IT and Telecommunications"
    },
    "amount": {
        "number": 100,
        "currency": "USD"
    },
    "fundingMethod": {
        "id": 55115,
        "type": "Card"
    },
    "purposeOfPayment": "Services",
    "purposeOfPaymentDescription": "Services",
    "extraInfo": {
        "customInfo": {
            "custom1": "test"
        }
    },
    "goodFundsPayment" : false,
    "sweepToWalletId" : 51244, // See Partner Notes
    "onBehalfAccountId": 944208 // See Partner Notes
}

Request Parameters

The following table contains detailed information on the payload's parameters, such as the parameter name, whether it is mandatory or not, formatting (if applicable), and size of the parameter. You can retrieve various fields such as countryCode, bankName, bankCode, swiftCode, and purposeOfPayment from the Country-Currency-Map endpoint. Please refer to the following link: country-currency-map

Parameter	Mandatory?	Format/Values	Size (in chars)
notes	No	String	128 (Max)
payer.firstName	Yes	String	64 (Max)
payer.lastName	Yes	String	64 (Max)
payer.email	Yes	String	254 (Max)
payer.phone	Yes	String	32 (Max)
payer.countryCode	Yes	ISO 3166-1 alpha-2 standard (eg. US, BE, BT etc)	2
payer.type	Yes	Business or Personal
payer.industry	Yes	Agriculture Business Services Construction Consumer Services Education Energy, Utilities, Waste & Minerals Finance, Insurance Government, Organizations Holding Companies & Conglomerates Hospitality, Recreation & Tourism Hospitals, Clinics & Healthcare Services Law Firms & Legal Services Manufacturing Media, Arts & Entertainment Real Estate Retail Trade Software, IT and Telecommunications Transportation, Warehousing, Wholesale
payer.subIndustry	Yes	Note*: Subindustry is unique to each industry, and is impractical to list all of them here. Subindustry information can be found below the table eg. For Agriculture, one can use the Crops subindustry
payer.businessName	Yes	String	128 (Max)
payer.phoneCountryCode	Yes	Country code (such as +1 for US or Canada, +31 for Netherlands etc. More info available below the table) Note*: The + prefixmust be included in the parameter	2-5
payer.business.websiteUrl	No	String, e.g. "https://test.com"	2048 (Max)
payer.business.address.countryCode	Yes	ISO 3166-1 alpha-2 standard (eg. US, BE, BT etc)	2
payer.business.address.street	Yes	String	128 (Max)
payer.business.address.province	Yes* (if no state is provided)	String	64 (Max)
payer.business.address.state	Yes*(if no province is provided)	String	64 (Max)
payer.business.address.postalCode	Yes	String	64 (Max)
payer.business.address.city	Yes	String	64 (Max)
payer.business.entity	Yes	For Business: Corporation, Company, ForeignCompany, GeneralPartnership, JointVenture, LimitedCompany, LimitedPartnership, NonProfit, Partnership, PublicCompany, Trust, UnlimitedCompany, SoleProprietorship, LLC or Representative\ For Personal*: Contractor, SoleProprietorship, Freelancer, SideProject or PersonalUse\ Note**: If the business entity provided does not match the expected account type, the API will return a 400 Bad Request error. This validation ensures that a business entity is not incorrectly used with a personal account type, and vice versa.
payer.business.taxIdNumber	Yes	String	32 (Max)
payer.bank.isoCountryCode	Yes	ISO 3166-1 alpha-2 standard (eg. US, BE, BT etc)	2
payer.bank
payer.bank.bankName	Yes	String (Note: Bank name and bank routing number MUST be valid)	128 (Max)
payer.bank.currencyCode	Yes	Currency Code (ISO 4217)	3
payer.bank.bankAccountNumber	Yes	String Note*: Make sure the bank account number is the one associated with thepayer's account
payer.bank.routingNumber	Yes	Refer to your financial institution of choice for the correct routingNumber for said institution
payer.bank.swiftBic	Yes*(ifpayer is a non-US account)	String	64 (Max)
payer.bank.bankInstitutionNumber	Yes*(ifpayer is a non-US account)	String
payer.bank.bic	Yes*(ifpayer is a non-US account)	String	64 (Max)
payer.bank.iban	Yes*(ifpayer is a non-North American account)	String	34 (Max)
amount.number	Yes	BigDecimal
amount.currency	Yes	Currency Code (ISO 4217)	3
fundingMethod.id	Yes	Long (Bank ID of payer)
fundingMethod.type	Yes	One of the following values*: "Bank", "External", "Cheque", "Card", "Wallet" "VirtualCard"
goodFundsPayment	No	Boolean
accountId	No	Number

👍
Partner Notes:

If sweepToWalletId is present we are moving the funds to the specified wallet ID. If it is not present we try to find the credit default funding method.

A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.

onBehalfAccountId is an optional parameter, this needs to be included on the request body in case of partner making an API request on behalf of their customer. This is the customer Veem accountId.

Response payload

{
    "requestId": "3974240f-9ef5-474f-9412-667b34a12864",
    "amount": {
        "number": 100.00,
        "currency": "USD"
    },
    "notes": "Invoice test",
    "payer": {
        "email": "[email protected]",
        "countryCode": "US",
        "phone": "tel:+1-415-566-3305"
    },
    "sweepToWalletId": 2053,
    "goodFundsPayment": false,
    "id": 159776,
    "status": "Sent",
    "exchangeRate": {
        "fromAmount": 50.00,
        "fromCurrency": "USD",
        "toAmount": 50.00,
        "toCurrency": "USD"
    },
    "claimLink": "https://apps.qa.veem.com/CustomerApp/Dashboard/Claim/Request/PaymentC?paymentId=159776-Invoice",
    "invoiceExtraInfo": {
        "id": 0,
        "payeeFundingMethodId": 51244,
        "payeeFundingMethodType": "WALLET"
    },
    "payeeAccountId": 379692,
    "payerAccountId": 379691
}