Orders Update

Overview

You can send information related to updating the status of orders to Legiti through the /order endpoint using a PUT request type. In addition, you can also mark an order as fraudulent using the /order/mark_fraudulent POST endpoint, update information for a payment through the /order/payment PUT endpoint, and update information for a delivery through the /order/delivery PUT endpoint.

When to Track

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

Entities

Updating the status of an order

You should use this endpoint to notify Legiti every time an order has its status changed.
{
"id": "12345",
"status": "cancelled",
"status_reason": "User requested"
}
Property
Type
Description
id
String
The order's unique identifier within your platform. Must be the same id used when creating the order
status
String
Order status. Allowed values are: approved, declined, pending, cancelled, manual_analysis, unauthorized. You can check more about it [here]](orders-update.md#order-status-description)
status_reason
String
The reason for the status change
custom_data
JSON for saving customizable data for each client

Order Marked Fraudulent

You should use this endpoint to notify Legiti when an order has been rejected due to suspected fraud or if an order has turned into a chargeback.
If an order is deemed fraudulent (either via your existing antifraud solution, manual analysis, acquirer rejection, or even if you receive a chargeback), it is extremely important that you relay this information to Legiti. This is perhaps the most valuable piece of information you can send to us; all of our fraud prediction models are trained on this label.
{
"order_id": "12345",
"fraud_signal_type": "chargeback"
}
Property
Type
Description
order_id
String
The order's unique identifier within your platform
fraud_signal_type
String
The mechanism by which you identified the order as fraudulent. Allowed values are: acquirer, manual_analysis, chargeback, third_party_antifraud, other. You can find more here
fraud_comment
String
For adding relevant information about fruad_signal_type. Is recommend when the fraud_signal_type is other or third_party_antifraud
custom_data
JSON for saving customizable data for each client

Delivery Update

You should use this endpoint to notify Legiti whenever a delivery has its data changed. It is important to note that if you need to indicate that the order was delivered, you must send a value in the delivery_datetime field of this entity, so Legiti will understand that the item was delivered.
{
"id": "1569723",
"order_id": "12345",
"delivery_datetime": "2020-12-17T00:48:03Z",
"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
order_id
String
The order's unique identifier within your platform. Must be the same id used when creating the order
type
String
The delivery's shipping type. Allowed values are: normal, express, and pickup
delivery_datetime
String
The date that the item was delivered in UTC following the ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)
deliverer
Deliverer
Information about the deliverer of the item
scheduled
Boolean
Indicates if the delivery is scheduled for a future date

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 unique identifier of the deliverer on your platform
email
String
The primary email associated with the deliverer
document
String
The document number associated with the deliverer
document_type
String
The document type used. Acceptable 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
country code associated to the phone number (numbers only). Note: if phone_country_code is provided, phone_number is also mandatory
password_hash
String
The protected password (salted and hashed) associated with the deliverer
name
String
Full name of the deliverer
gender
String
The gender of the deliverer. Accepted values are: male, female, other, and undisclosed
user_type
String
The type of deliverer on your platform. Accepted values are: consumer, service_provider
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 date and time of when the deliverer's account was created
address
Address
The address associated with the deliverer
custom_data
JSON for capturing custom data for each customer

Payment Update

You must use this endpoint to notify Legiti of the acquirer ID for a payment. This endpoint should be used only if the acquirer_id field was not sent during order-creation. This entity should be used rarely, if you are in doubt whether to use it or not, please contact our Legiti Customer Solutions team.
{
"id": "852456",
"order_id": "12345",
"acquirer_id": "54d5sf4654fsdwhd"
}
Property
Type
Description
id
String
The unique identifier of the payment on your platform. Must be the same id used when creating the order
order_id
String
The unique identifier of the order on your platform. Must be the same id used when creating the order
acquirer_id
String
The unique identifier for each transaction returned by the acquirer/gateway. This identifier is used to match chargebacks to orders
custom_data
JSON to capture custom data for each customer

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

Order Marked Fraudulent

These are the descriptions for the fraud_signal_type field in the order marked fraudulent entity:
Status
Description
acquirer
The payment was rejected by the acquirer because of fraud suspicion
manual_analysis
The order was reviewed by a human and rejected for fraud suspicion
chargeback
A chargeback was received for this order
third_party_antifraud
The order was rejected by another fraud solution provider. Only to be used when working with a different anti fraud solution in parallel to Legiti. Be aware, that you should pass the name of the anti fraud solution in the field fraud_comment
other
Some other signal indicating fraud or fraud suspicion. In this case we recommend you pass more details through the field fraud_comment

API Endpoints

Order status update

Notify Legiti whenever the status of an order is updated.
It is important to adhere to our API error handling best practices
Curl
Python
Node.js
PHP
Ruby
Java
curl -X PUT https://legiti-api.lgtcdn.net/v2/order \
-H "Authorization: Bearer $API_KEY" \
-d '{
"id": "12345",
"status": "unauthorized",
"status_reason": "Invalid card number"
}'
import json
import requests
headers = {
'Authorization': 'Bearer $API_KEY',
}
data = {
'id': '12345',
'status': 'unauthorized',
'status_reason': 'Invalid card number',
}
try:
response = requests.put(
'https://legiti-api.lgtcdn.net/v2/order',
headers=headers,
data=json.dumps(data),
timeout=2,
)
except requets.exceptions.TimeoutError as e:
print(e)
import fetch from 'node-fetch'
import AbortController from 'node-abort-controller'
const url = 'https://legiti-api.lgtcdn.net/v2/order';
const controller = new AbortController();
const signal = controller.signal;
setTimeout(() => controller.abort(), 2000);
var headers = {
'Authorization': 'Bearer $API_KEY'
};
var data = {
'id': '12345',
'status': 'unauthorized',
'status_reason': 'Invalid card number'
};
fetch(url, { method: 'PUT', headers: headers, body: data, signal: signal})
.then((res) => {
return res.json()
})
.then((json) => {
console.log(json);
// Do something with the returned data.
});
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
'Authorization' => 'Bearer $API_KEY'
);
$data = array(
'id' => '12345',
'status' => 'unauthorized',
'status_reason' => 'Invalid card number'
);
$options = array(
'timeout' => 2,
);
$response = Requests::put(
'https://legiti-api.lgtcdn.net/v2/order',
$headers,
json_encode($data),
$options
);
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://legiti-api.lgtcdn.net/v2/order")
request = Net::HTTP::Put.new(uri)
request.read_timeout = 2
request["Authorization"] = "Bearer $API_KEY"
request.body = JSON.dump({
"id" => "12345",
"status" => "unauthorized",
"status_reason" => "Invalid card number"
})
req_options = {
use_ssl: uri.scheme == "https",
}
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
http.request(request)
end
import okhttp3.*;
OkHttpClient client = new OkHttpClient().newBuilder()
.setConnectTimeout(2, TimeUnit.SECONDS)
.build();
String data = "{
\"id\": \"12345\",
\"status\": \"unauthorized\",
\"status_reason\": \"Invalid card number\"
}"
RequestBody body = RequestBody.create(mediaType, data)
Request request = new Request.Builder()
.url("https://legiti-api.lgtcdn.net/v2/order")
.method("PUT", body)
.addHeader("Authorization", "Bearer $API_KEY")
.build();
Response response = client.newCall(request).execute();
You can check our API responces here
Property
Required
Type
id
Yes
String
status
Yes
String (accepted values: approved, declined, pending, cancelled, manual_analysis, unauthorized)
status_reason
No
String
custom_data
No
predefined JSON

Order Marked Fraudulent

Notify Legiti that an order was found to be fraudulent.
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/mark_fraudulent \
-H "Authorization: Bearer $API_KEY" \
-d '{
"order_id": "12345",
"fraud_signal_type": "chargeback",
"fraud_comment": "This is a chargeback",
}'
import json
import requests
headers = {
'Authorization': 'Bearer $API_KEY',
}
data = {
'order_id': '12345',
'fraud_signal_type': 'chargeback',
'fraud_comment': 'This is a chargeback',
}
try:
response = requests.post(
'https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent',
headers=headers,
data=json.dumps(data),
timeout=2,
)
except requets.exceptions.TimeoutError as e:
print(e)
import fetch from 'node-fetch'
import AbortController from 'node-abort-controller'
const url = 'https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent';
const controller = new AbortController();
const signal = controller.signal;
setTimeout(() => controller.abort(), 2000);
var headers = {
'Authorization': 'Bearer $API_KEY'
};
var data = {
'order_id': '12345',
'fraud_signal_type': 'chargeback',
'fraud_comment': 'This is a chargeback'
};
fetch(url, { method: 'POST', headers: headers, body: data, signal: signal})
.then((res) => {
return res.json()
})
.then((json) => {
console.log(json);
// Do something with the returned data.
});
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
'Authorization' => 'Bearer $API_KEY'
);
$data = array(
'order_id' => '12345',
'fraud_signal_type' => 'chargeback',
'fraud_comment' => 'This is a chargeback',
);
$options = array(
'timeout' => 2,
);
$response = Requests::post(
'https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent',
$headers,
json_encode($data),
$options
);
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent")
request = Net::HTTP::Post.new(uri)
request.read_timeout = 2
request["Authorization"] = "Bearer $API_KEY"
request.body = JSON.dump({
"order_id" => "12345",
"fraud_signal_type" => "chargeback",
"fraud_comment" => "This is a chargeback",
})
req_options = {
use_ssl: uri.scheme == "https",
}
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
http.request(request)
end
import okhttp3.*;
OkHttpClient client = new OkHttpClient().newBuilder()
.setConnectTimeout(2, TimeUnit.SECONDS)
.build();
String data = "{
\"order_id\": \"12345\",
\"fraud_signal_type\": \"chargeback\",
\"fraud_comment\": \"This is a chargeback\",
}"
RequestBody body = RequestBody.create(mediaType, data)
Request request = new Request.Builder()
.url("https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent")
.method("POST", body)
.addHeader("Authorization", "Bearer $API_KEY")
.build();
Response response = client.newCall(request).execute();
You can check our API responces here
Property
Required
Type
order_id
Yes
String
status
Yes
String (accepted values: chargeback, acquirer, manual_analysis, third_party_antifraud, other)
fraud_comment
No
String
custom_data
No
predefined JSON

Delivery Updates

In case you need to indicate that the order was delivered, you must pass a value in the delivery_datetime field of this entity, so Legiti will understand that the item was delivered
Notify Legiti of delivery information updates.
It is important to adhere to our API error handling best practices
Curl
Python
Node.js
PHP
Ruby
Java
curl -X PUT https://legiti-api.lgtcdn.net/v2/order/delivery \
-H "Authorization: Bearer $API_KEY" \
-d '{
"id": "974613",
"order_id": "12345",
"delivery_datetime": "2020-12-17T00:48:03Z",
"deliverer": {
"id": "456987",
"name": "João Entregador"
}
}'
import json
import requests
headers = {
'Authorization': 'Bearer $API_KEY',
}
data = {
'id': '974613',
'order_id': '12345',
'delivery_datetime': '2020-12-17T00:48:03Z',
'deliverer': {
'id': '456987',
'name': 'João Entregador'
}
}
try:
response = requests.put(
'https://legiti-api.lgtcdn.net/v2/order/delivery',
headers=headers,
data=json.dumps(data),
timeout=2,
)
except requets.exceptions.TimeoutError as e:
print(e)
import fetch from 'node-fetch'
import AbortController from 'node-abort-controller'
const url = 'https://legiti-api.lgtcdn.net/v2/order/delivery';
const controller = new AbortController();
const signal = controller.signal;
setTimeout(() => controller.abort(), 2000);
var headers = {
'Authorization': 'Bearer $API_KEY'
};
var data = {
'id': '974613',
'order_id': '12345',
'delivery_datetime': '2020-12-17T00:48:03Z',
'deliverer': {
'id': '456987',
'name': 'João Entregador'
}
};
fetch(url, { method: 'PUT', headers: headers, body: data, signal: signal})
.then((res) => {
return res.json()
})
.then((json) => {
console.log(json);
// Do something with the returned data.
});
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
'Authorization' => 'Bearer $API_KEY'
);
$data = array(
'id' => '974613',
'order_id' => '12345',
'delivery_datetime' => '2020-12-17T00:48:03Z',
'deliverer' => array(
'id' => '456987',
'name' => 'João Entregador'
)
);
$options = array(
'timeout' => 2,
);
$response = Requests::put(
'https://legiti-api.lgtcdn.net/v2/order/delivery',
$headers,
json_encode($data),
$options
);
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://legiti-api.lgtcdn.net/v2/order/delivery")
request = Net::HTTP::Put.new(uri)
request.read_timeout = 2
request["Authorization"] = "Bearer $API_KEY"
request.body = JSON.dump({
"id" => "974613",
"order_id" => "12345",
"delivery_datetime" => "2020-12-17T00:48:03Z",
"deliverer" => {
"id" => "456987",
"name" => "João Entregador"
}
})
req_options = {
use_ssl: uri.scheme == "https",
}
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
http.request(request)
end
import okhttp3.*;
OkHttpClient client = new OkHttpClient().newBuilder()
.setConnectTimeout(2, TimeUnit.SECONDS)
.build();
String data = "{
\"id\": \"974613\",
\"order_id\": \"12345\",
\"delivery_datetime\": \"2020-12-17T00:48:03Z\",
\"deliverer\": {
\"id\": \"456987\",
\"name\": \"João Entregador\"
}
}"
RequestBody body = RequestBody.create(mediaType, data)
Request request = new Request.Builder()
.url("https://legiti-api.lgtcdn.net/v2/order/delivery")
.method("PUT", body)
.addHeader("Authorization", "Bearer $API_KEY")
.build();
Response response = client.newCall(request).execute();
You can check our API responces here
Property
Required
Type
id
Yes
String
order_id
Yes
String
type
No
String (valores aceitos: normal, express, pickup)
delivery_datetime
No
String (format YYYY-MM-DDTHH:mm:ssZ in UTC)
scheduled
No
Boolean
deliverer*
No
Deliverer
 ↳ id
Yes
String
name
Yes
String
email
No
String
creation_datetime
No
String (format YYYY-MM-DDTHH:mm:ssZ in UTC)
social_login
No
String (accepted values: facebook, apple, google, twitter)
document
No
String
document_type
No
String
phone_number
No
String
phone_country_code
No
String
password_hash
No
String
gender
No
String (accepted values: male, female, other, e undisclosed)
address*
No
Address
  ↳ street_name
Yes
String
  street_number
Yes
String
  city
Yes
String
  state
Yes
String
  country
Yes
String
  zip_code
No
String
  details
No
String
  label
No
String
  latitude
No
Float
  longitude
No
Float
  custom_data
No
predefined JSON
custom_data
No
predefined JSON
custom_data
No
predefined JSON
*The entity is not required, but if included, some of its fields are

Payment Update

This endpoint should be used only if the acquirer_id field was not sent during order-creation. This entity should rarely be used, if in doubt whether to use it or not, contact our Customer Solutions team
Send to Legiti the acquirer id of a payment.
It is important to adhere to our API error handling best practices
Curl
Python
Node.js
PHP
Ruby
Java
curl -X PUT https://legiti-api.lgtcdn.net/v2/order/payment \
-H "Authorization: Bearer $API_KEY" \
-d '{
"id": "974613",
"order_id": "12345",
"acquirer_id": "12645762"
}'
import json
import requests
headers = {
'Authorization': 'Bearer $API_KEY',
}
data = {
'id': '974613',
'order_id': '12345',
'acquirer_id': '12645762'
}
try:
response = requests.put(
'https://legiti-api.lgtcdn.net/v2/order/payment',
headers=headers,
data=json.dumps(data),
timeout=2,
)
except requets.exceptions.TimeoutError as e:
print(e)
import fetch from 'node-fetch'
import AbortController from 'node-abort-controller'
const url = 'https://legiti-api.lgtcdn.net/v2/order/payment';
const controller = new AbortController();
const signal = controller.signal;
setTimeout(() => controller.abort(), 2000);
var headers = {
'Authorization': 'Bearer $API_KEY'
};
var data = {
'id': '974613',
'order_id': '12345',
'acquirer_id': '12645762'
};
fetch(url, { method: 'PUT', headers: headers, body: data, signal: signal})
.then((res) => {
return res.json()
})
.then((json) => {
console.log(json);
// Do something with the returned data.
});
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
'Authorization' => 'Bearer $API_KEY'
);
$data = array(
'id' => '974613',
'order_id' => '12345',
'acquirer_id' => '12645762'
);
$options = array(
'timeout' => 2,
);
$response = Requests::put(
'https://legiti-api.lgtcdn.net/v2/order/payment',
$headers,
json_encode($data),
$options
);
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://legiti-api.lgtcdn.net/v2/order/payment")
request = Net::HTTP::Put.new(uri)
request.read_timeout = 2