Required Fields for Chargeback Guarantee

This page lists the mandatory operational fields that must be sent on Create Evaluation (POST /v1/antifraud/evaluations) when the merchant is covered by chargeback guarantee, plus the chargeback notification that must be sent after a dispute is reported.

These requirements complement the base OpenAPI contract. Incomplete or empty objects (for example address: {}) may cause validation errors or exclude the transaction from guarantee eligibility.

1. Create Evaluation — root objects

Object	Required	Notes
`type`	Yes	Must be `Ecommerce`.
`buyer`	Yes	Buyer identity, contact, and full address.
`device`	Yes	Session and IP (IPv4 or IPv6).
`store`	Yes	Merchant context and correlation IDs.
`items`	Yes	At least one line item.
`payments`	Yes	Payment instruments used on the order.
`transaction`	Yes	Business transaction identifiers.
`shipping`	Yes when goods/services are shipped or delivered	Full shipping address required for guarantee.
`callback_url`	Recommended	Public HTTPS endpoint for async evaluation status updates.

2. `buyer` (required)

Field	Required	Notes
`email`	Yes	Buyer email.
`full_name` or (`first_name` + `last_name`)	Yes	Provide full name or first and last name.
`phone`	Yes	See phone fields below.
`document`	Yes	See document fields below.
`address`	Yes	Full address — see address fields below. Do not send an empty object.

`buyer.phone`

Field	Required	Notes
`area_code`	Yes	Area / DDD code.
`type`	Yes	Phone type (for example `Mobile`).
`number`	Yes	Phone number.
`country_code`	Recommended	For example `+55`.

`buyer.document`

Field	Required	Notes
`type`	Yes	Document type (for example `CPF`, `DNI`).
`number`	Yes	Document number.
`nationality`	Recommended	Two-letter ISO 3166 country code when available.

`buyer.address` (full address)

Field	Required	Notes
`street`	Yes	Street name.
`number`	Yes	Street number.
`neighborhood`	Yes	Neighborhood / district.
`city`	Yes	City name or code.
`state`	Yes	State name or code.
`country_code`	Yes	Two-letter ISO 3166 country code.
`zip_code`	Yes	Postal / ZIP code.
`complement`	When available	Apartment, floor, landmark, etc.

3. `device` (required)

Field	Required	Notes
`ip_address`	Yes	Buyer device IP (IPv4 or IPv6).
`session_id`	Yes	Session / fingerprint session identifier.

For web checkouts, also integrate device fingerprint per JavaScript Integration and send the token in device as defined in the current OpenAPI.

4. `store` (required)

Field	Required	Notes
`code`	Yes	Store / merchant code configured with Koin.
`reference_id`	Yes	Merchant order identifier. Must stay stable between pre-evaluation and evaluation when both are used.
`category`	Recommended	MCC (merchant category code), when available.

5. `items[]` (required)

Each element must include the shared Item base fields:

Field	Required	Notes
`type`	Yes	Item discriminator (for example `Generic`, `Flight`, `Bus`).
`id`	Yes	Line / SKU identifier in your catalog.
`name`	Yes	Product or service name.
`quantity`	Yes	Quantity sold.
`category.id`	Yes	Category identifier.
`category.name`	Yes	Category name.
`price.currency_code`	Yes	ISO 4217 currency code.
`price.value`	Yes	Unit / line price value.

Additional fields may be required depending on items[].type. See the item types index.

6. `payments[]` — CreditCard (required for card flows)

Field	Required	Notes
`type`	Yes	`CreditCard`.
`amount.currency_code`	Yes	ISO 4217 currency code.
`amount.value`	Yes	Payment amount.
`details.bin`	Yes	Card BIN (first digits).
`details.expiration_month`	Yes	Card expiration month.
`details.expiration_year`	Yes	Card expiration year.
`payer`	Yes	Payer identity — see below.

Prefer tokenized card data (secure_token) when available. Do not send full PAN or CVV in clear text unless the published contract for your API version explicitly requires it.

`payments[].payer`

Field	Required	Notes
`full_name` or (`first_name` + `last_name`)	Yes	Payer name.
`document.type`	Yes	Document type.
`document.number`	Yes	Document number.
`document.nationality`	Yes	Two-letter ISO 3166 country code.

7. `transaction` (required)

Field	Required	Notes
`reference_id`	Yes	Unique business transaction identifier (max length / pattern per OpenAPI). Align with `store.reference_id` as defined by your integration.

8. `shipping` (required when delivery applies)

Field	Required	Notes
`address`	Yes	Full shipping address — same completeness rule as `buyer.address`.

`shipping.address`

Field	Required	Notes
`street`	Yes	Street name.
`number`	Yes	Street number.
`neighborhood`	Yes	Neighborhood / district.
`city`	Yes	City name or code.
`state`	Yes	State name or code.
`country_code`	Yes	Two-letter ISO 3166 country code.
`zip_code`	Yes	Postal / ZIP code.
`complement`	When available	Additional address details.

9. Example — Create Evaluation (minimum for chargeback guarantee)

Illustrative payload. Replace values with real data and validate against the current OpenAPI.

{
  "type": "Ecommerce",
  "buyer": {
    "first_name": "Maria",
    "last_name": "Silva",
    "email": "[email protected]",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "998887766",
      "type": "Mobile"
    },
    "document": {
      "type": "CPF",
      "number": "12345678901",
      "nationality": "BR"
    },
    "address": {
      "street": "Av Paulista",
      "number": "1500",
      "complement": "Apt 42",
      "neighborhood": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP",
      "country_code": "BR",
      "zip_code": "01310100"
    }
  },
  "device": {
    "ip_address": "192.0.2.10",
    "session_id": "sess-order-001"
  },
  "store": {
    "code": "SBXSTORE",
    "reference_id": "ORDER-2026-0001",
    "category": "5411"
  },
  "items": [
    {
      "type": "Generic",
      "id": "SKU-998877",
      "name": "Wireless headphones",
      "quantity": 1,
      "category": {
        "id": "CAT-001",
        "name": "Electronics"
      },
      "price": {
        "currency_code": "BRL",
        "value": 299.9
      }
    }
  ],
  "payments": [
    {
      "type": "CreditCard",
      "amount": {
        "currency_code": "BRL",
        "value": 299.9
      },
      "details": {
        "bin": "411111",
        "expiration_month": "12",
        "expiration_year": "2030"
      },
      "payer": {
        "first_name": "Maria",
        "last_name": "Silva",
        "document": {
          "type": "CPF",
          "number": "12345678901",
          "nationality": "BR"
        }
      }
    }
  ],
  "shipping": {
    "address": {
      "street": "Av Paulista",
      "number": "1500",
      "complement": "Apt 42",
      "neighborhood": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP",
      "country_code": "BR",
      "zip_code": "01310100"
    }
  },
  "transaction": {
    "reference_id": "ORDER-2026-0001"
  },
  "callback_url": "https://www.yourdomain.com/webhooks/antifraud-evaluation"
}

10. Chargeback notification (mandatory after dispute)

When a chargeback (or equivalent dispute) is reported for an already evaluated transaction, the merchant must notify antifraud using Send Notifications.

Item	Value
Method / URL	`PATCH https://api-sandbox.koin.com.br/v1/antifraud/notifications/{id}`
Purpose	Inform antifraud that a chargeback occurred (internal, bank, or scheme entity).
Distinct from	`callback_url` — callbacks are Koin → merchant; this `PATCH` is merchant → Koin.

Path and query parameters

Parameter	Location	Required	Description
`id`	path	Yes	`evaluation_id` returned by Create Evaluation or `store.reference_id` sent on evaluation.
`field`	query	No	Lookup key. Default: `EVALUATION_ID`. Use `REFERENCE_ID` when `{id}` is the merchant `reference_id`. Allowed: `EVALUATION_ID`, `REFERENCE_ID`.

Chargeback body (`type`: `CHARGEBACK`)

Field	Required	Notes
`type`	Yes	Must be `CHARGEBACK`.
`notification_date`	Yes	Notification timestamp (ISO 8601).
`sub_type`	Recommended	`FRAUD`, `NON_FRAUD`, or `PENDING`.
`message`	Optional	Human-readable description.
`details`	Optional	Key/value pairs with extra dispute metadata.

Example — chargeback by `evaluation_id`

curl -X PATCH 'https://api-sandbox.koin.com.br/v1/antifraud/notifications/9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f?field=EVALUATION_ID' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data-binary @- <<'EOF'
{
  "type": "CHARGEBACK",
  "sub_type": "FRAUD",
  "notification_date": "2026-07-21T14:10:44.307Z",
  "message": "Chargeback received from acquirer",
  "details": {
    "reason_code": "4837",
    "case_id": "CB-2026-0001"
  }
}
EOF

Example — chargeback by `reference_id`

curl -X PATCH 'https://api-sandbox.koin.com.br/v1/antifraud/notifications/ORDER-2026-0001?field=REFERENCE_ID' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data-binary @- <<'EOF'
{
  "type": "CHARGEBACK",
  "sub_type": "PENDING",
  "notification_date": "2026-07-21T14:10:44.307Z",
  "message": "Chargeback under review"
}
EOF

Operational rules

Send the chargeback notification whenever the acquirer, issuer, or merchant operations report a chargeback on an evaluated transaction, within the agreed operational window.
Implement retry with backoff for transient failures (5xx, timeout) without duplicating business side effects.
Keep audit logs (type, sub_type, evaluation_id / reference_id, timestamp, HTTP status).
Other notification types (RFI, STATUS, INFO) remain available on the same endpoint; for chargeback guarantee coverage, CHARGEBACK is the mandatory dispute signal.

11. Related references

Create Evaluation
Send Notifications
Antifraud Services Flow
JavaScript Integration (device fingerprint)
Item types index

Field names and enums must always be validated against the current OpenAPI. The published API contract prevails if there is any divergence.

1. Create Evaluation — root objects

2. buyer (required)

buyer.phone

buyer.document

buyer.address (full address)

3. device (required)

4. store (required)

5. items[] (required)

6. payments[] — CreditCard (required for card flows)

payments[].payer

7. transaction (required)

8. shipping (required when delivery applies)

shipping.address