Enrichment API Overview

The Enrichment API allows you to add enhanced transaction metadata to all your payment events (e.g. transactions, refunds, disputes), regardless of which data connection or payment service provider (PSP) we ingest your data from. This additional metadata is always linked to a payments event using the original transaction reference from the connected data source. This ensures updates and data points are linked accurately.

Sensitive Data Warning:Never pass sensitive customer data to Pagos via the Enrichment API.

Use Cases

The primary use case for enriching your payment events with metadata is the custom data segmentation and transaction categorization it facilitates. In other words, the more information you tag transactions with, the more parameters you have to filter your transaction data by. For example, you may want to track transaction volume or segment sales traffic based on a product line, customer acquisition channel, or customer cohort. Behaviorally, the best use for metadata is retries; you can categorize your transactions by a First Attempt, Retry, Second Retry, etc. Then, you can track transaction approval performance or even customer churn via the number of transaction attempts. Enhanced metadata is also valuable for capturing pre-checkout transaction properties. The ability to capture data before a transaction is even finalized opens avenues for analyzing customer behavior during checkout, understanding drop-off points, and improving the overall user experience. Information such as Device ID and IP address can also help in fraud detection, geolocation targeting, and device-specific optimizations.

Authentication

The Pagos platform uses API keys to authenticate requests to all our services. See our API Authentication guide for full instructions on generating API keys and authenticating with the Pagos APIs.

Enrichment Request

You can enrich a payments event with additional data on POST:

{account_id}/transactions/enrichment to enrich transactions from one of the data connections you import data into Pagos from
/transactions/enrichment to enrich transactions imported into Pagos from all your data connections

The enrichment request includes the following fields:

Property	Variable Type	Description	Example
`transaction_id`	string	The unique transaction identifier as provided by your PSP; max 255 characters	”SQK3T3B6SRZSRYV5”
`order_id`	string	The order reference identifier you generated (see note below); max 255 characters	”5671790218”
`metadata`	object	A transaction-level label used to segment transactions into meaningful groups	See Metadata section below

Transaction ID vs. Order ID

You can identify a transaction in your enrichment request using either of the following:

transaction_id - The transaction reference your PSP provided to you when processing the transaction. This is the most accurate way to identify a transaction for enrichment, as Pagos also uses this as the key reference for an order. In this case please note the appropriate field to specify this value so that we can find the correct record for a metadata update.
order_id - The transaction identifier generated in your own system. Keep in mind, if multiple transactions are identified with the order_id, all matching transactions will be enriched.

We provide these methods in order to make it as easy as possible to link additional data and labels to a transaction. Every enrichment request must include at least one.

Enrichment Window Limitations

The enrichment process operates asynchronously, allowing you to submit enrichment data even before a transaction has finished processing. To support this feature, we impose a restriction on the enrichment window.

Enrichment Duration: Once an enrichment record is submitted, the system will attempt to enrich any linked transactions for up to 7 days. Which means any future transactions also will be eligible for enrichment for the next 7 days.
Transaction Eligibility: Only transactions created within the last 45 days are eligible for enrichment. This window can be extended upon request.

Metadata Requirements

To enrich your events with additional metadata, your enrichment request should include a metadata object. This object allows you to add any valid key-value pair or JSON object to provide extra information about the event. The metadata object is a flexible structure that can contain any valid key-value pairs. This can include additional information such as retry attempts, custom keys, and other relevant data.

{
	...
	...
  metadata: {
    "key": "value",
    "retryAttempt": 1,
    "anotherCustomKey": "customValue"
  }
}

Example Request

Request body example:

{
  "transaction_id": "SQK3T3B6SRZSRYV5",
  "order_id": "5671790218",
  "metadata": {
    "subscription_id": "s_9kBsm9XudQKhIKpJmNaG2J3zeCwshgtk",
    "retryAttempt": 5,
    "purchase_flow": "Recurring",
    "isLastRetry": true
  }
}

CURL example:

curl --request POST \
  --url https://api.sandbox.nest.pagosapi.com/v1/transactions/enrichment \
  --header 'Authorization: Bearer XXX_YYY_ZZZ' \
  --header 'Content-Type: application/json' \
  --data '{
  "transaction_id": "SQK3T3B6GSRZZCV5",
  "metadata": {
    "subscription_id": "s_9kBsm9XudQKhIKpJmNaG2J3zeCwshgtk"
  }
}'

Enrichment Response

HTTP Response Code	Description
201 (created)	Enrichment record processed and saved in enrichment queue successfully
400 (bad request)	No transaction identifier provided; please populate `order_id` and/or `transaction_id`
401 (unauthorized)	Authorization failed. Possible reasons include invalid API key or API key from another environment

{
  "statusCode": 400,
  "message": "Validation error: Identifier should we populated with at least one strategy: transaction_id or order_id"
}

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Authentication

Data & Response Codes

Data Ingestion

BIN Database

Account Updater

Network Tokenization

Enrichment API Overview

Use Cases

Authentication

Enrichment Request

Transaction ID vs. Order ID

Enrichment Window Limitations

Metadata Requirements

Example Request

Enrichment Response

​Use Cases

​Authentication

​Enrichment Request

​Transaction ID vs. Order ID

​Enrichment Window Limitations

​Metadata Requirements

​Example Request

​Enrichment Response

Use Cases

Authentication

Enrichment Request

Transaction ID vs. Order ID

Enrichment Window Limitations

Metadata Requirements

Example Request

Enrichment Response