Card data requests
Learn about the different types of card data you can request with the Data API.
You can also use the Data API to get balance and transaction data associated with a user's card.
However, some providers do not support the cards scope. You can make a GET request to /providers to discover what data each provider supports by checking the scopes parameter provided in the response.
How far back you can request transactions from varies depending upon provider.
Get data for all cards
To get all stored user cards and associated data, make a GET request to /cards .
You need to enable the cards scope in Console to make this request.
/cards request
/cards requestcurl -H "Authorization: Bearer ${access_token}" \
https://api.truelayer.com/data/v1/cards
/cards response example
/cards response example{
"results": [
{
"account_id": "f7b093437032c216d4350b7d442b9c5ccc0e9f19",
"card_network": "VISA",
"card_type": "CREDIT",
"currency": "GBP",
"display_name": "Club Credit Card",
"partial_card_number": "0044",
"name_on_card": "A. N. Other",
"valid_from": "2017-01",
"valid_to": "2018-01",
"update_timestamp": "2017-02-07T17:29:24.740802Z",
"provider": {
"provider_id": "lloyds"
}
},
{
"account_id": "ad86fb1c213245b6b6594895068973efca5f9367",
"card_network": "MASTERCARD",
"card_type": "CHARGE",
"currency": "GBP",
"display_name": "Club Charge Card",
"partial_card_number": "0055",
"name_on_card": "A. N. Other",
"valid_from": "2017-01",
"valid_to": "2018-01",
"update_timestamp": "2017-02-07T17:29:24.740802Z",
"provider": {
"provider_id": "lloyds"
}
}
]
}
/cards response fields
/cards response fields| Field | Type | Description | Required |
|---|---|---|---|
account_id | string | Unique identifier of the account. | ✅ |
card_network | string | Processing network (for example, VISA). | ✅ |
card_type | string | Type of card (for example, Credit). | ✅ |
currency | string | ISO 4217 alpha-3 currency code of the account. | ✅ |
display_name | string | Human-readable name of the account. | ✅ |
partial_card_number | string | Last 4 digits of the card. | ✅ |
name_on_card | string | If available, the name on the card. | |
valid_from | string | If available, the valid from date. | |
valid_to | string | If available, the valid to date. | |
update_timestamp | datetime | Last updated time of the card information | ✅ |
provider.display_name | string | Display name for the provider. | Deprecated |
provider.logo_uri | string | URI for the provider logo. | Deprecated |
provider.provider_id | string | Unique identifier for the provider. | ✅ |
Note that the provider attributes display_name and logo_uri are deprecated. Details about the providers are available through the separate /providers endpoint.
Supported card networks
The card_network field can currently return the following results and supported networks.
| Type | Description |
|---|---|
AMEX | Processing network is American Express. |
MASTERCARD | Processing network is Mastercard. |
VISA | Processing network is VISA. |
NOT_SUPPORTED_BY_GEO | Processing network is not supported in the geographical location. |
NOT_SUPPORTED_BY_PROVIDER | Processing network is not supported by the provider. |
Get data for a specific card
You can make a GET request to /cards/${account_id} to get data for a specific card.
You need to enable the cards scope in Console to make this request.
/card/{account_id} request
/card/{account_id} requestcurl -H "Authorization: Bearer ${access_token}" \
https://api.truelayer.com/data/v1/cards/${account_id}
/card/{account_id} response example
/card/{account_id} response example{
"results": [
{
"account_id": "f7b093437032c216d4350b7d442b9c5ccc0e9f19",
"card_network": "VISA",
"card_type": "CREDIT",
"currency": "GBP",
"display_name": "Club Credit Card",
"partial_card_number": "0044",
"name_on_card": "A. N. Other",
"valid_from": "2017-01",
"valid_to": "2018-01",
"update_timestamp": "2017-02-07T17:29:24.740802Z",
"provider": {
"provider_id": "lloyds"
}
}
]
}
/card/{account_id}response fields
/card/{account_id}response fields| Field | Type | Description | Required |
|---|---|---|---|
account_id | string | Unique identifier of the account. | ✅ |
card_network | string | Processing network (for example, VISA). | ✅ |
card_type | string | Type of card (for example, Credit). | ✅ |
currency | string | ISO 4217 alpha-3 currency code of the account. | ✅ |
display_name | string | Human-readable name of the account | ✅ |
partial_card_number | string | Last 4 digits of the card. | ✅ |
name_on_card | string | If available, the name on the card. | |
valid_from | string | If available, the valid from date. | |
valid_to | string | If available, the valid to date. | |
update_timestamp | datetime | Last update time of the card information. | |
provider.display_name | string | Display name for the provider. | Deprecated |
provider.logo_uri | string | URI for the provider logo. | Deprecated |
provider.provider_id | string | Unique identifier for the provider. | ✅ |
Note that the provider attributes display_name and logo_uri are deprecated. Details about providers are available through the separate /providers endpoint.
Get the balance on a card
Make a GET request to /cards/${account_id}/balance to get the balance on a user's card.
You need to enable the cards and balance scopes in Console to make this request.
/cards/{account_id}/balance request
/cards/{account_id}/balance requestcurl -H "Authorization: Bearer ${access_token}" \
https://api.truelayer.com/data/v1/cards/${account_id}/balance
/cards/{account_id}/balance response example
/cards/{account_id}/balance response example{
"results": [
{
"available": 3279.0,
"currency": "GBP",
"current": 20.0,
"credit_limit": 3300,
"last_statement_balance": 226,
"last_statement_date": "2017-01-28",
"payment_due": 5.0,
"payment_due_date": "2017-02-24",
"update_timestamp": "2017-02-247T17:29:24.740802Z"
}
]
}
/cards/{account_id}/balance response fields
/cards/{account_id}/balance response fields| Field | Type | Description | Required |
|---|---|---|---|
available | number | The amount available to the card holder. This takes into account any pending transactions and credit limit. | |
currency | string | ISO 4217 alpha-3 currency code. | ✅ |
current | number | The amount of expenditure on the card. This does not include any pending transactions. | ✅ |
credit_limit | number | Card credit limit. | |
last_statement_balance | number | Card balance at time of last statement, if available. | |
last_statement_date | string | Date of last statement, if available. | |
payment_due | number | Minimum amount required by due date. | |
payment_due_date | number | Date by which payment due should be remitted. | |
update_timestamp | datetime | Last update time | ✅ |
You can optionally get an available amount in the response which takes any pending transactions into account.
A negative available amount means the card’s credit limit has been exceeded. A positive available amount represents the credit available to the cardholder.
Get transaction data for a card
To get transaction data from a user's card, make a GET request to /cards/${account_id}/transactions .
You can include the optional from and to parameters to retrieve transaction data from a specified period of time.
Ensure to use the
fromandtoparameters together. Using just one of them changes the time period to a default value of 88 days.
You need to enable the cards and transactions scopes in Console to make this request.
/cards/{account_id}/transactions request
/cards/{account_id}/transactions requestcurl -H "Authorization: Bearer ${access_token}" \
"https://api.truelayer.com/data/v1/cards/${account_id}/transactions?from=${from}&to=${to}"
/cards/{account_id}/transactions response example
/cards/{account_id}/transactions response example{
"results": [
{
"transaction_id": "a15d8156569ba848d84c07c34d291bca",
"timestamp": "2018-01-16T00:00:00+00:00",
"amount": 24.25,
"currency": "GBP",
"description": "SAINSBURYS SMRKT STORE 128",
"transaction_type": "DEBIT",
"transaction_category": "PURCHASE",
"running_balance": {
"amount": 1238.60,
"currency": "GBP"
},
"meta": {
"cardNumber": "1234********5678",
"location": "INTERNET"
}
},
{
"transaction_id": "af4d5470cc7ad6a83a02335ab8053481",
"timestamp": "2018-03-19T00:00:00",
"amount": 46.82,
"currency": "GBP",
"description": "TALKTALK TELECOM",
"transaction_type": "DEBIT",
"transaction_category": "PURCHASE",
"meta":{
"provider_transaction_category": "DEB",
"cardNumber": "1234********5678",
"location": "INTERNET"
}
}
]
}
/cards/{account_id}/transactions response fields
/cards/{account_id}/transactions response fields| Parameter | Type | Description |
|---|---|---|
transaction_id | string | Unique identifier of the transaction in a request. It may change between requests. |
timestamp | datetime | Date the transaction was posted on the account. |
description | string | Original description of the transaction as reported by the provider. |
transaction_type | string | Type of the transaction. Possible values are: - CREDIT: Indicates an incoming fund. - DEBIT: Indicates an outgoing fund. |
transaction_category | string | Category of the transaction. |
transaction_classification | array | Classification of the transaction. Array can be empty if classification has not been successfully assigned. |
amount | number | Amount of the transaction. A positive transaction amount reflects the flow of funds out of a card, such as a purchase. A negative amount indicates the flow of funds into the card, for example a refund. |
currency | string | ISO 4217 alpha-3 currency code. |
meta | object | A collection of additional provider-specific transaction metadata. The format of this data contained in meta changes based on provider.For example, when returning transactions for an American Express card, meta also contains a supplementary_card_id. This is an American Express-unique concept, where a second card can be a child of a main card, and all transactions for it are returned. |
You can optionally get a running_balance.amount in the response which displays any available running balance.
A positive running balance amount represents money owed to the provider by the cardholder. A negative running balance amount represents money owed to the cardholder by the provider.
For the complete list of optional and mandatory response parameters, see our API reference.
Pending transactions
It isn't possible to return a list of pending transactions for a specific time range, the API returns all pending transactions. Although most transactions clear within 7 days, transactions can be pending for up to 120 days.
Updated 4 months ago