Exchanges

You are here: Home » Direct Integrations » TIDI Receipt Assignment » Exchanges

POST method only

 

Description:

Use this service to provide the commercial data of a TIDI Receipt Assignment page of a transaction of type “exchange” and retrieve the URL of this TIDI Receipt Assignment page and other methods of interacting with the end-client. 

The identification of the users involved in this request, you and your client, can be provided either on the user_ids section of the body as part of the JSON payload or in the header third_party_cert. The process to use the third_party_cert is described here. The commercial data must be provided in the body in either way.

Important: if the relation between you and your client is not showing as “Accepted” in your account, this request will get blocked. You may read this to understand how to get it accepted.

The TIDI Receipt Assignment’s URL is the attribute «tidi_receipt_assignment_url« of the response. If you wish to integrate the QR code in your front-end, please review a code sample here.

 

 

Input:

Body:

1st JSON level 2nd JSON level Required Type Description

user_ids

{ (5) dict Identifiers of users involved in this transaction: you and the company

user_token

(2) string The user token as described here

relation_key

(6) string The relation key as described here

shared_provider_id

(6) string The shared provider Id as described here
} End of dictionary

client

{

(4) dict End-user data to link the TIDI-receipt

client_email

(2) string with email-like format Email of the client to the send the email to. For instance, "client_email": "example@gmail.com"

}

End of dictionary

employee

{

(4) dict Data of the employee that performed the transaction. Click here to understand the behaviour of this dict.

employee_id

string ID of the employee

employee_name

(2) string Name of the employee. For instance, "employee_name": "John"

employee_surname

(4) string Surname of the employee. For instance, "employee_surname": "García Ramírez"

}

End of dictionary

shop

{

(4) dict Data of the shop where the transaction was performed. Click here to understand the behaviour of this dict.

shop_id

(2) string ID of the shop

shop_address

(2) string Address of the shop. For instance, "shop_address": "Great Street, 45"

}

End of dictionary

returns

[

(1) list Items' data of all items returned
{ (1) dict Data of every single item returned

discount

(4) float The discount applied on this product. As an example, if you apply 15.5% discount, write “discount”: 15.5

promotion

(4) string The promotion that your client’s client is applying on this product, if any. For instance, "promotion": “Christmas campaign”
reason (4) string The reason for returning this object, if your client’s client wishes to share it. For instance, "reason": "Lower price at competitor"

brand

(4) string The brand of the product. For instance, "brand": “Nike”

currency

(1) string The currency in which the price of the product is denominated in ISO-4217, i.e. if it’s USD 20.45, give “currency”: “USD”

price

(3) int The price of the product with the VAT included, i.e. if it’s USD 20.45, give “price”: 2045

price_without_vat

(3) int The price of the product with the VAT excluded, i.e. if it’s USD 20.45, give “price_without_vat”: 2045

product_name

(1) string The name of the product involved in the transaction. For instance, "product_name": "trousers"

product_subtype

(4) string The secondary level of product classification as on your systems. For instance, "product_subtype": "jeans" in the case of a trouser.

product_type

(4) string The primary level of product classification as on your systems. For instance, "product_type": "cloth" in the case of a trouser.

purchasers_id_reference

(4) string The ID of this product as on your client’s provider’s systems, to identify it in the future. For instance, "purchasers_id_reference": “65/R742890”

sellers_id_reference

(1) string The ID of this product as on your systems, to identify it in the future. For instance, "sellers_id_reference": “7859403”

vat

(1) float The VAT percentage applied. If VAT = 7.7%, give “vat”: 7.7

units

(1) int Number of units or bulk weight of this product returned. For instance, "units": 3 or "units": 1.54

}

End of dictionary

]

End of list

sales

[

(1) list Items' data of all items sold
{ (1) dict Data of every single item sold

discount

(4) float The discount applied on this product. As an example, if you apply 15.5% discount, write “discount”: 15.5

promotion

(4) string The discount applied on this product. As an example, if you apply 15.5% discount, write “discount”: 15.5

brand

(4) string The brand of the product. For instance, "brand": “Nike”

currency

(1) string The currency in which the price of the product is denominated in ISO-4217, i.e. if it’s USD 20.45, give “currency”: “USD”

price

(3) int The price of the product with the VAT included, i.e. if it’s USD 20.45, give “price”: 2045

price_without_vat

(3) int The price of the product with the VAT excluded, i.e. if it’s USD 20.45, give “price_without_vat”: 2045

product_name

(1) string The name of the product involved in the transaction. For instance, "product_name": "trousers"

product_subtype

(4) string The secondary level of product classification as on your systems. For instance, "product_subtype": "jeans" in the case of a trouser.

product_type

(4) string The primary level of product classification as on your systems. For instance, "product_type": "cloth" in the case of a trouser.

purchasers_id_reference

(4) string The ID of this product as on your client’s provider’s systems, to identify it in the future. For instance, "purchasers_id_reference": “65/R742890”

sellers_id_reference

(1) string The ID of this product as on your systems, to identify it in the future. For instance, "sellers_id_reference": “7859403”

vat

(1) float The VAT percentage applied. If VAT = 7.7%, give “vat”: 7.7

units

(1) int Number of units or bulk weight of this product sold. For instance, "units": 3 or "units": 1.54

}

End of dictionary

]

End of list
shipping (1) int The shipping cost involved. For instance, if it is CHF 10.00, write “shipping”: 1000

subtotal

(4) int The subtotal of this transaction, this is, including the VAT amount, as on your client’s screen. For instance, if it is USD 155.50, give “subtotal”: 15550. Warning: in the case that it is not provided, it will be automatically calculated by us from each item’s price, price_without_vat, vat, units and/or discount. If you want the amount calculated by you to be reflected in the TIDI-receipt, please provide this number. For more information, please read this

taxes

(4) int The total taxes applied on this transaction. For instance, if it is USD 155.50, give “taxes”: 15550. Warning: in the case that it is not provided, it will be automatically calculated by us from each item’s price, price_without_vat, vat, units and/or discount. If you want the amount calculated by you to be reflected in the TIDI-receipt, please provide this number. For more information, please read this

total

(4) int The total of this transaction, including the VAT amount, as on your client’s screen. For instance, if it is USD 155.50, write “total”: 15550. Warning: in the case that it is not provided, it will be automatically calculated by us from each item’s price, price_without_vat, vat, units and/or discount. If you want the amount calculated by you to be reflected in the TIDI-receipt, please provide this number. For more information, please read this

receipt_id

(1) string The ID of this transaction on your systems, so that you can identify it in the future using your own ID. For instance, "receipt_id": "3-ERQ1542"
current_receipt_id (1) string The ID of the original transaction this exchange transaction is referring to and as on your systems, so that you can identify it in the future. For instance, "current_receipt_id": "1". Pro tip 1: we will validate this field on our system. If you have already provided this as a previous transaction’s receiptId or currentReceiptId, then both transactions will also be linked on our system and your client will see the full history linked for them on their TIDI account as well. If you did not provide it previously, the transaction will still be linked to your client but they will not see to which transaction it was previously linked on our systems. Pro tip 2: this field could be the same as receiptId in case you do not generate new receipt Id’s for exchanges in your system

api_version

(1) string The API version you are targeting. For instance "api_version": "2023_11"

operation_datetime

(1) string The datetime of the operation in ISO-8601 standard. For instance: "operation_datetime": "2022-10-13T18:03:48+02:00"
url_success (1) string with URL-like format The URL to take the company’s employee after the QR code is scanned or the receipt is sent by email. This will be triggered when the user clicks on the button "Finish". In most cases, this is an internal URL of your software.
url_cancel (1) string with URL-like format The URL to take the company’s employee after the Close button is clicked. In most cases, this is an internal URL of your software.

 

Headers:

Key Required Type Description Obtained by
third_party_cert (5) string The third-party certificate obtained from another endpoint Check

 

(1) Compulsory field and cannot be null or empty

(2) If the parent is not null, this field has to appear and cannot be null or empty

(3) Either price or price_without_vat must be provided. In the event of both being provided, the leading one will always be price when calculating the subtotal and total fields.

(4) Optional field

(5) Either the body attribute user_ids or the header third_party_cert must be provided. In the event of both being provided, the leading one will always be user_ids when understanding what users are involved in this transaction.

(6) Either relation_key or shared_provider_id must be provided. In the event of both being provided, the leading one will always be relation_key when understanding what company this data belongs to.

 

 

Output:

1st level Key 2nd level Key Type Description

png_with_qr_bytes_64encoded_as_string

string The PNG with the QR code generated, created as a bytes object, then encoded in base-64 and finally provided to you as a string

operation_id

int ID of the transaction created in our systems (counting all transactions generated, not only of this client of yours), relational only in TIDI’s DB

id_provider_operation

int ID of the transaction of your client created in our systems (referred just to this client), relational only in TIDI’s DB. This will be the recently-created receipt ID of this client within TIDI’s DB
tidi_receipt_assignment_url string The URL to the TIDIReceiptAssingment object created.

status

string “OK” if the request was correct; “NOK” otherwise

http_status

int The HTTP status code

error_trace:

[

list List of errors' data that occurred during the request

{

dict

error_name

string The error that occurred during the request. You may retrieve more information about it with parameter “errors_url”

error_message

string The explanation of the error

error_code

string The internal error code, in case you need to contact support to get it fixed.

}

]

errors_url

string The URL to the list of errors, to retrieve more information