跳到主要内容

Transaction

当持卡人发起交易时，数据应发送到我们的服务器，以便我们对该数据集所涉及的风险进行分析。

对象定义​

Request Body
{
  "id": "678",
  "cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
  "group_id" : "8507884b-c30f-4b45-951c-f0bf366926fc",
  "amount": 13725,
  "currency": "BRL",
  "brl_converted_amount": 13725,
  "installments": 6,
  "authorization_date": "2019-11-10T13:25:42.123-03:00",
  "authorization_type": "authorization",
  "transaction_type": "credit",
  "pan_entry_mode": "chip",
  "pin_sent": true,
  "source_account": "saving_account",
  "location": {
    "latitude": -45.2753548,
    "longitude": -15.24587
  },
  "terminal": {
    "id": "123456",
    "country_code": "BRA",
    "terminal_type": "2",
    "pin_entry_capability": true,
    "magnetic_stripe_capability": true,
    "contactless_capability": false,
    "chip_capability": true
  },
  "merchant": {
    "acquirer_id": "250",
    "merchant_id": "123456",
    "name": "VASP LINHAS AEREAS",
    "street" : "RUA CMDTE X, 127",
    "city" : "SAO PAULO, SP",
    "region": "BRA",
    "postal_code": "04570-140",
    "mcc": "3036"
  },
  "card": {
    "brand": "visa",
    "category": "black",
    "issuing_date": "2019-10-08T07:13:12.333-03:00",
    "unblock_date": "2019-10-12T07:13:12.333-03:00",
    "expiration_date": "2019-12-31",
    "bin": "498406",
    "last4": "1234",
    "total_credit_limit": 2500000,
    "used_credit_limit": 732625,
    "issuer_country_code": "BRA"
  },
  "transaction_status" : "authorized",
  "response_code": "05"
}

交易应在授权前发送到 API，可用于决定是否生成授权码。发送的数据还可用于根据持卡人的交易历史生成警报，以便在出现异常行为时触发适当的行动，从而降低交易影响。

欺诈状态（fraud_status 和 transaction_status）分别表示模型对该交易返回的决策，以及交易是否已完成、取消或成为争议。

transaction_status 使用以下状态：

  • not_authorized
  • authorized
  • cleared
  • cancelled
  • partially_cancelled
  • chargeback
  • partial_chargeback

fraud_status 使用以下状态：

  • automatically_approved
  • automatically_declined
  • not_analyzed

以下是 fraud_status 标志中返回的每个决策的含义：

结果描述
automatically_approved建议批准此交易
automatically_declined建议拒绝此交易
not_analyzed查询以分析标志为假发送，这意味着我们的系统不应返回意见
名称类型描述
idstring（必填）
客户系统中交易的标识符。
此编号对每个授权流程必须唯一
cardholder_idstring（必填）
客户系统中持卡人的标识符——如 Onboarding API 中注册的那样
group_idstring（可选）
客户系统中该用户所属组或类别的标识符
amount整数（必填）
交易金额——如"标准"部分所述
currencystring（必填）
交易使用的货币——ISO 4217 和 8583 的 ApplicationCurrencyCode
brl_converted_amount整数（必填）
转换为巴西雷亚尔的交易金额——如"标准"部分所述
installments整数（必填）
交易使用的分期数
authorization_datedatetime（必填）
交易开始的日期和时间，含时区
authorization_type枚举（必填）
授权交易还是预授权交易？
transaction_type枚举（必填）
信用、借记还是预付费
pan_entry_mode枚举（必填）
PAN 输入模式——芯片、手动输入、磁条、后备、非接触式——来自 ISO 8583 的字段（DE 22 - 子字段 1）
pin_sent布尔值（必填）
是否在终端输入了密码？——来自 ISO 8583 entry_mode 的字段
source_account枚举（可选）
交易金额应从账单、活期账户还是储蓄账户扣除——来自 ISO 8583 Processing Code 的字段
location.latitudenumber（可选）
交易发生地的纬度——如果有关联的手机或其他定位方式
location.longitudenumber（可选）
交易发生地的经度
terminal.idstring（可选）
收单机构在认证消息中发送的终端标识符
terminal.country_codestring（必填）
终端所在国家代码，按 ISO 3166-1 alpha-3 在授权消息中发送，来自 ISO 8583 的 Terminal Country Code 字段
terminal.terminal_typestring（必填）
从授权消息中接收到的终端类型——来自 ISO 8583 的 TerminalType 字段
terminal.pin_entry_capabilityboolean（必填）
终端是否支持输入卡密码？——来自 ISO 8583 的 TerminalPINEntryCapability 字段
terminal.magnetic_stripe_capabilityboolean（可选）
终端是否支持读取磁条？——ISO 8583 的 TerminalPANEntryCapability（DE 123）字段
terminal.contactless_capabilityboolean（可选）
终端是否支持非接触式交易？——ISO 8583 的 TerminalPANEntryCapability（DE 123）字段
terminal.chip_capabilityboolean（必填）
终端是否支持使用 EMV 芯片进行交易？——ISO 8583 的 TerminalPANEntryCapability（DE 123）字段
merchant.acquirer_idstring（必填）
授权消息中的收单机构标识符——ISO 8583 的 Acquirer Identifier（DE 32）字段
merchant.merchant_idstring（必填）
授权消息中收单机构的商户标识符——ISO 8583 的 Merchant Identifier 字段
merchant.namestring（可选）
授权消息中的商户名称——ISO 8583 的 Merchant Name 字段
merchant.streetstring（可选）
商户地址的街道——Card Acceptor Street Address 字段
merchant.citystring（可选）
商户地址的城市——Card Acceptor City 字段
merchant.regionstring（可选）
商户地址的城市——Card Acceptor Region Code 字段
merchant.postal_codestring（可选）
商户地址的城市——Card Acceptor Postal Code 字段
merchant.mccstring（必填）
商户类别码，符合 ISO 18245 和 ISO 8583
card.brand枚举（必填）
卡片品牌（visa、mastercard、elo……）
card.category枚举（必填）
卡片类别（classic、gold、platinum、black、infinite、corporate）
card.issuing_datedatetime（必填）
卡片发行的日期和时间，含时区
card.unblock_datedatetime（可选）
持卡人解锁卡片的日期和时间，含时区
card.expiration_datedate（必填）
卡片有效期（月末最后一天）
card.binstring（必填）
使用中的卡片 BIN
card.last4string（必填）
卡片后四位数字，用于在发行机构内识别卡片
card.total_credit_limitnumber（可选）
授予持卡人的总信用额度。若为预付卡，则为卡片上现有的信用金额
card.used_credit_limitnumber（可选）
已使用的额度金额（此交易之前）
card.issuer_country_codestring（必填）
发行机构所在国家，符合 ISO 3166-1 alpha-3
transaction_status枚举（可选）
交易状态，如果带有 analyze=false 标志发送且授权决策已做出。
response_code枚举（可选）
根据 ISO 8583 Response Code 字段的交易响应码，如果带有 analyze=false 标志发送且授权决策已做出。

枚举值​

卡片交易对象的枚举值包括 authorization_type、transaction_type、pan_entry_mode、source_account、brand 和 category。每个枚举值的可能值如下所示：

authorization_type​

枚举值含义
authorization购买授权——MTI x1xx（DMS）和 x2xx（SMS）
pre_authorization在卡片上预留额度的预授权（酒店、车辆租赁、设备租赁、加油机）——MTI x1xx（DMS）和 Transaction Type（Processing Code 前两位数字）"60"
reversal取消授权（以释放卡片额度并随后继续 Clearing/BASE II）——MTI x4xx

transaction_type​

枚举值含义
credit信用功能交易
debit借记功能交易
prepaid预付费功能交易

pan_entry_mode​

枚举值ISO 8583含义
unknown00PAN 输入模式未知。
typed01PAN 手动输入（键入）。
bar_code03通过条码阅读器输入 PAN
ocr04通过 OCR（光学字符识别）输入 PAN
chip05通过集成电路卡（芯片）输入 PAN
track_106通过磁条卡的 Track 1 输入 PAN
contactless07通过 Contactless EMV 输入 PAN
fallback_typed79尝试使用设备的卡片阅读器或磁条阅读器但无法处理（可能是设备或卡片问题），随后手动输入 PAN。某些情况下收单机构未获 CHIP 或磁条授权而发送此代码。
fallback_magnetic_stripe80尝试使用设备的卡片阅读器但无法处理（可能是设备或卡片问题），随后使用卡片磁条。
ecommerce81电商/非现场交易
magnetic_stripe90磁条交易（卡片无芯片或设备无阅读器/未获授权）

还有其他 PAN_ENTRY_MODE 值，但通常不使用。

source_account​

枚举值ISO 8583含义
default00默认或未指定
saving_account10储蓄账户
checking_account20活期账户
credit_facility30账单
universal_account40通用账户
investment_account50投资账户
electronic_purse60卡片芯片中存储的余额（电子钱包）

brand​

枚举值含义
visaVisa
mastercardMasterCard
diners_clubDiners Club
eloElo
american_expressAmerican Express

category​

枚举值含义
classicClassic
goldGold
platinumPlatinum
blackBlack/Infinite
travelTravel
corporateCorporate/Business
prepaid预付费

terminal_type​

枚举值含义
0Unknown
1No terminal used
2Magnetic stripe reader
3Bar code (reserved for future use)
4Optical Character Recognition (reserved for future use)
5Magnetic stripe reader and EMV specification compatible integrated circuit card (ICC) reader
6Key entry only
7Magnetic stripe reader and key entry
8Magnetic stripe reader and key entry and EMV-compatible ICC reader
9EMV compatible ICC reader

发送 Transaction​

Request Body
  {
    "id": "12345",
    ...
  }
Response Body
  {
    "id": "12345",
    "fraud_status": "automatically_approved"
  }

要评估交易，只需将 Transaction 类型的对象发送到以下端点，并适当设置标志：

POST https://api.production-sa.zaig.com.br/card_issuance/transaction?analyze=true

analyze 参数用于避免不需要分析的交易通过欺诈引擎，从而污染数据库。该参数的默认值为 true，因此只有明确标记的交易不会被分析。

更新 Transaction 状态​

Request Body：授权交易时
{
  "transaction_status": "authorized",
  "response_code": "05"
}
Request Body：部分取消交易时
{
  "transaction_status": "partially_cancelled",
  "partial_amount" : 3000,
  "response_code": "05"
}

为确保已实施规则和人工智能模型的反馈，需要在交易取消时通知系统。为此，应使用 PUT 方法发送请求，正常认证：

PUT https://api.production-sa.zaig.com.br/card_issuance/transaction/123456

查询 Transaction​

要检索特定 Transaction，只需发送 GET 请求。返回的结果是该 Transaction 的最新 JSON。如果该标识符与任何对象无关联，则返回 HTTP 状态码 404。

GET https://api.production-sa.zaig.com.br/card_issuance/transaction/12345678

curl "https://api.production-sa.zaig.com.br/card_issuance/transaction/12345678"
  -H "Authorization: EXAMPLE_API_KEY"

上述命令返回表示 Transaction 对象的 JSON。

搜索 Transactions​

Response Body：Transaction 对象列表。
[
  {
    "id": "12345",
    ...
  },
  {
    "id": "12345",
    ...
  }
]

如果需要搜索 Transaction，可以使用带查询参数的 GET 请求。返回的结果是表示 Transaction 列表的 JSON。如果使用发送的参数未找到对象，则返回 HTTP 状态码 200，响应体中包含空列表。

GET https://api.production-sa.zaig.com.br/card_issuance/transactions?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20

以下参数可用于搜索：

参数默认值描述
initial_datenull从 transaction_date 字段返回的第一个日期
final_datenull从 transaction_date 字段返回的最后一个日期
cardholder_idnull发行机构中持卡人的标识符
page_number0所需结果页码，从零开始
page_rows50单次查询返回的最大对象数