Transactions

• View a transaction
• List transactions
• Create a transaction
• Update a transaction
• Delete a transaction

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.

{warning} 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.

{warning} 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 twp 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: SELLER,
    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: BUYER
        }
      ]
    }
  }) {
    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
  }
}

Delete a transaction

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

{danger} 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")
}