Deposits

To test card and PayJustNow payments you can use the details provided on the test cards page

Hosted Payment Page

To use the hosted you need to call the checkoutLink query. This will generate a link to redirect your users to.

Once the user has completed an action they will be redirected to the success or failure urls you provided when configuring your application.

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

Response

The url changes between Development/SIT and Production and is only valid for 15 minutes from point of creation and should not be cached or altered.

{
    "data": {
        "checkoutLink": "https:\/\/pay-sandbox.tradesafe.dev\/checkout\/eyJpdiI6Im...FnIjoiIn0="
    }
}

Payment Gateway Selection

While the list of available payment gateways can be controlled in the application settings it can also be set at an api level. This allows the payment options to be dynamically configured e.g. allow only specific payment options for some products.

The selection of payment gateways can be customised based on custom criteria by specifying the paymentMethods with the request. This is passed as an array and can contain any of the following EFT, INSTANT_EFT, CARD, SNAP and PJN methods.

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

Payment Thresholds

When making a payment different gateways are subject to different thresholds and may be hidden if the deposit amount exceeds the threshold.

EFT: No limit

Instant EFT: R50 - R 2 000 000

Card: R50 - R 25 000

SnapScan: R50 - R 25 000

PayJustNow: R5000 - R 100 000

Redirects

When using redirect urls additional information is now passed as part of the redirect in the form of query parameters.

Success

Parameters

status: Result of payment

method: Method of payment used

transactionId: ID of the transaction

reference: Custom ref set during transaction creation

https://example.net/redirect?status=success&method=eft&transactionId=dZchb2J69BxsK4ETzTCgy&reference=custom-ref-ABCXYZ

Failure

Parameters

status: Result of payment

reason: Reason for the failed payment

transactionId: ID of the transaction

reference: Custom ref set during transaction creation

https://example.net/redirect?status=failure&reason=error&transactionId=dZchb2J69BxsK4ETzTCgy&reference=custom-ref-ABCXYZ

Cancelled

Parameters

status: Result of payment

reason: Reason for the failed payment

transactionId: ID of the transaction

reference: Custom ref set during transaction creation

https://example.net/redirect?status=failure&reason=canceled&transactionId=dZchb2J69BxsK4ETzTCgy&reference=custom-ref-ABCXYZ

Embedding the payment page

Embedding is a relatively new feature and we welcome any feedback to help improve this feature.

The payment page can also be embedded in your application. This can be done by adding the embed option in the request.

mutation checkoutLink {
    checkoutLink(transactionId: "dZchb2J69BxsK4ETzTCgy", embed: true)
}

Response

{
    "data": {
        "checkoutLink": "https:\/\/pay-sandbox.tradesafe.dev\/checkout\/eyJpdiI6Im...FnIjoiIn0="
    }
}

Notifications

When using the embed page in a frame the page will call parent.postMessage for success, failure and cancelled results.

Your app will require a listener to capture the statues.

The origin url will change between development/sandbox and production.

window.addEventListener('message', (e: any) => {
  if (e.origin === 'https://pay-sandbox.tradesafe.dev' && e.data.type === 'tradesafePaymentResponse') {
    // Proccess response
  }
})

The following information is sent with each response is as follows:

Success

{
  message: 'Payment successful'
  status: 'success'
  reference: 'custom-ref-ABCXYZ' // Transaction or custom ref set during transaction creation
  transactionId: 'dZchb2J69BxsK4ETzTCgy' // ID of the transaction been paid
  method: 'eft' // The method of payment used
}

Failure

{
  message: 'Payment failed'
  status: 'error'
  reference: 'custom-ref-ABCXYZ' // Transaction or custom ref set during transaction creation
  transactionId: 'dZchb2J69BxsK4ETzTCgy' // ID of the transaction been paid
}

Cancelled

{
  message: 'Payment cancelled by user'
  status: 'canceled'
  reference: 'custom-ref-ABCXYZ' // Transaction or custom ref set during transaction creation
  transactionId: 'dZchb2J69BxsK4ETzTCgy' // ID of the transaction been paid
}

Using funds from a Wallet

If a token has a sufficient balance, the funds can be used to pay for a transaction, the deposit will not be processed otherwise.

At this time partial payments are not supported however this is on the roadmap for 2023/2024.

You can check the available balance of token by querying the token directly.

Create a deposit using funds from the buyers wallet

Query

mutation transactionDeposit($id: ID!) {
    transactionDeposit(id: $id, method: WALLET) {
        id
        processed
    }
}

Result

{
    "data": {
        "transactionDeposit": {
            "id": "403vBLQI1X57cBWcWPNj7G",
            "processed": false
        }
    }
}

After the deposit is created a deposit object is returned. The initial processing status will be false while TradeSafe checks the buyers wallet and allocates the funds to the transaction.

Once the funds are allocated a callback is sent with a FUNDS_RECEIVED state.

The deposit can be checked by querying the transaction.

Query

query transaction($id: ID!) {
    transaction(id: $id) {
        state
        deposits {
            id
            method
            processed
        }
    }
}

Response

{
  "data": {
    "transaction": {
      "state": "FUNDS_RECEIVED",
      "deposits": [
        {
          "id": "2rMd8VGV8oge3tAWZ5FOjk",
          "method": "WALLET",
          "processed": true
        }
      ]
    }
  }
}