Transactions

View a Transaction

The transaction query is the is one of the most important queries as it provides all the information needed to interact with a transaction.

When viewing a transaction it is recommended to keep the query as small as possible to ensure you get a quick response from the API

Query

query transaction {
    transaction(id: "L6rWqEcUlm2gWfUvT05Pj") {
        id
        title
        createdAt
        parties {
            id
            name
            role
            details {
                user {
                    givenName
                    familyName
                    email
                }
            }
        }
    }
}

Result

{
    "data": {
        "transaction": {
            "id": "L6rWqEcUlm2gWfUvT05Pj",
            "title": "This is a test",
            "createdAt": "2021-01-15 12:50:54",
            "parties": [
                {
                    "id": "2eTA7VFEea1lzWxs5NuGx5",
                    "name": "Buyer's Name",
                    "role": "BUYER",
                    "details": {
                        "user": {
                            "givenName": "Buyer's",
                            "familyName": "Name",
                            "email": "buyer@example.net"
                        }
                    }
                },
                {
                    "id": "403vBLQI1X57cBWcWPNj7G",
                    "name": "Seller's Name",
                    "role": "SELLER",
                    "details": {
                        "user": {
                            "givenName": "Seller's",
                            "familyName": "Name",
                            "email": "seller@example.net"
                        }
                    }
                }
            ]
        }
    }
}

List Transactions

Transactions can be listed through the transactions query.

When listing transactions it is recommended to keep the query as small as possible to ensure you get a quick response from the API

query transactions {
    transactions {
        data {
            title
            description
            industry
            state
            createdAt
        }
    }
}

Create a Transaction

The transactionCreate mutation is used to create transactions on the API and requires that you have all the necessary data available before you start; for this reason we recommend that this mutation only be called at the beginning of your checkout process.

There are several parts to a transaction. They can be summarised as follows:

1. Transaction Information
2. Allocations
3. Parties (Users in a transaction)

Transaction Information

The basic information about a transaction includes the following:

1. Title - A title clearly identifying the transaction
2. Description - More information about the transaction. This could be an itemised product list or the terms of transaction.
3. Industry - Which industry the transaction is for.
4. Fee Allocation - Who will pay the escrow processing fee
5. Workflow - The type of workflow you want to use Standard (One payment), Milestone or Drawdown
6. Reference - A unique reference from your application

Allocations

Allocations are used to assign funds to a particular action. A simple example would be delivery of goods, or a service. A more complex example would be a project with multiple phases, and a portion of the funds assigned to each phase.

Parties

Parties are users or organizations that are associated with the transaction. Each party has a role assigned to them. A simple transaction requires two parties namely a buyer and seller, however you can add an agent and along with other beneficiaries.

One allocation

mutation transactionCreate {
    transactionCreate(input: {
        title: "Transaction Title",
        description: "Transaction Description",
        industry: GENERAL_GOODS_SERVICES,
        currency: ZAR,
        feeAllocation: SELLER,
        allocations: {
            create: [
                {
                    title: "Allocation Title",
                    description: "Allocation Description",
                    value: 10000.00,
                    daysToDeliver: 7,
                    daysToInspect: 7
                }
            ]
        },
        parties: {
            create: [
                {
                    token: "15Ndyzw4lUfWnTTeV0ggOY",
                    role: BUYER
                }, {
                    token: "1Mm0z59pN5g31BeOElntAw",
                    role: SELLER
                }
            ]
        }
    }) {
        id
        title
        createdAt
    }
}

Multiple allocations

mutation transactionCreate {
    transactionCreate(input: {
        title: "Transaction Title",
        description: "Transaction Description",
        industry: GENERAL_GOODS_SERVICES,
        currency: ZAR,
        feeAllocation: AGENT,
        workflow: MILESTONE,
        allocations: {
            create: [
                {
                    title: "First Allocation",
                    description: "First Allocation Description",
                    value: 5000.00,
                    daysToDeliver: 14,
                    daysToInspect: 7
                },
                {
                    title: "Second Allocation",
                    description: "Second Allocation Description",
                    value: 3000.00,
                    daysToDeliver: 7,
                    daysToInspect: 7
                },
                {
                    title: "Third Allocation",
                    description: "Third Allocation Description",
                    value: 2000.00,
                    daysToDeliver: 4,
                    daysToInspect: 7
                }
            ]
        },
        parties: {
            create: [
                {
                    token: "15Ndyzw4lUfWnTTeV0ggOY",
                    role: BUYER
                }, {
                    token: "1Mm0z59pN5g31BeOElntAw",
                    role: SELLER
                }, {
                    token: "67mdktsEUHjETgZ3i1cOiY",
                    role: AGENT,
                    fee: 10,
                    feeType: PERCENT,
                    feeAllocation: SELLER
                }
            ]
        }
    }) {
        id
        title
        createdAt
    }
}

Drawdowns

Creating a drawdown transaction only requires a single allocation. This allocation will be used as the pool of funds used for the drawdown process.

The key difference from a transaction with a single allocation is the workflow field which is set to DRAWDOWN.

mutation transactionCreate {
    transactionCreate(input: {
        title: "Transaction Title",
        description: "Transaction Description",
        industry: GENERAL_GOODS_SERVICES,
        currency: ZAR,
        feeAllocation: SELLER,
        workflow: DRAWDOWN,
        allocations: {
            create: [
                {
                    title: "Allocation Title",
                    description: "Allocation Description",
                    value: 10000.00,
                    daysToDeliver: 7,
                    daysToInspect: 7
                }
            ]
        },
        parties: {
            create: [
                {
                    token: "15Ndyzw4lUfWnTTeV0ggOY",
                    role: BUYER
                }, {
                    token: "1Mm0z59pN5g31BeOElntAw",
                    role: SELLER
                }
            ]
        }
    }) {
        id
        title
        createdAt
    }
}

Update a transaction

Updating a transaction works much like the createTransaction mutation. The key difference is that the keys for nested mutations (allocations and parties) reflect the action you want to achieve (create, update, delete)

mutation transactionUpdate {
    transactionUpdate(id: "66pkPDfpd2SuYEtv0dobdJ", input: {
        title: "Transaction Title",
        description: "Transaction Description",
        industry: GENERAL_GOODS_SERVICES,
        currency: ZAR,
        feeAllocation: SELLER,
        allocations: {
            update: [
                {
                    id: "6aEIgAOdrBYn5pTos3szr9"
                    title: "Allocation Title",
                    description: "Allocation Description",
                    value: 10000.00,
                    daysToDeliver: 7,
                    daysToInspect: 7
                }
            ]
        },
        parties: {
            update: [
                {
                    id: "71hp4o0a6rTMMvuG77XdJP"
                    token: "15Ndyzw4lUfWnTTeV0ggOY",
                    role: BUYER
                }
            ]
        }
    }) {
        id
        title
        createdAt
    }
}

Cancel or Refund a transaction

When calling transactionCancel the transaction will be cancelled and the funds will be refunded to the buyer if a deposit has been made.

Tip

The state of the transaction will change to CANCELLED if no deposit has been made, or REFUNDED if a deposit has occurred.

mutation transactionCancel {
    transactionCancel(id: "2O0Ub75OY1kjqvqlusZuBy", comment: "Reason for cancellation") {
       state
    }
}

Delete a transaction

If a transaction is still in the CREATED state is can be deleted using the transactionDelete mutation

Note

If a transaction has been sitting in the CREATED state for 3 weeks with no update it will be automatically deleted from our systems.

mutation transactionDelete {
    transactionDelete(id: "2O0Ub75OY1kjqvqlusZuBy")
}