TradeSafe

https://docs.tradesafe.co.za/
Admin
TradeSafe is an escrow and payment processing platform that enables secure transactions between...
Tokens:29,869
Snippets:264
Trust Score:8.4
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start Delivery

Source: https://docs.tradesafe.co.za/api/allocations

Initiates the delivery process for an allocation. This can only be called when the transaction is in the `FUNDS_RECEIVED` or `INITIATED` states.

```APIDOC
## Start Delivery

### Description
The `allocationStartDelivery` mutation is used to initiate delivery. This can only be called when the transaction is in the `FUNDS_RECEIVED` or `INITIATED` states.

### Method
MUTATION

### Endpoint
`/graphql`

### Parameters
#### Request Body
- **id** (String) - Required - The ID of the allocation to start delivery for.

### Request Example
```json
{
  "mutation": "mutation allocationStartDelivery {\n    allocationStartDelivery(id: \"4RwHQ1bQsmA5v4tjf5o0m6\") {\n        id\n        state\n    }\n}"
}
```

### Response
#### Success Response (200)
- **id** (String) - The ID of the allocation.
- **state** (String) - The updated state of the allocation.

#### Response Example
```json
{
  "data": {
    "allocationStartDelivery": {
      "id": "4RwHQ1bQsmA5v4tjf5o0m6",
      "state": "DELIVERY_STARTED"
    }
  }
}
```
```

--------------------------------

### Upgrade Magento Setup

Source: https://docs.tradesafe.co.za/plugins/magento

Run this command to apply any necessary database updates and schema changes after enabling the TradeSafe module.

```bash
php bin/magento setup:upgrade
```

--------------------------------

### Enable TradeSafe Module

Source: https://docs.tradesafe.co.za/plugins/magento

After installing the extension, enable the TradeSafe Payment Gateway module using this Magento CLI command.

```bash
php bin/magento module:enable TradeSafe_PaymentGateway
```

--------------------------------

### Start Delivery

Source: https://docs.tradesafe.co.za/guides/quick-start

Initiates the delivery process for a transaction once funds have been received and the transaction state is FUNDS_RECEIVED. This updates the allocation and transaction to the INITIATED state.

```APIDOC
## POST /allocation/start-delivery

### Description
Initiates the delivery process for an allocation.

### Method
POST

### Endpoint
/allocation/start-delivery

### Parameters
#### Query Parameters
- **id** (ID!) - Required - The ID of the allocation to start delivery for.

### Request Example
```json
{
  "id": "7Vf9ZUW4LyKxO3bsriociZ"
}
```

### Response
#### Success Response (200)
- **id** (ID) - The ID of the allocation.
- **state** (String) - The new state of the allocation, expected to be 'INITIATED'.

#### Response Example
```json
{
  "data": {
    "allocationStartDelivery": {
      "id": "7Vf9ZUW4LyKxO3bsriociZ",
      "state": "INITIATED"
    }
  }
}
```
```

--------------------------------

### Deposit with Saved Card Error Example

Source: https://docs.tradesafe.co.za/api/deposits-cards

Example of an error response when attempting a deposit with a saved card. This indicates issues during card processing.

```json
{
    "errors": [
        {
            "message": "The transaction failed",
            "extensions": {
                "reason": "There was a problem processing the card",
                "errors": [],
                "category": "custom"
            },
            "locations": [
                {
                    "line": 1136,
                    "column": 2
                }
            ],
            "path": [
                "transactionDepositCard"
            ]
        }
    ],
    "data": {
        "transactionDepositCard": null
    }
}
```

--------------------------------

### Transaction Query Response

Source: https://docs.tradesafe.co.za/guides/quick-start

Example JSON response containing a list of transactions and pagination metadata.

```json
{
  "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
      }
    }
  }
}
```

--------------------------------

### Saved Cards Response Example

Source: https://docs.tradesafe.co.za/api/deposits-cards

Example JSON response when querying for saved cards. This shows the structure of the data returned, including card identifiers and masked details.

```json
{
    "data": {
        "cards": [
            {
                "id": "F24CFD9E-D459-486B-9E9C-772DA9DE7540",
                "name": "Test Card",
                "number": "557678******2300",
                "month": 2,
                "year": 2024
            }
        ]
    }
}
```

--------------------------------

### Install TradeSafe Extension via Composer

Source: https://docs.tradesafe.co.za/plugins/magento

Use this command to add the TradeSafe Payment Gateway extension to your Magento project using Composer. Replace `<version>` with the desired version number.

```bash
composer require tradesafe/magento2:<version>
```

--------------------------------

### Start Allocation Delivery

Source: https://docs.tradesafe.co.za/api/allocations

Initiate the delivery process for an allocation. This mutation can only be called when the associated transaction is in the 'FUNDS_RECEIVED' or 'INITIATED' states.

```graphql
mutation allocationStartDelivery {
    allocationStartDelivery(id: "4RwHQ1bQsmA5v4tjf5o0m6") {
        id
        state
    }
}
```

--------------------------------

### Example Transaction Callback Data

Source: https://docs.tradesafe.co.za/api/callbacks

This JSON object represents a typical callback received from the API when a buyer makes a deposit, indicating the transaction state and related details.

```json
{
    "url": "https://example.net/your/callback/url",
    "data": {
        "id": "4apICtLE2JPu1NfoWURmL",
        "reference": "TKYB6PZ3",
        "state": "FUNDS_RECEIVED",
        "balance": "0.0000",
        "updated_at": "2021-06-14 09:25:03",
        "allocations": [
            {
                "id": "4RwHQ1bQsmA5v4tjf5o0m6",
                "state": "CREATED",
                "updated_at": "2021-06-14 09:24:08"
            }
        ]
    }
}
```

--------------------------------

### Card Authorization Link Response

Source: https://docs.tradesafe.co.za/api/deposits-cards

Example response containing a payment link generated by `checkoutCardAuthorize`. This link allows users to pre-authorize their card.

```json
{
    "data": {
        "checkoutCardAuthorize": "https://pay.tradesafe.co.za/A1b2C3d4E5"
    }
}
```

--------------------------------

### Token Card Authorization Link Response

Source: https://docs.tradesafe.co.za/api/deposits-cards

Example response containing a payment link generated by `tokenCardAuthorize`. This link is used for pre-authorizing a card without an existing transaction.

```json
{
    "data": {
        "tokenCardAuthorize": "https://pay.tradesafe.co.za/A1b2C3d4E5"
    }
}
```

--------------------------------

### List Allocations for a Transaction

Source: https://docs.tradesafe.co.za/api/allocations

Query all allocations linked to a specific transaction using its ID. This is useful for getting a comprehensive overview of how funds are distributed for a given transaction.

```graphql
query transaction {
    transaction(id: "4XTwDsioZZZFeOKKr5blO") {
        id
        allocations {
            id
            value
            state
            calculation {
                value
                payout
                fee
                refund
            }
        }
    }
}
```

--------------------------------

### Transaction Update Callback

Source: https://docs.tradesafe.co.za/guides/quick-start

A callback is sent to the registered application URL every time a transaction is updated. This is an example of a transaction update callback payload.

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

--------------------------------

### Create Transaction Mutation

Source: https://docs.tradesafe.co.za/api/transactions

Use this mutation to create a new transaction. It requires detailed input including title, description, industry, currency, fee allocation, allocations, and parties. This mutation is best called at the start of a checkout process.

```graphql
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
    }
}
```

--------------------------------

### Get current amendment

Source: https://docs.tradesafe.co.za/api/amendments

Fetches the active amendment for a given allocation.

```graphql
query allocation {
  allocation(id: "4RwHQ1bQsmA5v4tjf5o0m6") {
    currentAmendment {
      id
      state
      value
      units
      unitCost
      accepted
    }
  }
}
```

--------------------------------

### Get current amendment

Source: https://docs.tradesafe.co.za/api/amendments

Retrieves the currently active amendment for a specific allocation.

```APIDOC
## QUERY allocation

### Description
Retrieves the current amendment details for a specific allocation.

### Method
POST (GraphQL)

### Parameters
#### Query Parameters
- **id** (String) - Required - The allocation ID.

### Request Example
query allocation { allocation(id: "4RwHQ1bQsmA5v4tjf5o0m6") { currentAmendment { id state value units unitCost accepted } } }
```

--------------------------------

### Create a token

Source: https://docs.tradesafe.co.za/api/tokens

Creates a new token with user, organization, bank account, and setting details. Banking details are immutable once set.

```graphql
mutation tokenCreate {
    tokenCreate(input: {
        user: {
            givenName: "First Name",
            familyName: "Last Name",
            email: "email@example.net",
            mobile: "+27000000000",
        }
        organization: {
            name: "Org Name"
            tradeName: "Trading As name"
            type: PRIVATE
            registrationNumber: "0000/000000/00"
            taxNumber: "000000000"
        }
        bankAccount: {
            accountNumber: "0000000000",
            accountType: CHEQUE,
            bank: SBSA
        }
        settings: {
            payout: {
                interval: IMMEDIATE,
                refund: WALLET,
            }
        }
    }) {
        id
        name
    }
}
```

--------------------------------

### Select Payment Gateways

Source: https://docs.tradesafe.co.za/api/deposits

Customize available payment options by specifying `paymentMethods` in the `checkoutLink` query. Accepted methods include `EFT`, `INSTANT_EFT`, `CARD`, `SNAP`, and `PJN`.

```graphql
mutation checkoutLink {
    checkoutLink(transactionId: "dZchb2J69BxsK4ETzTCgy", paymentMethods: [EFT, INSTANT_EFT, CARD, SNAP, PJN])
}
```

--------------------------------

### Creating a Token

Source: https://docs.tradesafe.co.za/guides/quick-start

This mutation allows you to create a new token for regular users. Tokens are required before users can be added to a transaction. Banking and organization details are optional but necessary for payouts.

```APIDOC
## POST /api/token/create

### Description
Creates a new token for a user, optionally including their organization and banking details.

### Method
POST

### Endpoint
/api/token/create

### Parameters
#### Query Parameters
None

#### Request Body
- **input** (object) - The input object for token creation.
  - **user** (object) - User details.
    - **givenName** (string) - Optional. User's first name.
    - **familyName** (string) - Optional. User's last name.
    - **email** (Email) - Optional. User's email address.
    - **mobile** (string) - Optional. User's mobile number.
    - **idNumber** (string) - Optional. User's identification number.
    - **idType** (IdType) - Optional. Type of user's identification.
    - **idCountry** (Country) - Optional. Country of user's identification.
  - **organization** (object) - Organization details.
    - **name** (string) - Optional. Organization's name.
    - **tradeName** (string) - Optional. Organization's trade name.
    - **type** (OrganizationType) - Optional. Type of organization.
    - **registrationNumber** (string) - Optional. Organization's registration number.
    - **taxNumber** (string) - Optional. Organization's tax number.
  - **bankAccount** (object) - Bank account details.
    - **bank** (UniversalBranchCode) - Optional. Bank's universal branch code.
    - **accountNumber** (string) - Optional. Bank account number.
    - **accountType** (BankAccountType) - Optional. Type of bank account.

### Request Example
```json
{
  "input": {
    "user": {
      "givenName": "User",
      "familyName": "Name",
      "email": "user.name@example.net",
      "mobile": "+27831234567",
      "idNumber": "4206155253080",
      "idType": "ID",
      "idCountry": "ZA"
    },
    "organization": {
      "name": "Company Name (Pty) Ltd",
      "tradeName": "Example Trade Name",
      "type": "PRIVATE",
      "registrationNumber": "1234/012345/89",
      "taxNumber": "9876543210"
    },
    "bankAccount": {
      "bank": "ABC123456",
      "accountNumber": "1234567890",
      "accountType": "CHEQUE"
    }
  }
}
```

### Response
#### Success Response (200)
- **tokenCreate** (object) - The result of the token creation mutation.
  - **id** (string) - The unique identifier for the created token.
  - **name** (string) - The name associated with the token (often the organization name).
  - **reference** (string) - A reference code for the token.
  - **user** (object) - Details of the user associated with the token.
    - **givenName** (string) - User's first name.
    - **familyName** (string) - User's last name.
    - **email** (Email) - User's email address.
    - **mobile** (string) - User's mobile number.
    - **idNumber** (string) - User's identification number.
  - **organization** (object) - Details of the organization associated with the token.
    - **name** (string) - Organization's name.
    - **tradeName** (string) - Organization's trade name.
    - **type** (OrganizationType) - Type of organization.
    - **registration** (string) - Organization's registration number.
    - **taxNumber** (string) - Organization's tax number.

#### Response Example
```json
{
  "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
          }
        }
      ]
    }
  }
}
```
```

--------------------------------

### POST /tokenDeposit

Source: https://docs.tradesafe.co.za/api/tokens

Generate a deposit link for a token wallet.

```APIDOC
## POST /tokenDeposit

### Description
Generates a URL where users can deposit funds into their wallet using various payment methods.

### Method
POST (GraphQL Mutation)

### Parameters
#### Request Body
- **id** (String) - Required - The token wallet ID.
- **embed** (Boolean) - Optional - Whether to embed the deposit page.
- **paymentMethods** (Array) - Optional - List of allowed payment methods (e.g., CARD, EFT).
- **minutes** (Int) - Optional - Timeout for the deposit page in minutes.

### Request Example
mutation deposit {
    tokenDeposit(id: "abc..xyz", embed: true, paymentMethods: [CARD, EFT], minutes: 10) {
        id
        url
        expiresAt
    }
}
```

--------------------------------

### Create a Token

Source: https://docs.tradesafe.co.za/api/tokens

Creates a new user token. All user details are required. Organization, banking, and settings are optional.

```APIDOC
## Create a Token

### Description
Creates a new user token. All user details are required. Organization information, banking details, and settings are optional and can be added later. Note: Banking details can only be added once and cannot be updated; to change them, the token must be recreated.

### Method
MUTATION

### Endpoint
N/A (GraphQL Mutation)

### Parameters
#### Request Body
- **input** (object) - Required - Input object for creating the token.
  - **user** (object) - Required - User details.
    - **givenName** (string) - Required - User's first name.
    - **familyName** (string) - Required - User's last name.
    - **email** (string) - Required - User's email address.
    - **mobile** (string) - Required - User's mobile number.
  - **organization** (object) - Optional - Organization details.
    - **name** (string) - Organization's name.
    - **tradeName** (string) - Organization's trade name.
    - **type** (string) - Type of organization (e.g., PRIVATE).
    - **registrationNumber** (string) - Organization's registration number.
    - **taxNumber** (string) - Organization's tax number.
  - **bankAccount** (object) - Optional - Bank account details.
    - **accountNumber** (string) - Required if bankAccount is provided - Bank account number.
    - **accountType** (string) - Required if bankAccount is provided - Type of account (e.g., CHEQUE).
    - **bank** (string) - Required if bankAccount is provided - Bank name (e.g., SBSA).
  - **settings** (object) - Optional - Payment settings.
    - **payout** (object) - Payout settings.
      - **interval** (string) - Payout interval (e.g., IMMEDIATE).
      - **refund** (string) - Refund method (e.g., WALLET).

### Request Example
```graphql
mutation tokenCreate {
    tokenCreate(input: {
        user: {
            givenName: "First Name",
            familyName: "Last Name",
            email: "email@example.net",
            mobile: "+27000000000",
        },
        organization: {
            name: "Org Name",
            tradeName: "Trading As name",
            type: PRIVATE,
            registrationNumber: "0000/000000/00",
            taxNumber: "000000000"
        },
        bankAccount: {
            accountNumber: "0000000000",
            accountType: CHEQUE,
            bank: SBSA
        },
        settings: {
            payout: {
                interval: IMMEDIATE,
                refund: WALLET,
            }
        }
    }) {
        id
        name
    }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the newly created token.
- **name** (string) - The name of the created token.

#### Response Example
```json
{
  "data": {
    "tokenCreate": {
      "id": "tok_new123",
      "name": "New User Token"
    }
  }
}
```
```

--------------------------------

### POST /graphql (List Transactions)

Source: https://docs.tradesafe.co.za/api/transactions

Lists transactions available in the system.

```APIDOC
## POST /graphql

### Description
Lists transactions. It is recommended to keep the query fields minimal for faster response times.

### Method
POST

### Endpoint
/graphql

### Request Example
query transactions {
    transactions {
        data {
            title
            description
            industry
            state
            createdAt
        }
    }
}
```

--------------------------------

### Create Deposit Using Wallet Funds

Source: https://docs.tradesafe.co.za/api/deposits

This mutation allows creating a deposit for a transaction using funds from the buyer's wallet. Partial payments are not supported.

```APIDOC
## Create Deposit Using Wallet Funds

### Description
This mutation allows creating a deposit for a transaction using funds from the buyer's wallet. Partial payments are not supported.

### Method
MUTATION

### Endpoint
N/A (GraphQL Mutation)

### Parameters
#### Query Parameters
- **id** (ID!) - Required - The ID of the transaction for which to create a deposit.

### Request Example
```graphql
mutation transactionDepositWallet($id: ID!) {
    transactionDepositWallet(id: $id) {
        id
        state
    }
}
```

### Response
#### Success Response (200)
- **data.transactionDepositWallet.id** (ID) - The ID of the created deposit.
- **data.transactionDepositWallet.state** (String) - The initial state of the deposit (e.g., "FUNDS_RECEIVED").

#### Response Example
```json
{
    "data": {
        "transactionDepositWallet": {
            "id": "403vBLQI1X57cBWcWPNj7G",
            "state": "FUNDS_RECEIVED"
        }
    }
}
```
```

--------------------------------

### Get Saved Card Information

Source: https://docs.tradesafe.co.za/api/deposits-cards

Retrieve a list of saved cards associated with a token. This query provides card details such as ID, name, and masked number.

```APIDOC
## GET /cards

### Description
Retrieves a list of saved cards for a given token.

### Method
GET

### Endpoint
/cards

#### Query Parameters
- **tokenId** (string) - Required - The token ID associated with the saved cards.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the saved card.
- **name** (string) - The name of the cardholder.
- **number** (string) - The masked card number.
- **month** (integer) - The expiry month of the card.
- **year** (integer) - The expiry year of the card.

### Response Example
```json
{
    "data": {
        "cards": [
            {
                "id": "F24CFD9E-D459-486B-9E9C-772DA9DE7540",
                "name": "Test Card",
                "number": "557678******2300",
                "month": 2,
                "year": 2024
            }
        ]
    }
}
```
```

--------------------------------

### Create Wallet Deposit Mutation

Source: https://docs.tradesafe.co.za/api/deposits

GraphQL mutation to initiate a deposit using funds from a buyer's wallet.

```graphql
mutation transactionDepositWallet($id: ID!) {
    transactionDepositWallet(id: $id) {
        id
        state
    }
}
```

```json
{
    "data": {
        "transactionDepositWallet": {
            "id": "403vBLQI1X57cBWcWPNj7G",
            "state": "FUNDS_RECEIVED"
        }
    }
}
```

--------------------------------

### POST /graphql (Create Transaction)

Source: https://docs.tradesafe.co.za/guides/quick-start

Creates a new transaction between a buyer, seller, and optionally an agent.

```APIDOC
## POST /graphql

### Description
Creates a new transaction using provided party tokens and transaction details.

### Method
POST

### Endpoint
/graphql

### Request Body
- **title** (String) - Required - Title of the transaction.
- **description** (String) - Required - Description of the transaction.
- **industry** (Industry) - Required - Industry category.
- **value** (Float) - Optional - Transaction value.
- **buyerToken** (String) - Optional - Token for the buyer.
- **sellerToken** (String) - Optional - Token for the seller.

### Request Example
{
  "title": "Your Transaction Title",
  "description": "Some description goes here",
  "industry": "GENERAL_GOODS_SERVICES",
  "value": 10000,
  "buyerToken": "2XgpOMfNEEIdh7uu5tzQn8",
  "sellerToken": "3xN7R4ZnfOGqFG5r6E0Zbt"
}

### Response
#### Success Response (200)
- **id** (String) - The ID of the created transaction.
- **createdAt** (String) - Timestamp of creation.

#### Response Example
{
  "id": "dZchb2J69BxsK4ETzTCgy",
  "createdAt": "2020-09-21 16:21:36"
}
```

--------------------------------

### Create a Token

Source: https://docs.tradesafe.co.za/guides/quick-start

This GraphQL mutation is used to create a new token for regular users. Banking and organization details are optional, but required for payouts.

```graphql
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
        }
    }
}
```

```json
{
  "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
          }
        }
      ]
    }
  }
}
```

--------------------------------

### POST /graphql (Create Transaction)

Source: https://docs.tradesafe.co.za/api/transactions

Creates a new transaction including transaction information, allocations, and parties.

```APIDOC
## POST /graphql

### Description
Creates a new transaction. This mutation requires transaction information, fund allocations, and associated parties (users).

### Method
POST

### Endpoint
/graphql

### Request Body
- **input** (Object) - Required - The transaction creation input containing title, description, industry, currency, feeAllocation, allocations, and parties.

### Request Example
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
    }
}
```

--------------------------------

### Flush Magento Cache

Source: https://docs.tradesafe.co.za/plugins/magento

Execute this command to clear the Magento cache and ensure the new module is recognized and active.

```bash
php bin/magento cache:flush
```

--------------------------------

### Initiate Deposit with Saved Card

Source: https://docs.tradesafe.co.za/api/deposits-cards

Use the `transactionDepositCard` mutation to create a deposit request using a previously saved card. This bypasses the need for user interaction on the payment page.

```graphql
mutation transactionDepositCard {
    transactionDepositCard(id: "2iDaQZwUZz3GNTKLpNe1Gj", cardId: "F24CFD9E-D459-486B-9E9C-772DA9DE7540") {
        id
    }
}
```

--------------------------------

### Generate OAuth Token using cURL

Source: https://docs.tradesafe.co.za/api/authentication

Use this cURL command to send a POST request to the token endpoint with your client credentials. Ensure you replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual credentials.

```bash
curl --request POST \
  --url 'https://auth.tradesafe.co.za/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET
```

--------------------------------

### List Tokens

Source: https://docs.tradesafe.co.za/api/tokens

Retrieves a list of tokens created by your organization. A default token is generated during signup.

```APIDOC
## List Tokens

### Description
Retrieves a list of tokens that have been created. By default, your organization already has a token generated as part of the signup process.

### Method
QUERY

### Endpoint
N/A (GraphQL Query)

### Parameters
None

### Request Example
```graphql
query tokens {
    tokens {
        data {
            id
            name
            reference
            user {
                givenName
                familyName
                email
                mobile
            }
            organization {
                name
                tradeName
                type
                registration
                taxNumber
            }
        }
    }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the list of tokens.
  - **id** (string) - Unique identifier for the token.
  - **name** (string) - Name of the token.
  - **reference** (string) - Reference associated with the token.
  - **user** (object) - User details.
    - **givenName** (string) - User's first name.
    - **familyName** (string) - User's last name.
    - **email** (string) - User's email address.
    - **mobile** (string) - User's mobile number.
  - **organization** (object) - Organization details.
    - **name** (string) - Organization's name.
    - **tradeName** (string) - Organization's trade name.
    - **type** (string) - Type of organization (e.g., PRIVATE).
    - **registration** (string) - Organization's registration number.
    - **taxNumber** (string) - Organization's tax number.

#### Response Example
```json
{
  "data": {
    "tokens": {
      "data": [
        {
          "id": "tok_12345",
          "name": "User Token 1",
          "reference": "REF001",
          "user": {
            "givenName": "John",
            "familyName": "Doe",
            "email": "john.doe@example.com",
            "mobile": "+27000000001"
          },
          "organization": {
            "name": "Example Corp",
            "tradeName": "Example Trading",
            "type": "PRIVATE",
            "registration": "2023/123456/07",
            "taxNumber": "1234567890"
          }
        }
      ]
    }
  }
}
```
```

--------------------------------

### Initiate Delivery

Source: https://docs.tradesafe.co.za/guides/quick-start

Initiate the delivery process for an allocation once funds have been received and the transaction state is FUNDS_RECEIVED. This mutation updates the allocation and transaction to the INITIATED state.

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

```json
{
  "id": "7Vf9ZUW4LyKxO3bsriociZ"
}
```

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

--------------------------------

### Generate Checkout Link

Source: https://docs.tradesafe.co.za/api/deposits

Use the `checkoutLink` query to generate a URL for redirecting users to the hosted payment page. The generated URL is valid for 15 minutes.

```graphql
mutation checkoutLink {
    checkoutLink(transactionId: "dZchb2J69BxsK4ETzTCgy")
}
```

--------------------------------

### Accept Delivery

Source: https://docs.tradesafe.co.za/api/allocations

Marks an allocation as accepted, initiating payout to the seller. Cannot be used if `allocationCompleteDelivery` has already been called.

```APIDOC
## Accept Delivery

### Description
When an allocation is ready to be paid out, the `allocationAcceptDelivery` mutation should be called. This will trigger a payout to the seller, and a refund if the allocation has been amended. Once all allocations are accepted, payouts to 3rd parties such as agents and beneficiaries will be made. You cannot use `allocationAcceptDelivery` if you have already called `allocationCompleteDelivery`.

### Method
MUTATION

### Endpoint
`/graphql`

### Parameters
#### Request Body
- **id** (String) - Required - The ID of the allocation to accept.

### Request Example
```json
{
  "mutation": "mutation allocationAcceptDelivery {\n    allocationAcceptDelivery(id: \"4RwHQ1bQsmA5v4tjf5o0m6\") {\n        id\n        state\n    }\n}"
}
```

### Response
#### Success Response (200)
- **id** (String) - The ID of the allocation.
- **state** (String) - The updated state of the allocation.

#### Response Example
```json
{
  "data": {
    "allocationAcceptDelivery": {
      "id": "4RwHQ1bQsmA5v4tjf5o0m6",
      "state": "ACCEPTED"
    }
  }
}
```
```

--------------------------------

### Create a new transaction

Source: https://docs.tradesafe.co.za/guides/quick-start

Creates a transaction between a buyer, seller, and agent. Requires party tokens and transaction details.

```graphql
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
    }
}
```

```json
{
  "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"
}
```

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

--------------------------------

### List tokens

Source: https://docs.tradesafe.co.za/api/tokens

Retrieves a list of tokens created by the organization.

```graphql
query tokens {
    tokens {
        data {
            id
            name
            reference
            user {
                givenName
                familyName
                email
                mobile
            }
            organization {
                name
                tradeName
                type
                registration
                taxNumber
            }
        }
    }
}
```

--------------------------------

### Request Card Authorization

Source: https://docs.tradesafe.co.za/api/deposits-cards

Use the `checkoutCardAuthorize` mutation to reserve funds on a card without immediate deduction. A payment link is generated for user pre-authorization.

```graphql
mutation transactionDepositCard {
    checkoutCardAuthorize(id: "L6rWqEcUlm2gWfUvT05Pj")
}
```

--------------------------------

### Accept Delivery

Source: https://docs.tradesafe.co.za/guides/quick-start

Allows the buyer to accept the delivery of goods or services. Once all allocations are accepted, the transaction state transitions to FUNDS_RELEASED.

```APIDOC
## POST /allocation/accept-delivery

### Description
Allows the buyer to accept the delivery of goods or services.

### Method
POST

### Endpoint
/allocation/accept-delivery

### Parameters
#### Query Parameters
- **id** (ID!) - Required - The ID of the allocation to accept delivery for.

### Request Example
```json
{
  "id": "7Vf9ZUW4LyKxO3bsriociZ"
}
```

### Response
#### Success Response (200)
- **id** (ID) - The ID of the allocation.
- **state** (String) - The new state of the allocation, expected to be 'DELIVERED'.

#### Response Example
```json
{
  "data": {
    "allocationStartDelivery": {
      "id": "7Vf9ZUW4LyKxO3bsriociZ",
      "state": "DELIVERED"
    }
  }
}
```
```

--------------------------------

### Request a Deposit Using a Saved Card

Source: https://docs.tradesafe.co.za/api/deposits-cards

Initiates a deposit using a previously saved card. This mutation bypasses the need for user interaction and directly processes the payment.

```APIDOC
## POST /transactionDepositCard

### Description
Requests a deposit using a saved card. The payment is initiated immediately, and the transaction is updated upon success.

### Method
POST

### Endpoint
/transactionDepositCard

#### Request Body
- **id** (string) - Required - The transaction ID.
- **cardId** (string) - Required - The ID of the saved card to use for the deposit.

### Request Example
```json
{
    "transactionDepositCard": {
        "id": "2iDaQZwUZz3GNTKLpNe1Gj",
        "cardId": "F24CFD9E-D459-486B-9E9C-772DA9DE7540"
    }
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the initiated transaction.

#### Error Example
```json
{
    "errors": [
        {
            "message": "The transaction failed",
            "extensions": {
                "reason": "There was a problem processing the card",
                "errors": [],
                "category": "custom"
            },
            "locations": [
                {
                    "line": 1136,
                    "column": 2
                }
            ],
            "path": [
                "transactionDepositCard"
            ]
        }
    ],
    "data": {
        "transactionDepositCard": null
    }
}
```
```

--------------------------------

### POST /oauth/token

Source: https://docs.tradesafe.co.za/api/authentication

Generates an OAuth 2.0 access token using client credentials.

```APIDOC
## POST https://auth.tradesafe.co.za/oauth/token

### Description
Generates an access token using the client credentials grant flow. This token is required for subsequent API requests.

### Method
POST

### Endpoint
https://auth.tradesafe.co.za/oauth/token

### Request Body
- **grant_type** (string) - Required - Must be set to 'client_credentials'
- **client_id** (string) - Required - Your application's Client ID
- **client_secret** (string) - Required - Your application's Client Secret

### Request Example
curl --request POST \
  --url 'https://auth.tradesafe.co.za/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET

### Response
#### Success Response (200)
- **access_token** (string) - The generated token for authorization
- **token_type** (string) - The type of token (e.g., bearer)
- **expires_in** (integer) - Token expiration time in seconds
- **refresh_token** (string) - Refresh token if applicable

#### Response Example
{
  "access_token":"MTQ...jI3",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":""
}
```

--------------------------------

### POST /graphql (transactions query)

Source: https://docs.tradesafe.co.za/guides/quick-start

Retrieves a paginated list of transactions. Use the 'first' and 'page' variables to control the result set size and offset.

```APIDOC
## POST /graphql

### Description
Retrieves a paginated list of all transactions. The query supports pagination via the 'first' and 'page' arguments.

### Method
POST

### Endpoint
/graphql

### Parameters
#### Query Parameters
- **first** (Int) - Optional - The number of results to return.
- **page** (Int) - Optional - The page number to return.

### Request Example
{
  "query": "query transactions($first: Int, $page: Int) { transactions(first: $first, page: $page) { data { id title } paginatorInfo { count total } } }",
  "variables": {
    "page": 1,
    "first": 10
  }
}

### Response
#### Success Response (200)
- **data** (Object) - The transaction list and pagination metadata.

#### Response Example
{
  "data": {
    "transactions": {
      "data": [
        {
          "id": "dZchb2J69BxsK4ETzTCgy",
          "title": "Delivery Test 3"
        }
      ],
      "paginatorInfo": {
        "count": 20,
        "total": 32,
        "currentPage": 1
      }
    }
  }
}
```

--------------------------------

### Initiate a drawdown request

Source: https://docs.tradesafe.co.za/api/drawdowns

Triggers the request process for a previously created drawdown.

```graphql
mutation drawdownRequest {
  drawdownRequest(id: "5Mbe7xDUoUdryvN4HNjhdm") {
    state
  }
}
```
Tokens:
Raw