CryptoExchange API :: Create a transaction

Create a transaction

Creating transactions with the Escrow API is straight forward. Consider a simple transaction between myself and a seller, where I am buying a domain name for $1000.


                    
curl "https://cryptoexchange.com/api/v1/escrow/partner/transactions" \
    -X POST \
    -H "Authorization:Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "initiator_id": 17,
    "participant_email": "[email protected]",
    "participant_phone": "+12343342344",
    "initiator_role": "seller",
    "fee_pay_strategy": "buyer",
    "type": "motor_vehicle",
    "price": 12312.33,
    "currency": "USD",
    "crypto_currency": "BTC",
    "payload": {
        "vin": "dfsdfgdgs2342342",
        "odometer": {
            "type": "mi",
            "value": "1000"
        },
        "shipping": {
            "type": "none",
            "payer": "buyer",
            "price": {
                "amount": "",
                "currency": "USD"
            }
        }
    },
    "title": "Ford Focus 2001",
    "phone": "+1885118600",
    "inspection_period": 1,
    "registration_expiry_date": "07/22/2022",
    "notes": ""
}'


                    
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://cryptoexchange.com/api/v1/escrow/partner/transactions',
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_HTTPHEADER => array(
        'Accept: application/json',
    'Authorization:Bearer your-api-key',
    'Content-Type: application/json'
    ),
    CURLOPT_POSTFIELDS => '
    {
    "initiator_id": 17,
    "participant_email": "[email protected]",
    "participant_phone": "+12343342344",
    "initiator_role": "seller",
    "fee_pay_strategy": "buyer",
    "type": "motor_vehicle",
    "price": 12312.33,
    "currency": "USD",
    "crypto_currency": "BTC",
    "payload": {
        "vin": "dfsdfgdgs2342342",
        "odometer": {
            "type": "mi",
            "value": "1000"
        },
        "shipping": {
            "type": "none",
            "payer": "buyer",
            "price": {
                "amount": "",
                "currency": "USD"
            }
        }
    },
    "title": "Ford Focus 2001",
    "phone": "+1885118600",
    "inspection_period": 1,
    "registration_expiry_date": "07/22/2022",
    "notes": ""
}'
));

$output = curl_exec($curl);
echo $output;
curl_close($curl);

Example Response


                    
{
    "id": "44165ddd-e469-415f-a7f0-e7f5a5c316e6"
}

We represent a transaction with a Transaction object. Within the transaction object, we have different attributes.

Parties Attribute

During transaction creation we use the parties attribute to determine the role of each customer in a transaction. There are four different roles: buyer, seller, broker and partner. It is important to set the customers to their correct role as it cannot be changed once the transaction has been started. Certain actions are only able to be performed be certain roles, such as accepting items.

The buyer in the transaction is the customer that is purchasing the items in the transaction. They are required to fund the transaction and accept the items after the inspection period.

The seller in the transaction is the customer that is providing the items in the transaction. They are required to ship the items to the buyer, and have their funds disbursed after the buyer accepts the items.

The broker in a transaction is the user that is setting up a transaction on behalf of other users. Brokers are able to set a broker commission, and able to set who pays this. If a broker is participating in a transaction, we also support the privacy attribute, which conceals information about the seller from the buyer and information about the buyer from the seller. This includes contact details and transaction amounts. This allows the broker to have a broker commission that is visible to one party, both parties or neither party.

Partners are similar to Brokers in a transaction, however approved partners are also able to perform actions on behalf of customers on a transaction. When a transaction is created on the Escrow API, the partner will automatically be set to the customer that makes the API call. There is no need to specify the party object for the partner.

Currently there is a minimum of one buyer and one seller, and a maximum of one buyer, one seller, one broker and one partner is supported in a transaction. However the API may support more in the future.

It is a requirement for the customer or partner creating the transaction to be a party in the transaction. The calling customer will automatically be added as the partner in a created transaction, however we will not automatically assign the buyer, seller or broker roles to any other party. For those roles, it needs to be set specifically.

Besides the role attribute on the party object, there is also the customer attribute. This is the email address of the customer, or simply me. The special value me is a shortcut value to refer to the current user that is making the request.

For more information on the party object, please refer to the reference documentation on the Party Object.

Currency Attribute

The currency attribute assigns which currency is being used for the transaction. Currently the only currencies that are supported are usd, aud, euro, and gbp. However, we may add more currencies in the future.

Description Attribute

This is the description for the transaction. Here you can describe what the transaction is for.

Items Attribute

Every transaction must have at least one item on it. Items can both be transferable items and non transferable items.

Transferable items refer to goods or services that the buyer is purchasing. These include:

Domain names
Motor Vehicles
Services
NFT
Others

Non transferable items refer to items in the transaction that facilitate the transfer of transferable items to the buyer.
Such items include:

Shipping fees
Broker fees
Partner feesX

Each item must contain at least one schedule object. This is how we determine the price of an item and who is paying for it. Currently the only item types that can have multiple schedules are milestone anddomain_name_holding.

Valid values for the item type are:

domain_name
domain_name_holding
others
milestone
motor_vehicle
broker_fee
partner_fee
shipping_fee

At the moment, the API only supports one type of transferable item type per transaction.

Each item can have a category field which gives classification for the type of item being sold.

The valid categories are based on the type of item as follows:

item_type	category
motor_vehicle	cars
others	watches
domain_name	domain_name
nft	nft
services	services

We highly recommend providing a category to your items, as doing so can result in faster processing of your transactions.

Fees Attribute

The fees attribute refers to the Cryptoexchange.com transaction fees. Examples of these fees include:

General escrow fee
Paypal deposit fee
Credit card deposit fee
Wire disbursement fee

Type Attribute

The valid types on the fee object are as follows:

cheque_disbursement
escrow
paypal_deposit
creditcard_deposit
wire_disbursement

Split Attribute

This attribute is only applicable to the fee type escrow and is only valid on transaction creation. This field is used to allow customers to determine who should pay the escrow fee. Valid values are decimal 0.5 (50% of the total) and 1 (100% of the total).

When creating a transaction it is not valid to pass an amount for the fee object. You must pass in the split attribute to the fee object instead. The split specified on each fee item in the list must add up to 1.0.

If no fee schedule is passed on transaction creation, by default the buyer will be set to pay 100% of the escrow type fee.

If a fee schedule is passed on transaction creation, the same fee schedule must be included on each item in the transaction.

Schedule Attribute

Each fee object must contain at least one schedule object. This determines who is paying for the fees. Currently the buyer must pay for the following fee types:

paypal_deposit
creditcard_deposit

And the seller must pay for the following fee types:

cheque_disbursement
wire_disbursement

For more information, have a look at the Schedule documentation.

Additional Attributes

The additional attributes field for each item contains both the image_url and merchant_url fields.

The image_url field specifies an image URL to be displayed on the Escrow Pay portal UX and any Cryptoexchange.com Transaction emails.

The merchant_url field specifies a URL to be shown on the partner dashboard transaction page view as a reference to the listing.

Schedule Objects

The schedule object is used for representing who is paying for an item or fee.

amount

This field is used for determining the price of items or fees. This is a decimal value.

due_date

In transactions with multiple payment schedules, such as Domain Name Holding or transactions with items delivered at multiple times, you specify the due_date. This field represents when Cryptoexchange.com expects a certain payment to be made, or delivery of an item to be made.

This field is required on schedules on domain name holding and milestone items. Setting this field on other item types is an invalid request and will result in an error.

payer_customer

This is the email address of the customer who will be paying for the item.

beneficiary_customer

This is the email address of the customer who will be receiving the funds. For transferable items this will always be the seller, and for broker fees it will be the broker. For escrow fees it will always be the value escrow.