Invoice Collection
Modified on: 2026-03-05 14:03
TABLE OF CONTENTS
- Invoice Collection Request Schema
- Invoice Collection Request Example
- Invoice Collection Request Response Schema
- Invoice Collection Request Response Example
The Invoice collection call type is used by different personas such as TMCs, payment providers, Distribution channels and others, with the goal of asking the hotel to send an invoice for a booking to a specific email. This type of call is a trigger post stay and it is one of the most relevant problems within the Corporate distribution.
Invoice Collection Request Schema
Your system will use this endpoint to submit new call requests to DerbySoft. To ensure successful processing:
- All mandatory fields must be included in the request payload.
- The check-out date must be in the past; requests with future check-out dates will be rejected.
- Once a valid request is submitted, DerbySoft will begin initiating calls to the hotel starting five days before the check-in date.
Request (METHOD: POST)
| Level | Field Name | Num. Occ. | Data type | Format | Description | Example |
|---|---|---|---|---|---|---|
| 1 | purpose | 1 | object | Object used to share call request data to verify. | - | |
| 2 | callType | 1 | Enum | INVOICE_COLLECTION | tbd | INVOICE_COLLECTION |
| 2 | invoiceCollection | 1 | object | Object used to share reservation information | - | |
| 3 | toEmail | 1 | string | min 6 char max 254 char | email where the invoice needs to be sent | barcelonaFrontdesk@gmail.com |
| 3 | transactionAmount | 0..1 | decimal | Min 1 Char | Amount eligible for invoicing for the specified reservation. | 156 |
| 3 | transactionCurrency | 0..1 | string | 3 char code | Currency code following ISO 4217 | EUR |
| 3 | transactionDate | 0..1 | date | yyyy-mm-dd | Date of when the transaction was done | 2025-07-25 |
| 3 | lastFourDigits | 0..1 | intenger | Min 4 Max 4 | Last four digits of the credit card use in the transaction | 1235 |
| 3 | corporateName | 0..1 | string | Max 100 char | Customer’s full corporation name | Derbysoft |
| 3 | corporateAddress | 0..1 | string | Max 100 char | Customer’s full corporation address | Av. Diagonal, 472, p.8 pta. 3, Gracia, 08006 Barcelona |
| 3 | vatNumber | 0..1 | string | Max 20 | A unique tax identification number assigned to a business or individual by a national tax authority for the purpose of Value Added Tax (VAT) reporting and compliance. | ES123456789X |
| 1 | recipient | 1 | object | |||
| 2 | phoneNumber | 1 | string | “+” followed by digits Min 6 Max 20 | Telephone number associated with the property. Including “+” and country code | +34932952800 |
| 1 | callData | 1 | object | - | This object is used to group all data information | - |
| 2 | onBehalfOrg | 0..1 | string | Max 100 char | When provided it will be used by the AI agent that it is calling on behalf of that company. If not provided it will use your company name | Barcelona Travel |
| 2 | property | 1 | object | - | Object used to shara Property information | - |
| 3 | name | 1 | string | Max lenght 200 char | Hotel name | W Barcelona, MGM Grand, Sun Hotel |
| 3 | distributorHotelID | 0..1 | string | Max length TBD | Unique Derbysoft identifiyer for hotel | ABCDE |
| 3 | gdsId | 0..1 | string | Max lenght 200 char | Unique GDS identifiyer for hotel | WH BCN183 WH 45626 WH 101944 WH 3183 |
| 3 | address | 1 | object | - | Object used to share address associated with the hotel. | - |
| 4 | addressLine1 | 1 | string | Max lenght 200 char | Free-form address details. | Plaça Rosa Del Vents 1 |
| 4 | addressLine2 | 0..1 | string | Max lenght 200 char | Free-form address details. | Final, Pg. de Joan de Borbó |
| 4 | cityName | 1 | string | Max lenght 100 char | City or town where the hotel is located | Barcelona |
| 4 | StateProv | 0..1 | string | Max lenght 100 char | State or Province name (e.g., Texas).State, province, or region name needed to identify hotel location. | |
| 4 | countryISO | 1 | string | Min 2 Max 2 | ISO 3166-1 Listing Country code | ES |
| 2 | guest | 1 | object | - | object used to share guest details for the reservation. | - |
| 3 | firstName | 1 | string | Max lenght 100 char | Given, or first, name of the guest. | Leo |
| 3 | lastName | 1 | string | Max lenght 100 char | Family, or last, name of the guest. | Messi |
| 3 | company | 0..1 | string | Max lenght 200 char | Company name where guest works | FCB Barcelona |
| 2 | reservation | 1 | object | - | Object used to share all reservation details | - |
| 3 | hotelConfirmationId | 0..1 | string | Max lenght 50 char | Unique identifier for the booking in distributor system | 012AC983 |
| 3 | checkIn | 1 | date | yyyy-mm-dd | Check in date - ISO 8601. Check in date cannot be in the past. | 2026-05-13 |
| 3 | checkOut | 1 | date | yyyy-mm-dd | Check outdate - ISO 8601. Check out date cannot be in the past or higher that check in date. | 2026-06-14 |
Invoice Collection Request Example
Call Request success example with all verification parameters
{
"purpose": {
"callType": "INVOICE_COLLECTION",
"invoiceCollection": {
"transactionAmount": "1000",
"transactionCurrency": "EUR",
"transactionDate": "2025-07-17",
"lastFourDigits": "1234",
"corporateName": "Derbysoft",
"corporateAddress": "Av. Diagonal, 472, p.8 pta. 3, Gracia, 08006 Barcelona",
"vatNumber": "ES123456789X",
"toEmail": "invoice@barcelonatavel.es"
}
},
"recipient": {
"phoneNumber": "+34981811552"
},
"callData": {
"onBehalfOrg": "BCN travel"
"property": {
"name": "Galicia Paradise",
"distributorHotelID": "123",
"gdsId": "456",
"address": {
"addressLine1": "Rua de Castelao",
"addressLine2": "string",
"cityName": "Vigo",
"stateProv": "",
"countryISO": "SP"
}
},
"guest": {
"firstName": "Iago",
"lastName": "Aspas",
"company": ""
},
"reservation": {
"hotelConfirmationId": "string",
"checkIn": "2025-02-01",
"checkOut": "2025-02-10"
}
}
}Call Request success example with only VCC
{
"purpose": {
"callType": "INVOICE_COLLECTION",
"invoiceCollection": {
"transactionAmount": "",
"transactionCurrency": "",
"transactionDate": "",
"lastFourDigits": "1234",
"corporateName": "",
"corporateAddress": "",
"vatNumber": "",
"toEmail": "invoice@barcelonatavel.es"
}
},
"recipient": {
"phoneNumber": "+34981811552"
},
"callData": {
"onBehalfOrg": "BCN travel"
"property": {
"name": "Galicia Paradise",
"distributorHotelID": "123",
"gdsId": "456",
"address": {
"addressLine1": "Rua de Castelao",
"addressLine2": "string",
"cityName": "Vigo",
"stateProv": "",
"countryISO": "SP"
}
},
"guest": {
"firstName": "Iago",
"lastName": "Aspas",
"company": ""
},
"reservation": {
"hotelConfirmationId": "string",
"checkIn": "2025-02-01",
"checkOut": "2025-02-10"
}
}
}Call Request success example only with email
{
"purpose": {
"callType": "INVOICE_COLLECTION",
"invoiceCollection": {
"transactionAmount": "",
"transactionCurrency": "",
"transactionDate": "",
"lastFourDigits": "",
"corporateName": "",
"corporateAddress": "",
"vatNumber": "",
"toEmail": "invoice@barcelonatavel.es"
}
},
"recipient": {
"phoneNumber": "+34981811552"
},
"callData": {
"onBehalfOrg": "BCN travel"
"property": {
"name": "Galicia Paradise",
"distributorHotelID": "123",
"gdsId": "456",
"address": {
"addressLine1": "Rua de Castelao",
"addressLine2": "string",
"cityName": "Vigo",
"stateProv": "",
"countryISO": "SP"
}
},
"guest": {
"firstName": "Iago",
"lastName": "Aspas",
"company": ""
},
"reservation": {
"hotelConfirmationId": "string",
"checkIn": "2025-02-01",
"checkOut": "2025-02-10"
}
}
}Call Request error example missing mandatory field to Email
{
"purpose": {
"callType": "INVOICE_COLLECTION",
"invoiceCollection": {
"transactionAmount": "1000",
"transactionCurrency": "EUR",
"transactionDate": "2025-07-17",
"lastFourDigits": "1234",
"corporateName": "Derbysoft",
"corporateAddress": "Av. Diagonal, 472, p.8 pta. 3, Gracia, 08006 Barcelona",
"vatNumber": "ES123456789X",
"toEmail": ""
}
},
"recipient": {
"phoneNumber": "+34981811552"
},
"callData": {
"onBehalfOrg": "BCN travel"
"property": {
"name": "Galicia Paradise",
"distributorHotelID": "123",
"gdsId": "456",
"address": {
"addressLine1": "Rua de Castelao",
"addressLine2": "string",
"cityName": "Vigo",
"stateProv": "",
"countryISO": "SP"
}
},
"guest": {
"firstName": "Iago",
"lastName": "Aspas",
"company": ""
},
"reservation": {
"hotelConfirmationId": "string",
"checkIn": "2025-02-01",
"checkOut": "2025-02-10"
}
}
}Invoice Collection Request Response Schema
Once a call request is submitted, DerbySoft's system will initiate a response to your system indicating whether the request was successfully parsed or if an error occurred.
- If the request is successful, the response will include a Call Request ID.
- This ID is essential and must be securely stored on your side.
- You will need this ID for any future operations related to the request, such as checking the call status or canceling the call request.
HTTP Response
| Level | Field Name | Num.Occ. | Datatype | Format | Description | Example |
|---|---|---|---|---|---|---|
| 1 | success | 1 | boolean | True False | True: call request was created successfully in our system False: call request was not created in our system | TRUE |
| 1 | callRequestId | 0..1 | String | 16 Char | Unique identifier for a call request, it must be stored to be able to request call status or cancel the call request | 66a1b2c3d4e5f678 |
| 1 | error | 0..1 | object | - | Object used for error description. | - |
| 2 | code | 1 | String | 100 | Short error description | BAD_REQUEST |
| 2 | message | 1 | String | 500 | Long error description | "Invalid request: call type cannot be empty" |
Invoice Collection Request Response Example
Call request creation success example
{
"success": true,
"callRequestId": "66a1b2c3d4e5f678"
}Call request creation error example
{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request: call type cannot be empty"
}
}Did you find it helpful? Yes No
Send feedbackSorry we couldn't be helpful. Help us improve this article with your feedback.