Create a transaction

Creating transactions with the Trustcrow API is straight forward. Consider a simple transaction between myself and a seller, where I am buying 3 bags of cements for NGN500,000.

Create a new transaction

POST {{api_url}}/v1/transactions

Headers

Name	Type	Description
Accepts	string	application/json
Authorization	string	your Trustcrow API keys with which you authorize customers.

200: OK transaction created successfully

{
    "status": true,
    "message": "Transaction created successfully",
    "data": {
        "title": "Bag of cement",
        "description": "Purchase of 3 bags of cements",
        "category": "GOODS",
        "sub_category": "Food/beverage/agriculture",
        "transaction_contract_url": "",
        "status": "RECIPIENT_APPROVED_AWAITING_FUNDING",
        "transaction_originator": "BUYER",
        "buyer_id": "524c35c9-ef73-4a4d-a4ab-97146f3cff95",
        "seller_id": "eeae27bc-3e12-47f4-a6cb-fceaa3013629",
        "source": "api",
        "clientId": "dd2f3541-9047-46e1-b117-6ca8584ea0bd",
        "created_by": "369ea20c-212b-4b2a-9f87-31c7b11dec58",
        "milestones": [
            {
                "title": "Purchase of 3 bags of cements",
                "description": "Purchase of 3 bags of cements",
                "amount": 500000,
                "position_in_transaction": 1,
                "due_date_type": "DEADLINE_DATE",
                "due_date": "2023-12-30T00:00:00.000Z",
                "commission_payer": "SELLER_100",
                "inspection_duration": 2,
                "extensions": [
                    {
                        "title": "First extension",
                        "number_of_days": 1,
                        "milestone_id": "4cc0a406-ad97-4aa6-9f71-bfca4404f1a5",
                        "extension_start_date": null,
                        "extension_end_date": null,
                        "id": "bf1b36f2-bb46-4ec6-95ca-1c9b0e4d3ccb",
                        "has_been_activated": false,
                        "created_at": "2023-12-26T10:02:35.691Z",
                        "updated_at": "2023-12-26T10:02:35.691Z"
                    }
                ],
                "milestone_escrow": {
                    "balance": 0,
                    "id": "8991b718-bade-4119-a4b1-e6bec59cd3b2",
                    "created_at": "2023-12-26T10:02:35.691Z",
                    "updated_at": "2023-12-26T10:02:35.691Z"
                },
                "milestone_fee": 16250,
                "transaction_id": "2a3799a7-4dc2-4081-94eb-770bc6048a48",
                "milestone_escrow_id": "8991b718-bade-4119-a4b1-e6bec59cd3b2",
                "delivery_rejection_reason": null,
                "execution_timeline": null,
                "discount_code": null,
                "inspection_end_date": null,
                "return_deadline_date": null,
                "current_extension_index": null,
                "id": "4cc0a406-ad97-4aa6-9f71-bfca4404f1a5",
                "is_milestone_funded": false,
                "is_delivered": false,
                "is_completed": false,
                "is_delivery_rejected": false,
                "is_return_proof_sent": false,
                "is_return_approved": false,
                "is_return_rejected": false,
                "status": "PENDING",
                "rate_used": 1,
                "created_at": "2023-12-26T10:02:35.691Z",
                "updated_at": "2023-12-26T10:02:35.691Z"
            }
        ],
        "transaction_amount": 500000,
        "on_last_milestone": true,
        "total_amount_funded": 0,
        "total_amount_refunded": 0,
        "total_amount_disbursed": 0,
        "current_milestone_id": null,
        "job_id": null,
        "decline_reason": null,
        "is_completed": false,
        "has_buyer_rated": false,
        "has_seller_rated": false,
        "discount_code": null,
        "declined_at": null,
        "approved_at": null,
        "updated_by": null,
        "date_canceled": null,
        "id": "2a3799a7-4dc2-4081-94eb-770bc6048a48",
        "created_at": "2023-12-26T10:02:35.691Z",
        "updated_at": "2023-12-26T10:02:35.691Z"
    }
}

As an example, you can a make a post request to the endpoint above and pass in the raw json data below to create an escrow transaction.

{
    "title": "Bag of cement",
    "description": "Purchase of 3 bags of cements",
    "category": "GOODS",
    "sub_category": "Food/beverage/agriculture",
    "buyer_id": "369ea20c-212b-4b2a-9f87-31c7b11dec58",
    "seller_id": "7c4e5b33-eb74-41fd-8f07-230cfaeb2439",
    "contract_url": "Alvin_Eze_transaction_contract_1699981762479.png",
    "milestones": [
        {
            "amount" : 500000,
            "title": "Purchase of 3 bags of cements",
            "description": "Purchase of 3 bags of cements",
            "due_date": "12-30-2023",
            "inspection_duration": 2,
            "extensions": [
                {
                    "title": "First extension",
                    "number_of_days": 1
                }
            ]
        }
    ]
}

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

During transaction creation we use the parties attribute to determine the role of each customer in a transaction. There are two different roles: buyer and seller. 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 by 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.

Note

The current model of transactions supports two participants: one buyer and one seller. However the API may support more roles in the future.