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. To access the API, you must authenticate via Bearer Authentication (e.g. for a cross-origin request). When you make any API request, pass an Authorization header in the following format: 
"Authorization: Bearer <api key>”.
All API requests must be made over HTTPS; calls made over plain HTTP will fail. API requests without authentication will also fail.

​
Enrichment Request

You can enrich a payments event with additional data on POST: The enrichment request includes the following fields:
PropertyVariable TypeDescriptionExample
transaction_idstringThe unique transaction identifier as provided by your PSP; max 255 characters”SQK3T3B6SRZSRYV5”
order_idstringThe order reference identifier you generated (see note below); max 255 characters”5671790218”
metadataobjectA transaction-level label used to segment transactions into meaningful groupsSee 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 CodeDescription
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"
}