Transactions API

The transactions API implements a number of methods to filter the response data that you receive.

TIP

You can use the following mechanisms individually or in combination.

Filtering

The transaction API endpoint allows you to apply filters in the query string to return only a subset of the available transactions.

WARNING

The V1 API will always filter the response based on the authentication token that is provided. A consumer token can only retrieve transactions that belong to the user / session.

WARNING

The V2 Partner API will filter transactions based on group / franchise / location permissions that they have been assigned.

Available Filters

We are able to filter using the following properties:

UUID

Specify the particular UUID that you are interested in

Status

Request either complete (1) or incomplete (0) transactions only

Vehicle Identifiers

Request only transactions for vehicles with matching identifiers

Examples

Request all complete transactions only

GET /api/transaction?filter[status]=1

Request a specific transaction

GET /api/transaction?filter[uuid]=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01

Request transactions for vehicle with Stock ID 1234

GET /api/transaction?filter[identifiers][ndstockid]=1234

Request transactions for vehicle with external ID 1234

GET /api/transaction?filter[identifiers][salesmasterid]=1234

Response Expansion

Some of the online payments API endpoints will accept optional "expand" parameters, which will allow additional related entities to be returned with the subject.

For example, when requesting a transaction you may choose to also populate the response with the payment records that belong to the transaction and/or the extras that have been selected.

Available records

The related records that are available are listed in the API response:

{
	"_expand": "vehicle,ndMeta,extras,deliveryCollection,selectedPaymentMethod,financeProposal,valuation,customer,payments,financeDefaults",
	"data": [
    ....

Examples

Example 1: Request all transactions and include payment data in the response

Request

GET /api/v2/transaction/?expand=payments

Response

{
	"_expand": "vehicle,ndMeta,extras,deliveryCollection,selectedPaymentMethod,financeProposal,valuation,customer,payments,financeDefaults",
	"data": [
		{
			"uuid": "8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01",
			"status": 1,
			"editable": true,
			"isDeleted": 0,
			"priceAdjustment": {
				"payment": true,
				"priceRule": true
			},
			"externalRedirect": 0,
			"incentive": false,
			"document_id": null,
			"preselectedPaymentMethod": "deposit",
			"referrerUrl": "https://mercedes-benz-mena.auto.gforcestestlink.com/stock/15539861-mercedes-benz-a-class-mercedes-benz%20a35%20amg%204m%20hatchback%20premium%20plus/",
			"guestEmail": null,
			"payments": [
				{
					"id": 1109044,
					"transaction_id": 2968012,
					"hash": "3542b7396d521b6ca272ea81425f7bc3cae8f382",
					"token": "pm_1MeygGJyyR5os2qGiE9kfzaE",
					"reference": "N/A",
					"provider_references": null,
					"type": 1,
					"product_identifier": "PAY",
					"value": "1000.00",
					"status": 1,
					"message": null,
					"is_selected": null,
					"settings": null,
					"details": {
						"type": "card",
						"brand": "visa",
						"method": null,
						"funding": "credit"
					},
					"transaction_completed_at": "2023-02-24 14:39:15",
					"created_at": 1677235115,
					"created_by": "v1/transaction/create",
					"updated_at": 1677236133,
					"updated_by": "v2/transaction/update",
					"gateway_id": 1862
				},
				{
					"id": 1109049,
					"transaction_id": 2968012,
					"hash": "639060c81f8ed894bcf9733b15d574281c2c6550",
					"token": null,
					"reference": "0f67d7fd-8173-43a5-9df8-5649384d7dc2",
					"provider_references": null,
					"type": 8,
					"product_identifier": "PAY",
					"value": "1000.00",
					"status": 1,
					"message": "Payment",
					"is_selected": null,
					"settings": null,
					"details": "Cash payment created on Friday, 24 February 2023 10:42:12. Reference: Payment",
					"transaction_completed_at": null,
					"created_at": 1677235333,
					"created_by": "v2/payment/create",
					"updated_at": 1677235333,
					"updated_by": "v2/payment/create",
					"gateway_id": null
				},
				{
					"id": 1109055,
					"transaction_id": 2968012,
					"hash": "eb45333edc2ca7d821f6fff7e9a402c721e765d6",
					"token": null,
					"reference": "N/A",
					"provider_references": null,
					"type": 0,
					"product_identifier": "PAY",
					"value": "211000.00",
					"status": 0,
					"message": null,
					"is_selected": 1,
					"settings": null,
					"details": null,
					"transaction_completed_at": null,
					"created_at": 1677235663,
					"created_by": "v1/transaction/update",
					"updated_at": 1677269039,
					"updated_by": "v2/transaction/update",
					"gateway_id": null
				}
			]
		}
	],
	"_links": {
		"self": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&expand=payments&page=1&per-page=10"
		},
		"first": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&expand=payments&page=1&per-page=10"
		},
		"last": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&expand=payments&page=1&per-page=10"
		}
	},
	"_meta": {
		"totalCount": 1,
		"pageCount": 1,
		"currentPage": 1,
		"perPage": 10
	}
}

Example 2: Request all transactions and include payment data and delivery method in the response

Request

GET /api/v2/transaction/?expand=payments,deliveryCollection

Response

{
	"_expand": "vehicle,ndMeta,extras,deliveryCollection,selectedPaymentMethod,financeProposal,valuation,customer,payments,financeDefaults",
	"data": [
		{
			"uuid": "8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01",
			"status": 1,
			"editable": true,
			"isDeleted": 0,
			"priceAdjustment": {
				"payment": true,
				"priceRule": true
			},
			"externalRedirect": 0,
			"incentive": false,
			"document_id": null,
			"preselectedPaymentMethod": "deposit",
			"referrerUrl": "https://mercedes-benz-mena.auto.gforcestestlink.com/stock/15539861-mercedes-benz-a-class-mercedes-benz%20a35%20amg%204m%20hatchback%20premium%20plus/",
			"guestEmail": null,
			"deliveryCollection": {
				"is_default": 1,
				"is_live": 1,
				"lead_time": 3,
				"method": "Delivery ",
				"order": 2,
				"price": "0.00",
				"hash": "afc875ad48c4500de064ce914f6ea4b961bb7f6c",
				"preferred_date": "2023-02-27",
				"delivery_date": "2023-02-27",
				"delivery_status": "To be confirmed",
				"minDate": "2023-05-08",
				"maxDate": "2024-05-05",
				"type": 2,
				"units": null,
				"originalPrice": "0.00"
			},
			"payments": [
				{
					"id": 1109044,
					"transaction_id": 2968012,
					"hash": "3542b7396d521b6ca272ea81425f7bc3cae8f382",
					"token": "pm_1MeygGJyyR5os2qGiE9kfzaE",
					"reference": "N/A",
					"provider_references": null,
					"type": 1,
					"product_identifier": "PAY",
					"value": "1000.00",
					"status": 1,
					"message": null,
					"is_selected": null,
					"settings": null,
					"details": {
						"type": "card",
						"brand": "visa",
						"method": null,
						"funding": "credit"
					},
					"transaction_completed_at": "2023-02-24 14:39:15",
					"created_at": 1677235115,
					"created_by": "v1/transaction/create",
					"updated_at": 1677236133,
					"updated_by": "v2/transaction/update",
					"gateway_id": 1862
				},
				{
					"id": 1109049,
					"transaction_id": 2968012,
					"hash": "639060c81f8ed894bcf9733b15d574281c2c6550",
					"token": null,
					"reference": "0f67d7fd-8173-43a5-9df8-5649384d7dc2",
					"provider_references": null,
					"type": 8,
					"product_identifier": "PAY",
					"value": "1000.00",
					"status": 1,
					"message": "Payment",
					"is_selected": null,
					"settings": null,
					"details": "Cash payment created on Friday, 24 February 2023 10:42:12. Reference: Payment",
					"transaction_completed_at": null,
					"created_at": 1677235333,
					"created_by": "v2/payment/create",
					"updated_at": 1677235333,
					"updated_by": "v2/payment/create",
					"gateway_id": null
				},
				{
					"id": 1109055,
					"transaction_id": 2968012,
					"hash": "eb45333edc2ca7d821f6fff7e9a402c721e765d6",
					"token": null,
					"reference": "N/A",
					"provider_references": null,
					"type": 0,
					"product_identifier": "PAY",
					"value": "211000.00",
					"status": 0,
					"message": null,
					"is_selected": 1,
					"settings": null,
					"details": null,
					"transaction_completed_at": null,
					"created_at": 1677235663,
					"created_by": "v1/transaction/update",
					"updated_at": 1677269039,
					"updated_by": "v2/transaction/update",
					"gateway_id": null
				}
			]
		}
	],
	"_links": {
		"self": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&expand=payments%2CdeliveryCollection&page=1&per-page=10"
		},
		"first": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&expand=payments%2CdeliveryCollection&page=1&per-page=10"
		},
		"last": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&expand=payments%2CdeliveryCollection&page=1&per-page=10"
		}
	},
	"_meta": {
		"totalCount": 1,
		"pageCount": 1,
		"currentPage": 1,
		"perPage": 10
	}
}

Property Selection

The transaction response object is large and when we use response expansion to retrieve related records it can get even larger. To reduce the size of the response and therefore the download time to retrieve data, you can use "property selection" to retrieve only the properties that you need to consume.

Property selection can be applied to both the transaction and related records

Examples

Example 1: Request all transactions but only return uuid and status

Request

GET /api/v2/transaction/?fields=uuid,status

Response

{
	"_expand": "vehicle,ndMeta,extras,deliveryCollection,selectedPaymentMethod,financeProposal,valuation,customer,payments,financeDefaults",
	"data": [
		{
			"uuid": "8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01",
			"status": 1
		}
	],
	"_links": {
		"self": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&fields=uuid%2Cstatus&page=1&per-page=10"
		},
		"first": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&fields=uuid%2Cstatus&page=1&per-page=10"
		},
		"last": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&fields=uuid%2Cstatus&page=1&per-page=10"
		}
	},
	"_meta": {
		"totalCount": 1,
		"pageCount": 1,
		"currentPage": 1,
		"perPage": 10
	}
}

Example 2: Request all transactions but only return transaction uuid and key details from each payment record

Request

GET /api/v2/transaction/?expand=payments&fields=uuid,payments.value,payments.type,payments.status

Response

{
	"_expand": "vehicle,ndMeta,extras,deliveryCollection,selectedPaymentMethod,financeProposal,valuation,customer,payments,financeDefaults",
	"data": [
		{
			"uuid": "8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01",
			"payments": [
				{
					"type": 1,
					"value": "1000.00",
					"status": 1
				},
				{
					"type": 8,
					"value": "1000.00",
					"status": 1
				},
				{
					"type": 0,
					"value": "211000.00",
					"status": 0
				}
			]
		}
	],
	"_links": {
		"self": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&expand=payments&fields=uuid%2Cpayments.value%2Cpayments.type%2Cpayments.status&page=1&per-page=10"
		},
		"first": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&expand=payments&fields=uuid%2Cpayments.value%2Cpayments.type%2Cpayments.status&page=1&per-page=10"
		},
		"last": {
			"href": "https://payments-2.netdirector.co.uk/v2/transaction?filter%5Buuid%5D=8e64f15c-96be-5154-b1b9-ff54802a09d3-EU01&expand=payments&fields=uuid%2Cpayments.value%2Cpayments.type%2Cpayments.status&page=1&per-page=10"
		}
	},
	"_meta": {
		"totalCount": 1,
		"pageCount": 1,
		"currentPage": 1,
		"perPage": 10
	}
}