Enrich a universal transaction
curl --request POST \
--url https://east.sandbox.spade.com/transactions/universal/enrich \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"userId": "user_id_123456789",
"description": "AMAZON CORP SYF PAYMNT",
"amount": "283.78",
"currencyCode": "USD",
"occurredAt": "2022-06-15 18:27:51Z",
"organizationId": "organization_id_123",
"accountId": "account_id_123456789",
"transactionId": "transaction_id_123456789",
"direction": "CREDIT",
"billingProfile": "standard",
"customAttributes": {
"custom_attribute_1": "value_1",
"custom_attribute_2": "value_2"
}
}
'import requests
url = "https://east.sandbox.spade.com/transactions/universal/enrich"
payload = {
"userId": "user_id_123456789",
"description": "AMAZON CORP SYF PAYMNT",
"amount": "283.78",
"currencyCode": "USD",
"occurredAt": "2022-06-15 18:27:51Z",
"organizationId": "organization_id_123",
"accountId": "account_id_123456789",
"transactionId": "transaction_id_123456789",
"direction": "CREDIT",
"billingProfile": "standard",
"customAttributes": {
"custom_attribute_1": "value_1",
"custom_attribute_2": "value_2"
}
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
userId: 'user_id_123456789',
description: 'AMAZON CORP SYF PAYMNT',
amount: '283.78',
currencyCode: 'USD',
occurredAt: '2022-06-15 18:27:51Z',
organizationId: 'organization_id_123',
accountId: 'account_id_123456789',
transactionId: 'transaction_id_123456789',
direction: 'CREDIT',
billingProfile: 'standard',
customAttributes: {custom_attribute_1: 'value_1', custom_attribute_2: 'value_2'}
})
};
fetch('https://east.sandbox.spade.com/transactions/universal/enrich', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://east.sandbox.spade.com/transactions/universal/enrich",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'userId' => 'user_id_123456789',
'description' => 'AMAZON CORP SYF PAYMNT',
'amount' => '283.78',
'currencyCode' => 'USD',
'occurredAt' => '2022-06-15 18:27:51Z',
'organizationId' => 'organization_id_123',
'accountId' => 'account_id_123456789',
'transactionId' => 'transaction_id_123456789',
'direction' => 'CREDIT',
'billingProfile' => 'standard',
'customAttributes' => [
'custom_attribute_1' => 'value_1',
'custom_attribute_2' => 'value_2'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://east.sandbox.spade.com/transactions/universal/enrich"
payload := strings.NewReader("{\n \"userId\": \"user_id_123456789\",\n \"description\": \"AMAZON CORP SYF PAYMNT\",\n \"amount\": \"283.78\",\n \"currencyCode\": \"USD\",\n \"occurredAt\": \"2022-06-15 18:27:51Z\",\n \"organizationId\": \"organization_id_123\",\n \"accountId\": \"account_id_123456789\",\n \"transactionId\": \"transaction_id_123456789\",\n \"direction\": \"CREDIT\",\n \"billingProfile\": \"standard\",\n \"customAttributes\": {\n \"custom_attribute_1\": \"value_1\",\n \"custom_attribute_2\": \"value_2\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://east.sandbox.spade.com/transactions/universal/enrich")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"userId\": \"user_id_123456789\",\n \"description\": \"AMAZON CORP SYF PAYMNT\",\n \"amount\": \"283.78\",\n \"currencyCode\": \"USD\",\n \"occurredAt\": \"2022-06-15 18:27:51Z\",\n \"organizationId\": \"organization_id_123\",\n \"accountId\": \"account_id_123456789\",\n \"transactionId\": \"transaction_id_123456789\",\n \"direction\": \"CREDIT\",\n \"billingProfile\": \"standard\",\n \"customAttributes\": {\n \"custom_attribute_1\": \"value_1\",\n \"custom_attribute_2\": \"value_2\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://east.sandbox.spade.com/transactions/universal/enrich")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"userId\": \"user_id_123456789\",\n \"description\": \"AMAZON CORP SYF PAYMNT\",\n \"amount\": \"283.78\",\n \"currencyCode\": \"USD\",\n \"occurredAt\": \"2022-06-15 18:27:51Z\",\n \"organizationId\": \"organization_id_123\",\n \"accountId\": \"account_id_123456789\",\n \"transactionId\": \"transaction_id_123456789\",\n \"direction\": \"CREDIT\",\n \"billingProfile\": \"standard\",\n \"customAttributes\": {\n \"custom_attribute_1\": \"value_1\",\n \"custom_attribute_2\": \"value_2\"\n }\n}"
response = http.request(request)
puts response.read_body{
"transactionInfo": {
"type": "spending",
"subType": null,
"spendingInfo": null,
"thirdParties": [
{
"id": "ac48cef2-0d7f-4159-865e-e92b152262bc",
"name": "Paypal",
"type": "payment_processor",
"logo": "https://static.v2.spadeapi.com/logos/9063bc0f0a3f4b1fbf644f9862e17002/light.png",
"website": "https://www.paypal.com/"
}
],
"recurrenceInfo": null,
"display": {
"name": "Amazon",
"categoryName": "Online Marketplace",
"graphic": "https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png",
"graphicSource": "counterparty"
},
"transferInfo": {
"direction": "outgoing",
"transferMethod": "ach",
"transferType": "external",
"isAdjustmentOrRefund": false
},
"atmInfo": null,
"isAccountVerification": false,
"isPeerToPeer": false,
"isDigitalWallet": false,
"transactionId": "transaction_id_123456789",
"riskInsights": {
"irregularWebPresenceDetected": false,
"negativeOnlineSentiment": false,
"highRiskEntity": false,
"riskyIndustry": false,
"cardAcceptanceHistory": "extensive"
}
},
"counterparty": [
{
"location": [
{
"id": "fdf79470-3deb-4638-956a-6859e473b9d8",
"address": "1234 W 5th Ave Suite 100",
"addressLine1": "1234 W 5th Ave",
"addressLine2": "Suite 100",
"city": "New York",
"region": "NY",
"country": "USA",
"postalCode": "10001",
"latitude": 45,
"longitude": 120,
"phoneNumber": "+18664862360",
"matchScore": 93.5
}
],
"possibleCounterpartyAlternate": null,
"id": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
"name": "Amazon",
"legalName": "Amazon Inc.",
"industry": [
{
"id": "011-000-000-000",
"name": "Retail",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
}
],
"matchScore": 93.5,
"logo": "https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png",
"phoneNumber": "+18664862360",
"website": "https://www.amazon.com"
}
],
"enrichmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"mobileAppInfo": {
"id": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
"name": "Roblox",
"url": "https://play.google.com/store/apps/details?id=com.roblox.client",
"logo": "https://static.v2.spadeapi.com/logos/58c03a73629c46b8aa4c1e15cb4f0d0b/light.png",
"developerName": "Roblox Corporation",
"developerId": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
"category": "Auto and Transportation",
"hasGamblingOrRewards": false,
"hasSimulatedGambling": false,
"ageRating": "Teen"
},
"customAttributes": {
"custom_attribute_1": "value_1",
"custom_attribute_2": "value_2"
},
"actions": [
{
"id": "trigger-12345",
"type": "merchant_trigger",
"action": {
"type": "REWARD",
"rewardPercent": 5
},
"scope": "account",
"source": "counterparty"
}
]
}{
"invalidField": [
"This field is required."
]
}{
"details": "Incorrect authentication credentials."
}{
"details": "Internal server error."
}Universal Enrichment
Enrich a universal transaction
Enrich any type of transaction such as an aggregator transaction, card transaction, ACH withdrawal, ACH deposit, or wire transfer.
Note that universal enrichment is currently in beta, please reach out to sales@spade.com to request access.
POST
/
transactions
/
universal
/
enrich
Enrich a universal transaction
curl --request POST \
--url https://east.sandbox.spade.com/transactions/universal/enrich \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"userId": "user_id_123456789",
"description": "AMAZON CORP SYF PAYMNT",
"amount": "283.78",
"currencyCode": "USD",
"occurredAt": "2022-06-15 18:27:51Z",
"organizationId": "organization_id_123",
"accountId": "account_id_123456789",
"transactionId": "transaction_id_123456789",
"direction": "CREDIT",
"billingProfile": "standard",
"customAttributes": {
"custom_attribute_1": "value_1",
"custom_attribute_2": "value_2"
}
}
'import requests
url = "https://east.sandbox.spade.com/transactions/universal/enrich"
payload = {
"userId": "user_id_123456789",
"description": "AMAZON CORP SYF PAYMNT",
"amount": "283.78",
"currencyCode": "USD",
"occurredAt": "2022-06-15 18:27:51Z",
"organizationId": "organization_id_123",
"accountId": "account_id_123456789",
"transactionId": "transaction_id_123456789",
"direction": "CREDIT",
"billingProfile": "standard",
"customAttributes": {
"custom_attribute_1": "value_1",
"custom_attribute_2": "value_2"
}
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
userId: 'user_id_123456789',
description: 'AMAZON CORP SYF PAYMNT',
amount: '283.78',
currencyCode: 'USD',
occurredAt: '2022-06-15 18:27:51Z',
organizationId: 'organization_id_123',
accountId: 'account_id_123456789',
transactionId: 'transaction_id_123456789',
direction: 'CREDIT',
billingProfile: 'standard',
customAttributes: {custom_attribute_1: 'value_1', custom_attribute_2: 'value_2'}
})
};
fetch('https://east.sandbox.spade.com/transactions/universal/enrich', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://east.sandbox.spade.com/transactions/universal/enrich",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'userId' => 'user_id_123456789',
'description' => 'AMAZON CORP SYF PAYMNT',
'amount' => '283.78',
'currencyCode' => 'USD',
'occurredAt' => '2022-06-15 18:27:51Z',
'organizationId' => 'organization_id_123',
'accountId' => 'account_id_123456789',
'transactionId' => 'transaction_id_123456789',
'direction' => 'CREDIT',
'billingProfile' => 'standard',
'customAttributes' => [
'custom_attribute_1' => 'value_1',
'custom_attribute_2' => 'value_2'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://east.sandbox.spade.com/transactions/universal/enrich"
payload := strings.NewReader("{\n \"userId\": \"user_id_123456789\",\n \"description\": \"AMAZON CORP SYF PAYMNT\",\n \"amount\": \"283.78\",\n \"currencyCode\": \"USD\",\n \"occurredAt\": \"2022-06-15 18:27:51Z\",\n \"organizationId\": \"organization_id_123\",\n \"accountId\": \"account_id_123456789\",\n \"transactionId\": \"transaction_id_123456789\",\n \"direction\": \"CREDIT\",\n \"billingProfile\": \"standard\",\n \"customAttributes\": {\n \"custom_attribute_1\": \"value_1\",\n \"custom_attribute_2\": \"value_2\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://east.sandbox.spade.com/transactions/universal/enrich")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"userId\": \"user_id_123456789\",\n \"description\": \"AMAZON CORP SYF PAYMNT\",\n \"amount\": \"283.78\",\n \"currencyCode\": \"USD\",\n \"occurredAt\": \"2022-06-15 18:27:51Z\",\n \"organizationId\": \"organization_id_123\",\n \"accountId\": \"account_id_123456789\",\n \"transactionId\": \"transaction_id_123456789\",\n \"direction\": \"CREDIT\",\n \"billingProfile\": \"standard\",\n \"customAttributes\": {\n \"custom_attribute_1\": \"value_1\",\n \"custom_attribute_2\": \"value_2\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://east.sandbox.spade.com/transactions/universal/enrich")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"userId\": \"user_id_123456789\",\n \"description\": \"AMAZON CORP SYF PAYMNT\",\n \"amount\": \"283.78\",\n \"currencyCode\": \"USD\",\n \"occurredAt\": \"2022-06-15 18:27:51Z\",\n \"organizationId\": \"organization_id_123\",\n \"accountId\": \"account_id_123456789\",\n \"transactionId\": \"transaction_id_123456789\",\n \"direction\": \"CREDIT\",\n \"billingProfile\": \"standard\",\n \"customAttributes\": {\n \"custom_attribute_1\": \"value_1\",\n \"custom_attribute_2\": \"value_2\"\n }\n}"
response = http.request(request)
puts response.read_body{
"transactionInfo": {
"type": "spending",
"subType": null,
"spendingInfo": null,
"thirdParties": [
{
"id": "ac48cef2-0d7f-4159-865e-e92b152262bc",
"name": "Paypal",
"type": "payment_processor",
"logo": "https://static.v2.spadeapi.com/logos/9063bc0f0a3f4b1fbf644f9862e17002/light.png",
"website": "https://www.paypal.com/"
}
],
"recurrenceInfo": null,
"display": {
"name": "Amazon",
"categoryName": "Online Marketplace",
"graphic": "https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png",
"graphicSource": "counterparty"
},
"transferInfo": {
"direction": "outgoing",
"transferMethod": "ach",
"transferType": "external",
"isAdjustmentOrRefund": false
},
"atmInfo": null,
"isAccountVerification": false,
"isPeerToPeer": false,
"isDigitalWallet": false,
"transactionId": "transaction_id_123456789",
"riskInsights": {
"irregularWebPresenceDetected": false,
"negativeOnlineSentiment": false,
"highRiskEntity": false,
"riskyIndustry": false,
"cardAcceptanceHistory": "extensive"
}
},
"counterparty": [
{
"location": [
{
"id": "fdf79470-3deb-4638-956a-6859e473b9d8",
"address": "1234 W 5th Ave Suite 100",
"addressLine1": "1234 W 5th Ave",
"addressLine2": "Suite 100",
"city": "New York",
"region": "NY",
"country": "USA",
"postalCode": "10001",
"latitude": 45,
"longitude": 120,
"phoneNumber": "+18664862360",
"matchScore": 93.5
}
],
"possibleCounterpartyAlternate": null,
"id": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
"name": "Amazon",
"legalName": "Amazon Inc.",
"industry": [
{
"id": "011-000-000-000",
"name": "Retail",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
}
],
"matchScore": 93.5,
"logo": "https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png",
"phoneNumber": "+18664862360",
"website": "https://www.amazon.com"
}
],
"enrichmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"mobileAppInfo": {
"id": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
"name": "Roblox",
"url": "https://play.google.com/store/apps/details?id=com.roblox.client",
"logo": "https://static.v2.spadeapi.com/logos/58c03a73629c46b8aa4c1e15cb4f0d0b/light.png",
"developerName": "Roblox Corporation",
"developerId": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
"category": "Auto and Transportation",
"hasGamblingOrRewards": false,
"hasSimulatedGambling": false,
"ageRating": "Teen"
},
"customAttributes": {
"custom_attribute_1": "value_1",
"custom_attribute_2": "value_2"
},
"actions": [
{
"id": "trigger-12345",
"type": "merchant_trigger",
"action": {
"type": "REWARD",
"rewardPercent": 5
},
"scope": "account",
"source": "counterparty"
}
]
}{
"invalidField": [
"This field is required."
]
}{
"details": "Incorrect authentication credentials."
}{
"details": "Internal server error."
}Authorizations
Body
application/json
Anonymous ID representing your user. This will be used for summary features, recurrence flagging, and category personalization purposes.
Maximum string length:
512Example:
"user_id_123456789"
The full transaction description. Typically, this will be a string containing the name of the merchant or institution involved in the transaction plus information related to the type of transaction such as "ACCT VERIFY", "WEB PMT", "ETRANSFER", etc...
Maximum string length:
1024Example:
"AMAZON CORP SYF PAYMNT"
Value of the transaction in the given currency. Negative values indicate incoming money.
Example:
"283.78"
Maximum string length:
16Example:
"USD"
The time the transaction occurred. Formatted as an ISO 8601 date time.
Example:
"2022-06-15 18:27:51Z"
An ID representing the organization associated with this transaction. Use this field if you are enriching transactions on behalf of other organizations. Used for billing purposes and for scoping products such as action triggers and category personalizations at the organization-level. For more information, see Supporting multiple data sources and clients
Maximum string length:
256Example:
"organization_id_123"
Anonymous ID representing the account of the user (NOT the account number).
Maximum string length:
512Example:
"account_id_123456789"
Your ID representing this transaction
Maximum string length:
512Example:
"transaction_id_123456789"
The direction of the transaction. Will take precedence over the direction inferred from the amount field.
Available options:
CREDIT, DEBIT Maximum string length:
8Examples:
"CREDIT"
"DEBIT"
An optional billing profile for this transaction. When set to "resell", the organizationId field is required. For more information, see Supporting multiple data sources and clients
Available options:
standard, resell Example:
"standard"
A dictionary containing custom attributes that you would like to be returned in the response.
Please ensure this object does not contain any PII.
Restrictions include: customAttributes must be an object, up 30 custom attributes are allowed, each key must be a string <= 40 characters in length, and each value must be a string <= 250 characters in length.
Show child attributes
Show child attributes
Example:
{
"custom_attribute_1": "value_1",
"custom_attribute_2": "value_2"
}
Response
Successful operation
Show child attributes
Show child attributes
An array of counterparties matched to the transaction, ordered by descending match score.
Show child attributes
Show child attributes
Our ID representing the enrichment, not to be confused with your provided transactionId.
The mobile app information for the transaction. This object is only non-null if the transaction was matched to a mobile app.
Show child attributes
Show child attributes
A dictionary containing the custom attributes that were included in the enrichment request (if any).
Show child attributes
Show child attributes
Example:
{
"custom_attribute_1": "value_1",
"custom_attribute_2": "value_2"
}
An array of triggered actions, or null if no triggers matched.
This field is only present if your integration has the actions feature enabled.
When a transaction matches one or more registered triggers, this array contains the action details
including your custom action data. Multiple matches are possible when triggers are registered
at different scopes (account, program, user, card).
Show child attributes
Show child attributes
Example:
[
{
"id": "trigger-12345",
"type": "merchant_trigger",
"action": { "type": "REWARD", "rewardPercent": 5 },
"scope": "account",
"source": "counterparty"
}
]