Creation and Evaluation of Orders

Overview

You can send information related to orders to Legiti through the /order endpoint, which supports POST requests. In this endpoint you can specify, through the evaluate flag, whether or not you want to receive an evaluation from Legiti for this order. If you wish to receive Legiti's evaluation, it is important that you treat the API response differently.

When to Track

You can see more information about where to add these endpoints in your payment flow here

Entities

Order

{
"id": "12345",
"evaluate": true,
"total_paid_value": 110.0,
"total_gross_value": 100.0,
"discount_value": 10.0,
"shipping_value": 10.0,
"tip_value": 5.0,
"coupon_names": ["LOTR"],
"currency": "BRL",
"status": "pending",
"creation_datetime": "2020-02-10T20:18:40Z",
"tax_invoice_document_type": "cpf",
"tax_invoice_document": "12345678911",
"user": {
"id": "98745",
"name":"john fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55",
"password_hash": "effebbbeeabc123",
"gender": "male",
"social_login": "facebook",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Apto 11",
"label": "Casa"
}
},
"items": [
{
"quantity":2,
"unit_price":30,
"unit_discount":0,
"total_value":60,
"product": {
"sku": "15975368",
"title": "Product A",
"product_id": "123",
"ean": "1589461449846",
"description": "Cool Product A",
"categories": ["8"],
"seller": {
"id": "852456",
"name": "Meu Marketplace",
"description": "O melhor marketplace de todos",
"email": "[email protected]",
"categories": ["9", "45"],
"subcategories": ["4541", "41546"],
"document_type": "cnpj",
"document": "45.543.948/0001-00",
"phone_country_code": "+55",
"phone_number": "1138544649",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Conjunto 15"
}
}
},
"delivery": {
"id": "1569723",
"type": "normal",
"scheduled": false,
"deliverer": {
"id": "456987",
"name": "João Entregador"
}
}
},
{
"quantity":1,
"unit_price":50.0,
"unit_discount":10.0,
"total_value":40.0,
"product": {
"sku": "75363418",
"title": "Product B",
"product_id": "456",
"ean": "4194874146871",
"description": "Cool Product B",
"categories": ["8", "9"],
"seller": {
"id": "74123",
"name": "Meu Marketplace 2",
"description": "O segundo melhor marketplace de todos",
"email": "[email protected]",
"categories": ["9", "45"],
"subcategories": ["4541", "41546"],
"document_type": "cnpj",
"document": "77.852.965/0001-00",
"phone_country_code": "+55",
"phone_number": "1138555649",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "253",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Conjunto 15"
}
}
},
"delivery": {
"id": "1569723",
"type": "normal",
"scheduled": false,
"deliverer": {
"id": "456987",
"name": "João Entregador"
}
}
}
],
"payments": [
{
"id": "974613",
"method": "credit_card",
"payment_value": 110.0,
"installments": 1,
"interest": 0.1,
"document_type": "cpf",
"document": "12345678911",
"credit_card": {
"first_six_digits": "123456",
"last_four_digits": "1234",
"expiration_date": "23/05",
"holder_name": "Random da Silva"
},
"billing_address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR"
}
}
],
"shipping_address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Apto 308",
"label": "Home"
}
}
Property
Type
Description
id
String
The order's unique identifier within your platform. This is the id that will be used in the dashboards provided by Legiti
evaluate
Boolean
Indicates whether Legiti should return an evaluation for the the order or not
user
User
Information about the user
total_paid_value
Float
The exact amount that the user paid (total_paid_value = total_gross_value + shipping_value + tip_value - discount_value)
total_gross_value
Float
The sum of all the order items value, without summing shipping_value, discount_value and tip_value
discount_value
Float
The discount value applied to the order
shipping_value
Float
Delivery's shipping value
tip_value
Float
The tip paid by the user to the deliverer
coupon_names
Array of Strings
The name of the coupons that were applied (if any). Note: if coupon_names is provided, discount_value is also required
currency
String
The currency of the total_paid_value, as an ISO-4217 currency code
status
String
The status of the order. _The allowed values are: approved, declined, pending, cancelled, manual_analysis, and unauthorized__. You can find more here
status_reason
String
The reason for the status change.
tax_invoice_document_type
String
The document type associated with the tax invoice (a.k.a "nota fiscal") document number. Accepted values are cpf, cnpj, and other
tax_invoice_document
String
The document number associated with the tax invoice (a.k.a "nota fiscal")
items
Array of Item
The purchased items (e.g. products)
payments
Array of Payment
The payments used in this purchase
shipping_address
Address
The delivery's address. Not necessary if the product does not require shipping
creation_datetime
String
The datetime when the order was created. The value should be in UTC following the ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)
custom_data
JSON for saving customizable data for each client

User

Legiti standardized format for representing users.
{
"id": "12345",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code": "55",
"password_hash": "effebbbeeabc123",
"name": "john fulano",
"gender": "male",
"user_type": "consumidor",
"social_login": "facebook",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Apto 11",
"label": "Casa"
}
}
Property
Type
Description
id
String
Your unique identifier for this user in your platform
email
String
The main email associated with the user
document
String
The document number associated with the user
document_type
String
The document type associated with the user's document number. Accepted values are cpf, cnpj, passport, rg, rne, and other
phone_number
String
The main phone number associated with the user (numbers only; country code not included). Note: if phone_number is provided, phone_country_code is also required
phone_country_code
String
The international country code associated with the phone number (numbers only). Note: if phone_country_code is provided, phone_number is also required
password_hash
String
The secure (salted and hashed) password associated with the user
name
String
The user's full name
gender
String
The user's gender. Accepted values are: male, female, other, and undisclosed
social_login
String
If the user signed-up using a third-party service. Accepted values are: facebook, apple, google, twitter
creation_datetime
String (format YYYY-MM-DDTHH:mm:ssZ in UTC)
The datetime of when the user account was created
address
Address
The address associated with the user
custom_data
JSON for saving customizable data for each client

Item

Legiti standardized format for representing purchased items.
{
"quantity":2,
"unit_price":30,
"unit_discount":0,
"total_value":60,
"product": {
"sku": "15975368",
"title": "Product A",
"product_id": "123",
"ean": "1589461449846",
"description": "Cool Product A",
"categories": ["8"],
"seller": {
"id": "852456",
"name": "Meu Marketplace",
"description": "O melhor marketplace de todos",
"email": "[email protected]",
"categories": ["9", "45"],
"subcategories": ["4541", "41546"],
"document_type": "cnpj",
"document": "45.543.948/0001-00",
"phone_country_code": "+55",
"phone_number": "1138544649",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Conjunto 15"
}
}
},
"delivery": {
"id": "1569723",
"type": "normal",
"delivery_datetime": "2020-02-11T20:18:40Z",
"scheduled": false,
"deliverer": {
"id": "456987",
"name": "João Entregador"
}
}
Property
Type
Description
quantity
Integer
The purchased quantity of this product
unit_price
Float
The purchased product's unit price
unit_discount
Float
The discount amount applied to each unit of this product
total_value
Float
The total value paid for this product
product
Product
The associated Product
delivery
Delivery
The associated Delivery
custom_data
JSON for saving customizable data for each client

Product

Legiti standardized format for representing a product.
{
"sku": "15975368",
"title": "Product A",
"product_id": "123",
"ean": "1589461449846",
"description": "Cool Product A",
"categories": ["8"],
"seller": {
"id": "852456",
"name": "Meu Marketplace",
"description": "O melhor marketplace de todos",
"email": "[email protected]",
"categories": ["9", "45"],
"subcategories": ["4541", "41546"],
"document_type": "cnpj",
"document": "45.543.948/0001-00",
"phone_country_code": "+55",
"phone_number": "1138544649",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Conjunto 15"
}
}
Property
Type
Description
sku
String
The product sku or unique identifier within your platform
title
String
The product title
product_id
String
The product secondary id (it can be the id of the main product if this is a variation only)
ean
String
The product barcode number
seller
Seller
Information about the seller of the product
description
String
The product description
categories
Array of String
Your platform categories that apply to this product. (Arbitrary categories accepted, but must be consistent.)
custom_data
JSON for saving customizable data for each client
Seller
{
"id": "852456",
"name": "Meu Marketplace",
"description": "O melhor marketplace de todos",
"email": "[email protected]",
"categories": ["9", "45"],
"subcategories": ["4541", "41546"],
"document_type": "cnpj",
"document": "45.543.948/0001-00",
"phone_country_code": "+55",
"phone_number": "1138544649",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Conjunto 15"
}
}
Property
Type
Description
id
String
The unique identifier of the seller on your platform. This is the id that will be used in the dashboards provided by Legiti.
name
String
The name of the seller
description
String
The seller description
email
String
The main email associated with the seller
categories
Array of String
The categories associated with the seller
subcategories
Array of String
The subcategories associated with the seller
document
String
The document number associated with the seller
document_type
String
The document type associated with the seller's document number. Accepted values are cpf, cnpj, and other
phone_number
String
The main phone number associated with the seller (numbers only; country code not included). Note: if phone_number is provided, phone_country_code is also required
phone_country_code
String
The international country code associated with the phone number (numbers only). Note: if phone_country_code is provided, phone_number is also required
creation_datetime
String (format YYYY-MM-DDTHH:mm:ssZ in UTC)
The datetime of when the seller account was created
address
Address
The address associated with the seller
custom_data
JSON for saving customizable data for each client

Delivery

Legiti standardized format for representing a product delivery.
{
"id": "1569723",
"type": "normal",
"scheduled": false,
"deliverer": {
"id": "456987",
"name": "João Entregador"
}
}
Property
Type
Description
id
String
The delivery's unique identifier within your platform. Be advised, this is the id used to update delivery information afterwards
type
String
The delivery's shipping type. The allowed values are: normal, express, and pickup
delivery_datetime
String
Date that the item was delivered in UTC following the ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). This value will normally be received at the delivery update endpoint
deliverer
Deliverer
Information about the deliverer of the product
scheduled
Boolean
Indicates if the delivery is scheduled for a future date
custom_data
JSON for saving customizable data for each client
Deliverer
Legiti standardized format for representing a deliverer.
{
"id": "456987",
"name": "João Entregador",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code": "55",
"password_hash": "effebbbeeabc123",
"gender": "male",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Apto 11",
"label": "Casa"
}
}
Property
Type
Description
id
String
The deliverer unique identifier within your platform
email
String
The main email associated with the deliverer
document
String
The document number associated with the deliverer
document_type
String
The document type associated with the deliverer's document number. Accepted values are cpf, cnpj, passport, rg, rne, and other
phone_number
String
The main phone number associated with the deliverer (numbers only; country code not included). Note: if phone_number is provided, phone_country_code is also required
phone_country_code
String
The international country code associated with the phone number (numbers only). Note: if phone_country_code is provided, phone_number is also required
password_hash
String
The secure (salted and hashed) password associated with the deliverer
name
String
The deliverer's full name
gender
String
The deliverer's gender. Accepted values are: male, female, other, and undisclosed
social_login
String
If the deliverer signed-up using a third-party service. Accepted values are: facebook, apple, google, twitter
creation_datetime
String (format YYYY-MM-DDTHH:mm:ssZ in UTC)
The datetime of when the deliverer account was created
address
Address
The address associated with the deliverer
custom_data
JSON for saving customizable data for each client

Payment

Legiti standardized format for representing an order's payments.
{
"id": "974613",
"acquired_id": "123654789",
"method": "credit_card",
"payment_value": 110.0,
"installments": 1,
"interest": 0.1,
"document_type": "cpf",
"document": "12345678911",
"credit_card": {
"first_six_digits": "123456",
"last_four_digits": "1234",
"expiration_date": "23/05",
"holder_name": "Random da Silva"
},
"billing_address":{
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR"
}
}
Property
Type
Description
id
String
The unique identifier for the payment within your platform. If you don't have one you can send us the order id. Be advised that this is the identifier to be used if in the future you need to update payment information
acquirer_id
String
The unique identifier for each transaction returned by the acquirer/gateway. This id is used for linking chargebacks
method
String
The payment's method. The allowed values are credit_card, boleto, wallet, cash, vr (vale refeição), pix, transfer, apple_pay, google_pay, and other
payment_value
Float
The amount payed
installments
Integer
The number of installments (e.g. "parcelas") to be paid.
interest
Float
The applied interest rate - where 0 means no interest was applied and 1 means 100% monthly interest was applied
document_type
String
The document type associated with the payment's document number. Accepted values are cpf, cnpj, passport, rg, rne, and other
document
String
The document number associated with the payer
credit_card
The credit card associated with the payment. Note: credit_card is required only if the method is credit_card
billing_address
Address
The billing address associated with the payment. Note: billing_address is required only if the method is credit_card or boleto
custom_data
JSON for saving customizable data for each client

Credit Card

Legiti standardized format for representing a payment's credit card information.
{
"first_six_digits": "123456",
"last_four_digits": "1234",
"expiration_date": "23/05",
"holder_name": "Random da Silva"
}
Property
Type
Description
Placeholder Values*
first_six_digits
String
The first six digits of the credit card number (should be only digits)
999999
last_four_digits
String
The last four digits of the credit card number (should be only digits)
9999
expiration_date
String
The credit card's expiration date, formatted as mm/yy
XX/XX
holder_name
String
The credit card holder's full name.
Unavailable
custom_data
JSON for saving customizable data for each client
-
*If you do not have any credit card information you can use these values as placeholder in place of the missing information

Status Description

Order Status

These are the descriptions for the status field in the order entity:
Order statuses
Status
Description
approved
The order was approved and is expected to be delivered to the consumer
declined
The order was rejected for fraud suspicion (either from Legiti or another anti-fraud provider)
unauthorized
The payment was not approved by the acquirer
pending
The order hasn’t been rejected nor approved and its payment hasn’t been processed yet. You are still deciding if you should approve or reject the order
manual_analysis
The order was sent to a human for review
cancelled
The order has been cancelled or refunded and will no longer be delivered or the consumer is returning it

API Endpoints

Creation and evaluation of orders

For receiving the evaluation for this order the flag evaluate must be set to true
Notifies Legiti whenever a new order is created. If the evaluate flag is true the endpoint will return Legiti's evaluation for this order.
Legiti should receive all the orders on the platform, even the non-credit card ones, since these orders can be used to evaluate other orders. Importantly, for non-credit card orders the flag evaluate should be set to false.
It is important to adhere to our API error handling best practices
Curl
Python
Node.js
PHP
Ruby
Java
curl -X POST https://legiti-api.lgtcdn.net/v2/order \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"id": "12345",
"evaluate": true,
"total_paid_value": 110.0,
"total_gross_value": 100.0,
"discount_value": 10.0,
"shipping_value": 10.0,
"tip_value": 5.0,
"coupon_names": ["LOTR"],
"currency": "BRL",
"status": "pending",
"creation_datetime": "2020-02-10T20:18:40Z",
"tax_invoice_document_type": "cpf",
"tax_invoice_document": "12345678911",
"user": {
"id": "98745",
"name":"john fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55",
"password_hash": "effebbbeeabc123",
"gender": "male",
"social_login": "facebook",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Apto 11",
"label": "Casa"
}
},
"items": [
{
"quantity":2,
"unit_price":30,
"unit_discount":0,
"total_value":60,
"product": {
"sku": "15975368",
"title": "Product A",
"product_id": "123",
"ean": "1589461449846",
"description": "Cool Product A",
"categories": ["8"],
"seller": {
"id": "852456",
"name": "Meu Marketplace",
"description": "O melhor marketplace de todos",
"email": "[email protected]",
"categories": ["9", "45"],
"subcategories": ["4541", "41546"],
"document_type": "cnpj",
"document": "45.543.948/0001-00",
"phone_country_code": "+55",
"phone_number": "1138544649",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Conjunto 15"
}
}
},
"delivery": {
"id": "1569723",
"type": "normal",
"scheduled": false,
"deliverer": {
"id": "456987",
"name": "João Entregador"
}
}
},
{
"quantity":1,
"unit_price":50.0,
"unit_discount":10.0,
"total_value":40.0,
"product": {
"sku": "75363418",
"title": "Product B",
"product_id": "456",
"ean": "4194874146871",
"description": "Cool Product B",
"categories": ["8", "9"],
"seller": {
"id": "74123",
"name": "Meu Marketplace 2",
"description": "O segundo melhor marketplace de todos",
"email": "[email protected]",
"categories": ["9", "45"],
"subcategories": ["4541", "41546"],
"document_type": "cnpj",
"document": "77.852.965/0001-00",
"phone_country_code": "+55",
"phone_number": "1138555649",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "253",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Conjunto 15"
}
}
},
"delivery": {
"id": "1569723",
"type": "normal",
"scheduled": false,
"deliverer": {
"id": "456987",
"name": "João Entregador"
}
}
}
],
"payments": [
{
"id": "974613",
"method": "credit_card",
"payment_value": 110.0,
"installments": 1,
"interest": 0.1,
"document_type": "cpf",
"document": "12345678911",
"credit_card": {
"first_six_digits": "123456",
"last_four_digits": "1234",
"expiration_date": "23/05",
"holder_name": "Random da Silva"
},
"billing_address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR"
}
}
],
"shipping_address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Apto 308",
"label": "Home"
}
}'
import json
import requests
headers = {
'Authorization': 'Bearer $API_KEY',
}
data = {
'id': '12345',
'evaluate': true,
'total_paid_value': 110.0,
'total_gross_value': 100.0,
'discount_value': 10.0,
'shipping_value': 10.0,
'tip_value': 5.0,
'coupon_names': ['LOTR'],
'currency': 'BRL',
'status': 'pending',
'creation_datetime': '2020-02-10T20:18:40Z',
'tax_invoice_document_type': 'cpf',
'tax_invoice_document': '12345678911',
'user': {
'id': '98745',
'name':'john fulano',
'email': '[email protected]',
'document': '123.456.789-10',
'document_type': 'cpf',
'phone_number': '11999123456',
'phone_country_code':'55',
'password_hash': 'effebbbeeabc123',
'gender': 'male',
'social_login': 'facebook',
'creation_datetime': '2019-12-17T00:48:03Z',
'address': {
'street_name': 'Rua Fidalga',
'street_number': '252',
'zip_code': '05432-010',
'city': 'São Paulo',
'state': 'SP',
'country': 'BR',
'details': 'Apto 11',
'label': 'Casa'
}
},
'items': [
{
'quantity':2,
'unit_price':30,