Data Contract

Sentra's data contract is sentra.ingest.v0. It defines the file formats used for data import, model training, quality checks, and AI enrichment.

Upload package

Recommended folder:

partner_batch_001/
  manifest.json
  transactions.csv
  entities.csv
  labels.csv
  kyc_docs.jsonl

Minimum first batch:

transactions.csv

Recommended first training batch:

transactions.csv
entities.csv
labels.csv

Optional enrichment batch:

kyc_docs.jsonl

manifest.json

{
  "schema_version": "sentra.ingest.v0",
  "dataset_name": "partner_batch_20260315",
  "files": [
    {
      "name": "transactions.csv",
      "type": "transactions",
      "s3_key": "partner_batch_20260315/transactions.csv",
      "sha256": "replace-with-file-sha256-if-available",
      "row_count": 1000
    }
  ]
}

transactions.csv

Required columns:

Column	Description
`tx_id`	Unique transaction ID.
`created_at`	ISO-8601 timestamp.
`amount`	Numeric payment amount.
`currency`	Canonical currency.
`direction`	`pay_in` or `pay_out` preferred.
`channel`	Payment channel.
`psp`	Payment service provider.
`route_id`	Route/corridor identifier.
`status`	Transaction status.
`status_reason`	Status reason.
`fee_total`	Total fee amount.
`sender_entity_id`	Sender entity.
`receiver_entity_id`	Receiver entity.
`sender_country`	Sender country.
`receiver_country`	Receiver country.

Important optional fields:

fx_rate
ip_hash
device_id_hash
response_code
response_time_ms
duplicate_order_count
is_http_error
is_slow_response
is_extreme_amount
merchant_hour_request_count
merchant_hour_error_rate
hashed request, merchant, order, user, email, phone, account, and document identifiers

Do not export raw PII. Hash or categorize raw fields before sending them to Sentra.

Canonical values

Field	Values
`direction`	`pay_in`, `pay`, `pay_out`, `payout`
`channel`	`card`, `bank_transfer`, `wallet`, `crypto_offramp`, `spei`, `net_banking`, `nequi`, `pix`, `oxxo_pay`, `cash`
`status`	`completed`, `success`, `approved`, `pending`, `failed`, `error`, `refunded`
`psp`	`stripe`, `adyen`, `checkout`, `airwallex`, `todaypay`, `vamospago`, `partner`

Unknown values can ingest, but they degrade feature quality until mapped.

labels.csv

Required columns:

tx_id
label_type
label_value
source

Optional:

note
labeled_at

Accepted sources:

manual
system
partner

Label training semantics:

Label type	Training target
`fraud=1`	Positive fraud target.
`chargeback=1`	Positive fraud target.
`blocked=1`	Positive fraud target.
`fraud=0`, `chargeback=0`, `blocked=0`	Negative fraud target.
`false_positive=1`	Negative fraud target.
`refund`, `other`	Stored for history, ignored for fraud target.

Unsupported label types, unsupported sources, or non-binary label values fail ingest.

entities.csv

Required columns:

entity_id
entity_type
country

Optional:

kyc_level
onboarded_at

Recommended entity_type values:

user
merchant
agent
psp

kyc_docs.jsonl

Each line is one JSON object:

{"entity_id":"merchant_987","doc_hash":"dochash_partner_001","doc_s3_url":"s3://sentra-kyc-docs/demo/merchant_987_certificate.pdf","text_blob":"Certificate of incorporation..."}

Use text_blob only when approved by your retention and masking policy.

Mapping workflow

Download starter templates from Admin Data Contract.
Fill payment_field_mapping_template.csv.
Normalize timestamps, countries, currency, PSP, channel, direction, and status.
Hash sensitive identifiers.
Validate locally before upload.

On this page