Quick Start Guide


Before you start

Before starting ensure that you have completed the following:


Tokens

Tokens are used in place of personal/banking details. Once a token is generated it can be stored safely as part of a users profile for example.

Retrieving API owner tokens

Each organization registered contains a token ID.

{warning} The IDs are updated if the banking details are changed when editing your profile.

A list of organizations IDs are retrieved as follows:

Query:

query {
    apiProfile {
        organizations {
            name
            token
        }
    }
}

Response:

{
  "data": {
    "apiProfile": {
      "organizations": [
        {
          "name": "Company Name (Pty) Ltd",
          "token": "1LmSTMO37LClxXAQddVgMf"
        }
      ]
    }
  }
}

Creating a Token

For regular users a token must be generated before they can be added to a transaction.

A token can be created as follows:

{danger} The banking and organization details are optional however users cannot receive a payout without providing their banking details.

Query:

mutation tokenCreate($givenName: String, $familyName: String, $email: Email, $mobile: String, $idNumber: String, $idType: IdType, $idCountry: Country, $bank: UniversalBranchCode, $accountNumber: String, $accountType: BankAccountType, $organizationName: String, $organizationTradeName: String, $organizationType: OrganizationType, $organizationRegistrationNumber: String, $organizationTaxNumber: String) {
    tokenCreate(input: {
        user: {
            givenName: $givenName
            familyName: $familyName
            email: $email
            mobile: $mobile
            idNumber: $idNumber
            idType: $idType
            idCountry: $idCountry
        }
        organization: {
            name: $organizationName,
            tradeName: $organizationTradeName
            type: $organizationType
            registrationNumber: $organizationRegistrationNumber
            taxNumber: $organizationTaxNumber
        }
        bankAccount: {
            bank: $bank
            accountNumber: $accountNumber
            accountType: $accountType
        }
    }) {
        id
        name
        reference
        user {
            givenName
            familyName
            email
            mobile
            idNumber
        }
        organization {
            name
            tradeName
            type
            registration
            taxNumber
        }
    }
}

Response:

{
  "data": {
    "tokenCreate": {
      "data": [
        {
          "id": "2GgV4fTDkRzqkhrwhcdawV",
          "name": "Company Name (Pty) Ltd",
          "reference": "XMSNQ327",
          "user": {
            "givenName": "User",
            "familyName": "Name",
            "email": "user.name@example.net",
            "mobile": "+27831234567",
            "idNumber": "4206155253080"
          },
          "organization": {
            "name": "Company Name (Pty) Ltd",
            "tradeName": null,
            "type": "PRIVATE",
            "registration": "1234/012345/89",
            "taxNumber": null
          }
        }
      ]
    }
  }
}

Transactions

Querying

Listing All Transactions

You can retrieve a list of transactions using the transactions query.

The query allows you to receive a paginated list of all transactions.

{info} A full list of available fields can be found in the GraphQL Schema which can be viewed in the playground

{info} The paginatorInfo block has a number of helpful values to page through the list of transactions.

{warning} The speed of this query is heavily impacted by the amount of data requested. It is recommended you only retrieve the data that is required.

Query:

query transactions($first: Int, $page: Int) {
    transactions(first: $first, page: $page) {
        data {
            id
            title
            auxiliaryData
            parties {
                id
                role
                details {
                    user {
                        givenName
                        familyName
                        email
                    }
                }
            }
            allocations {
                id
                title
                description
                value
                state
                deliverBy
                inspectBy
            }
            deposits {
                id
                method
                value
                processed
                paymentLink
                redirects {
                    success
                    failure
                    cancel
                }
            }
        }
        paginatorInfo {
            count
            total
            lastItem
            perPage
            currentPage
            lastPage
            hasMorePages
        }
    }
}

Variables:

{info} The first and page allow you to query a specific part of the transaction list. First sets the number of results to return while page sets the group of transactions to return.

For example first: 10 and page: 3 will return 21st through to the 30th transaction in the list.

{
  "page": 1,
  "first": 10
}

Response:

{
  "data": {
    "transactions": {
      "data": [
        {
          "id": "dZchb2J69BxsK4ETzTCgy",
          "title": "Delivery Test 3",
          "parties": [
            {
              "id": "cw3Nsj7sxGZBZXz2p2c85",
              "role": "BUYER",
              "details": {
                "user": {
                  "givenName": "Jane",
                  "familyName": "Doe",
                  "email": "jane.doe@example.net"
                }
              }
            },
            {
              "id": "4dqu9TUJvs1w0WzoHk0eLl",
              "role": "SELLER",
              "details": {
                "user": {
                  "givenName": "John",
                  "familyName": "Doe",
                  "email": "john.doe@example.net"
                }
              }
            }
          ],
          "allocations": [
            {
              "id": "5gUfRG86M479wOB7o1wlB5",
              "title": "First",
              "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur pellentesque urna eu iaculis dignissim. Vestibulum feugiat nisi eget leo congue dictum. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Nulla dolor odio, luctus at sagittis eget, placerat rhoncus sapien. Nulla dapibus commodo mauris laoreet varius. Nam imperdiet metus mi, vitae sollicitudin sem gravida ut. Pellentesque luctus consectetur ante, sed tempor dui vestibulum in. Ut aliquam tincidunt lorem, non tristique ipsum aliquet et. Nulla mollis condimentum tortor, sit amet dapibus ante convallis ac. Vestibulum ac luctus nisi.",
              "value": 15000,
              "state": "CREATED",
              "deliverBy": null,
              "inspectBy": null
            }
          ],
          "deposits": [
            {
              "id": "4WnvKSRVqmXIeRr38tXT2w",
              "method": "OZOW",
              "value": 15300,
              "processed": false,
              "paymentLink": "https:\/\/pay.ozow.com\/d417c170-cb26-4b2c-bd8c-188e4c483804\/Secure",
              "redirects": null
            }
          ]
        }
      ],
      "paginatorInfo": {
        "count": 20,
        "total": 32,
        "lastItem": 20,
        "perPage": 20,
        "currentPage": 1,
        "lastPage": 2,
        "hasMorePages": true
      }
    }
  }
}

Retrieving a single Transaction

Querying a transaction is much like getting a list of transactions. However, you need to provide the transaction id.

Query:

query transactions($id: ID!) {
    transaction(id: $id) {
        id
        title
        auxiliaryData
        parties {
            id
            role
            details {
                user {
                    givenName
                    familyName
                    email
                }
            }
        }
        allocations {
            id
            title
            description
            value
            state
            deliverBy
            inspectBy
        }
        deposits {
            id
            method
            value
            processed
            paymentLink
            redirects {
                success
                failure
                cancel
            }
        }
    }
}

Variables:

{
  "id": "dZchb2J69BxsK4ETzTCgy"
}

Response:

{
  "transaction": {
    "data": [
      {
        "id": "dZchb2J69BxsK4ETzTCgy",
        "title": "Delivery Test 3",
        "parties": [
          {
            "id": "cw3Nsj7sxGZBZXz2p2c85",
            "role": "BUYER",
            "details": {
              "user": {
                "givenName": "Jane",
                "familyName": "Doe",
                "email": "jane.doe@example.net"
              }
            }
          },
          {
            "id": "4dqu9TUJvs1w0WzoHk0eLl",
            "role": "SELLER",
            "details": {
              "user": {
                "givenName": "John",
                "familyName": "Doe",
                "email": "john.doe@example.net"
              }
            }
          }
        ],
        "allocations": [
          {
            "id": "5gUfRG86M479wOB7o1wlB5",
            "title": "First",
            "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur pellentesque urna eu iaculis dignissim. Vestibulum feugiat nisi eget leo congue dictum. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Nulla dolor odio, luctus at sagittis eget, placerat rhoncus sapien. Nulla dapibus commodo mauris laoreet varius. Nam imperdiet metus mi, vitae sollicitudin sem gravida ut. Pellentesque luctus consectetur ante, sed tempor dui vestibulum in. Ut aliquam tincidunt lorem, non tristique ipsum aliquet et. Nulla mollis condimentum tortor, sit amet dapibus ante convallis ac. Vestibulum ac luctus nisi.",
            "value": 15000,
            "state": "CREATED",
            "deliverBy": null,
            "inspectBy": null
          }
        ],
        "deposits": [
          {
            "id": "4WnvKSRVqmXIeRr38tXT2w",
            "method": "OZOW",
            "value": 15300,
            "processed": false,
            "paymentLink": "https:\/\/pay.ozow.com\/d417c170-cb26-4b2c-bd8c-188e4c483804\/Secure",
            "redirects": null
          }
        ]
      }
    ]
  }
}

Creating a Transaction

Once you have tokens for each of the parties that you would like to add to the transaction. Thee transaction itself can be created.

The following creates a simple transaction between a buyer, seller and agent.

Query:

mutation transactionCreate($title: String!, $description: String!, $industry: Industry!, $workflow: TransactionWorkflow! $value: Float, $buyerToken: String, $sellerToken: String) {
    transactionCreate(input: {
        title: $title
        description: $description
        industry: $industry
        currency: ZAR
        feeAllocation: SELLER
        allocations: {
            create: [
                {
                    title: $title
                    description: $description
                    value: $value
                    daysToDeliver: 7
                    daysToInspect: 7
                }
            ]
        }
        parties: {
            create: [
                {
                    token: $buyerToken
                    role: BUYER
                }
                {
                    token: $sellerToken
                    role: SELLER
                }
                {
                    token: $agentToken
                    role: AGENT
                    fee: $agentFee
                    feeType: $agentFeeType
                    feeAllocation: $agentFeeAllocation
                }
            ]
        }
    }) {
        id
        createdAt
    }
}

Variables:

{
  "title": "Your Transaction Title",
  "description": "Some description goes here",
  "industry": "GENERAL_GOODS_SERVICES",
  "value": 10000,
  "buyerToken": "2XgpOMfNEEIdh7uu5tzQn8",
  "sellerToken": "3xN7R4ZnfOGqFG5r6E0Zbt",
  "agentToken": "4dqu9TUJvs1w0WzoHk0eLl",
  "agentFee": 2,
  "agentFeeType": "PERCENT",
  "feeAllocation": "SELLER"
}

Response:

{
  "id": "dZchb2J69BxsK4ETzTCgy",
  "createdAt": "2020-09-21 16:21:36"
}

Deposits

Once a transaction has been created the buyer needs to be prompted to deposit the funds. A payment link needs to be generated first.

The following generates a payment link using a credit card gateway. The buyer can then be directed to the link and complete the payment. They will be redirected back to either the success, failure or cancel urls.

Query:

mutation transactionDeposit($id: ID!, $method: DepositMethod!, $successUrl: String!, $failureUrl: String!, $cancelUrl: String!) {
    transactionDeposit(id: $id, method: $method, redirects: {success: $successUrl, failure: $failureUrl, cancel: $cancelUrl}) {
        id
        value
        processed
        paymentLink
        redirects {
            success
            failure
            cancel
        }
    }
}

Variables:

{
  "id": "3TAps9Uygc8Fn5MKvvzCYn",
  "method": "ECEN",
  "successUrl": "https://example.net/success",
  "failureUrl": "https://example.net/failure",
  "cancelUrl": "https://example.net/cancel"
}

Response:

{
  "data": {
    "transactionDeposit": {
      "id": "2ppjCwrQbuZvvwSWYdWRPD",
      "value": 10033.8,
      "processed": null,
      "paymentLink": "https:\/\/developer-api.tradesafe.dev\/api\/ecentric\/redirect\/2ppjCwrQbuZvvwSWYdWRPD",
      "redirects": {
        "success": "https:\/\/example.net\/success",
        "failure": "https:\/\/example.net\/failure",
        "cancel": "https:\/\/example.net\/cancel"
      }
    }
  }
}

Start Delivery

Once the funds have been received, and the transaction is in the FUNDS_RECEIVED state.

The allocation and transaction will be updated to the INITIATED state.

Query:

mutation allocationStartDelivery($id: ID!) {
    allocationStartDelivery(id: $id) {
        id
        state
    }
}

Variables:

{
  "id": "7Vf9ZUW4LyKxO3bsriociZ"
}

Response:

{
  "data": {
    "allocationStartDelivery": {
      "id": "7Vf9ZUW4LyKxO3bsriociZ",
      "state": "INITIATED"
    }
  }
}

Accept Delivery

Once the buyer has received the goods or service they can then accept the delivery.

{info} Once all allocations have been accepted, the transaction will transition to the FUNDS_RELEASED once the funds have been paid.

Query:

mutation allocationAcceptDelivery($id: ID!) {
    allocationStartDelivery(id: $id) {
        id
        state
    }
}

Variables:

{
  "id": "7Vf9ZUW4LyKxO3bsriociZ"
}

Response:

{
  "data": {
    "allocationStartDelivery": {
      "id": "7Vf9ZUW4LyKxO3bsriociZ",
      "state": "DELIVERED"
    }
  }
}

Callbacks

Everytime a transaction is updated a callback will be sent to the url provided when registering your application.

Response:

{
  "id": "3RbZ0f1PPS3yMPBIT9rqT5",
  "reference": "TGG40H29",
  "state": "CREATED",
  "balance": 0
}