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.
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:
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.
A full list of available fields can be found in the GraphQL Schema which can be viewed in the playground
The paginatorInfo block has a number of helpful values to page through the list of transactions.
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 redirects { success failure cancel } } } paginatorInfo { count total lastItem perPage currentPage lastPage hasMorePages } }}Variables:
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, "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: AGENT 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. The buyer can then be directed to the link and complete the payment. They will be redirected back to either the success, failure/cancel urls.
Mutation:
mutation checkoutLink($id: ID!) { checkoutLink(transactionId: $id)}Variables:
{ "id": "3TAps9Uygc8Fn5MKvvzCYn"}Response:
{ "data": { "checkoutLink": "https:\/\/pay-sandbox.tradesafe.dev\/checkout\/embed\/eyJpdiI6Im...FnIjoiIn0=" }}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.
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}