API ReferenceChangelog
API Reference

Transaction feedback guide

This short guide introduces you to Spade's enrichment feedback endpoints, where you can submit data which helps us to continuously improve our transaction enrichment service.

What are the enrichment feedback endpoints?

There are four enrichment feedback endpoints, each designed for you to send specific types of information related to transactions which you have enriched using Spade's API.

  • enrichments/<enrichmentId>/chargeback for providing information on a chargeback which occurred on a transaction
  • enrichments/<enrichmentId>/decline for providing information on a card decline which occurred on a transaction
  • enrichments/<enrichmentId>/refund for providing information on a card refund which occurred on a transaction
  • enrichments/<enrichmentId/fraud for providing information on fraud which occurred on a transaction, but which was not otherwise related to a chargeback, decline, or refund

You can send requests to these endpoints using the enrichmentId you received when enriching a transaction using the transactions/enrich endpoint. You can find a detailed specification of each endpoint at this link. Internally, we collect the feedback you provide and use it derive insights on the merchants and locations we return during enrichments, leveraging these insights to enhance our core enrichment API.

How do I integrate with the feedback endpoints?

Integrating with the feedback endpoints is simple. We'll run through an example using the enrichments/<enrichmentId>/chargeback endpoint.
If you haven't already integrated with Spade's enrichment API, read our Getting Started Guide to learn how to set up enrichments.

It's important that you keep track of the enrichmentId as this query parameter must be passed to the feedback endpoints. Using an enrichmentId from a previously renriched transaction, we can send a request to the chargeback endpoint.

enrichment_id = "<Your enrichmentId Here>"

chargeback_data = {
  "state": "chargeback_lost",
  "chargebackNotes": "merchant reported the chargeback as fraud",
  "occurredAt": "2023-03-17T12:35:00Z",
  "isFraud": True,
  "fraudType": "chargeback_fraud"
}

response = requests.post(
    f"https://east.sandbox.spade.com/enrichments/{enrichment_id}/chargeback",
    json=chargeback_data,
    headers={"X-Api-Key": "<Your API Key Here>"}
)

print(response.json())

If the request was successful, you'll receive a 200 response indicating the chargeback was received. You can follow an almost identical process to send requests to the endpoints for card declines, card refunds, and fraud events. Thanks for helping Spade in our journey to provide best in class transaction enrichment!