Resources may contain fields that have fields within them. However, these nested fields are not shown by default when a resource is retrieved. For example, when retrieving a transaction's details, the response you get contains a merchant field, but the details of this field, such as its id and legalName, are not shown in that response.
If you want to retrieve these nested details, you need to add some parameters in the URL to expand the specified fields. The basic format of an expand query parameter is as follows:
/{resource}/{id}?expand={field}
In the example above, to expand the merchant field of a transaction, use the following URL:
/transactions/{id}?expand=merchant
The expand query parameter allows multiple fields separated by a comma (,). Alternatively, you can append another expand query parameter with an ampersand (&) in the URL. Below are the formats:
{resource}/{id}?expand={field1},{field2}
{resource}/{id}?expand={field1}&expand={field2}
For example, if you want to retrieve the details of a transaction's merchant and shopper, you can use any of these URLs:
/transactions/{id}?expand=merchant,shopper
/transactions/{id}?expand=merchant&expand=shopper
For resources that have fields with additional nested layers, you can use a dot (.) to expand those fields as well. The format is as follows:
/{resource}/{id}?expand={field1.field2}
You can have a combination of parameters with different layers. Take a look at the example below:
/transactions/{id}?expand=merchant,account.planList,shopper
Note that the expand query parameter is only supported on GET calls. Using this parameter on other API calls will not have any effect.
In addition, not all fields can be expanded. Fields that can be used as part of the expand query parameter are those that can be retrieved by themselves via GET. In the examples above, merchant, shopper, account, and planList are all fields that are also resources that you can retrieve by themselves. A transaction's type is something that cannot be expanded because the type field is not something that you can retrieve by itself.
Here is a list of fields that can be expanded: merchant, processorAccount, account, planList, order, paymentLink, paymentLinkEvent, paymentSession, hostedCard, forexAdvice, transaction, batch, shopper, storedCard, plan, subscription, notification. Note that this is not a comprehensive list and that it only serves as a quick guide.
To illustrate further, review the two examples of responses below. In the first example, the following URL is used to retrieve a transaction: https://uat.api.converge.eu.elavonaws.com/transactions/dqwjbcmfp64q3jgpkv4cjdjgkrvp. The response is as follows:
{
"href": "https://uat.api.converge.eu.elavonaws.com/transactions/dqwjbcmfp64q3jgpkv4cjdjgkrvp",
"id": "dqwjbcmfp64q3jgpkv4cjdjgkrvp",
"createdAt": "2023-03-16T12:44:32.641Z",
"modifiedAt": "2023-03-16T12:44:33.993Z",
"type": "sale",
"source": "directApiCall",
"merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"processorAccount": "https://uat.api.converge.eu.elavonaws.com/processor-accounts/pxj468g3qfv4xvfy7br2vq27mbjf",
"account": "https://uat.api.converge.eu.elavonaws.com/accounts/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"total": {
"amount": "10.00",
"currencyCode": "EUR"
},
"totalRefunded": null,
"issuerTotal": null,
"salesTax": null,
"conversionRate": null,
"markupRate": null,
"markupRateAnnotation": null,
"parentTransaction": null,
"description": null,
"shopperStatement": null,
"debtorAccount": null,
"customReference": null,
"shopperReference": null,
"processorReference": "B1L41IE5FD8",
"issuerReference": "MSI066282",
"orderReference": null,
"shopperInteraction": "telephoneOrder",
"shopper": null,
"shipTo": null,
"shopperEmailAddress": null,
"shopperIpAddress": null,
"shopperLanguageTag": null,
"shopperTimeZone": null,
"order": null,
"subscription": null,
"credentialOnFileType": "none",
"credentialOnFileData": null,
"card": {
"holderName": "John Doe",
"panToken": {
"token": "9565916908901790188",
"provider": "ELAVON_C2_V1",
"type": "pan"
},
"panFingerprint": "brwmhqf8m7q49xc9wfg6t32hbhxm",
"expirationMonth": 1,
"expirationYear": 2025,
"billTo": null,
"maskedNumber": "XXXX.XXXX.XXXX.1251",
"last4": "1251",
"bin": "510008",
"scheme": "MasterCard",
"brand": "MasterCard Credit",
"fundingSource": "credit",
"issuingBank": "INTERNATIONAL CARD SERVICES BV",
"issuingCountry": "NLD",
"issuingCurrency": "EUR",
"isDebit": "false",
"isCorporate": "false",
"isDccAllowed": "true"
},
"paymentLink": null,
"paymentSession": null,
"createdBy": null,
"modifiedBy": null,
"customFields": null,
"isHeldForReview": false,
"doCapture": true,
"doSendReceipt": true,
"isAuthorized": true,
"authorizationCode": "514433",
"verificationResults": {
"name": "unsupported",
"securityCode": "unprovided",
"addressStreet": "unprovided",
"addressPostalCode": "unprovided",
"threeDSecureV1": "unprovided",
"threeDSecureV2": "unprovided"
},
"state": "captured",
"batch": null,
"relatedTransactions": [
],
"failures": [
],
"history": [
{
"state": "authorized",
"modifiedAt": "2023-03-16T12:44:32.641Z",
"modifiedBy": null
}
]
}In the second example, the following URL is used: https://uat.api.converge.eu.elavonaws.com/transactions/dqwjbcmfp64q3jgpkv4cjdjgkrvp?expand=merchant,account.planList. Take note of the merchant and account fields, including the planList field within account, in the response below.
{
"href": "https://uat.api.converge.eu.elavonaws.com/transactions/dqwjbcmfp64q3jgpkv4cjdjgkrvp",
"id": "dqwjbcmfp64q3jgpkv4cjdjgkrvp",
"createdAt": "2023-03-16T12:44:32.641Z",
"modifiedAt": "2023-03-16T12:44:33.993Z",
"type": "sale",
"source": "directApiCall",
"merchant": {
"href": "https://uat.api.converge.eu.elavonaws.com/merchants/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"id": "8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"legalName": "DAN TANGERMAN",
"isDemo": false
},
"processorAccount": "https://uat.api.converge.eu.elavonaws.com/processor-accounts/pxj468g3qfv4xvfy7br2vq27mbjf",
"account": {
"href": "https://uat.api.converge.eu.elavonaws.com/accounts/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"id": "8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"createdAt": "2021-04-27T21:35:12.821Z",
"modifiedAt": "2021-04-27T21:35:12.821Z",
"merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"name": "DAN TANGERMAN",
"description": null,
"planList": {
"href": "https://uat.api.converge.eu.elavonaws.com/plan-lists/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"id": "8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"createdAt": "2021-04-27T21:35:12.876Z",
"modifiedAt": "2021-04-27T21:35:12.876Z",
"merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"name": "DAN TANGERMAN",
"description": null
}
},
"total": {
"amount": "10.00",
"currencyCode": "EUR"
},
"totalRefunded": null,
"issuerTotal": null,
"salesTax": null,
"conversionRate": null,
"markupRate": null,
"markupRateAnnotation": null,
"parentTransaction": null,
"description": null,
"shopperStatement": null,
"debtorAccount": null,
"customReference": null,
"shopperReference": null,
"processorReference": "B1L41IE5FD8",
"issuerReference": "MSI066282",
"orderReference": null,
"shopperInteraction": "telephoneOrder",
"shopper": null,
"shipTo": null,
"shopperEmailAddress": null,
"shopperIpAddress": null,
"shopperLanguageTag": null,
"shopperTimeZone": null,
"order": null,
"subscription": null,
"credentialOnFileType": "none",
"credentialOnFileData": null,
"card": {
"holderName": "John Doe",
"panToken": {
"token": "9565916908901790188",
"provider": "ELAVON_C2_V1",
"type": "pan"
},
"panFingerprint": "brwmhqf8m7q49xc9wfg6t32hbhxm",
"expirationMonth": 1,
"expirationYear": 2025,
"billTo": null,
"maskedNumber": "XXXX.XXXX.XXXX.1251",
"last4": "1251",
"bin": "510008",
"scheme": "MasterCard",
"brand": "MasterCard Credit",
"fundingSource": "credit",
"issuingBank": "INTERNATIONAL CARD SERVICES BV",
"issuingCountry": "NLD",
"issuingCurrency": "EUR",
"isDebit": "false",
"isCorporate": "false",
"isDccAllowed": "true"
},
"paymentLink": null,
"paymentSession": null,
"createdBy": null,
"modifiedBy": null,
"customFields": null,
"isHeldForReview": false,
"doCapture": true,
"doSendReceipt": true,
"isAuthorized": true,
"authorizationCode": "514433",
"verificationResults": {
"name": "unsupported",
"securityCode": "unprovided",
"addressStreet": "unprovided",
"addressPostalCode": "unprovided",
"threeDSecureV1": "unprovided",
"threeDSecureV2": "unprovided"
},
"state": "captured",
"batch": null,
"relatedTransactions": [
],
"failures": [
],
"history": [
{
"state": "authorized",
"modifiedAt": "2023-03-16T12:44:32.641Z",
"modifiedBy": null
}
]
}