Skip to main content

Initiate new trade

This page details how the initiate trade flow works. It allows you make a payer pay for a payee's item and initiate a trade between the two. To use the flow it requires that payee is connected with symblepay and you have the SymblepayAccountId for the payee. It assumes that you already have credentials to successfully call Symblepay APIs and have subscribed to notifications using Webhooks API.

How it works​

Sunshine scenario is expected for the majority of the time.

  • When a user wants to buy an item on your marketplace, request your backend service to create a redirectUri using Symblepay API.
  • Re-direct user to Symblepay Frontend using https uri.
  • User chooses payment method and transfers to Symblepay Escrow account.
  • Your backend receives notification with trade id and state.
  • Meanwhile user returns to your application (using re-direct or switching apps) and sees the success screen.

Trade Flow

Initiate flow​

Initiate Flow
curl https://api.symblepay.io/v1/marketplace/trades/initiate \
  -X POST \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
        "title": "Adidas Campus 00s",
        "description": "Almost new Adidas Campus 00s. Used 3 times and still have the box and receipt.",
        "amount": 1200.5,
        "payerFee": 5.0,
        "payeeFee": 2.5,
        "payerMarketplaceUserId": "003dc3d2-dc30-4b37-a573-f664a03f5154",
        "payeeMarketplaceUserId": "82f700bd-5789-4623-95e7-0d34fde4720c",
        "referenceId": "bba3b9be-bcbc-4471-8454-acb6e733747281784a78-8b7f-4e49-ad4e-383417c970cf",
        "checkoutIdempotencyKey": "81784a78-8b7f-4e49-ad4e-383417c970cf",
        "shipping": {
          "price": 105.43,
          "expectedMaxWeight": 2,
          "paidBy": 0,
          "shippingProviderShopId": "918c0e9a-ed15-4603-a332-65c6851bc772"
        },
        "successUrl": "https://marketplace.dk/success-url",
        "cancelUrl": "https://marketplace.dk/cancel-url",
        "imageUrls": [ "image-url-1", "image-url-2" ],
        "appSwitch": {
          "appSwitchCallbackUri": "callback-uri",
          "operatingSystem": 0
        },
      }'
Response example
{
    "redirectUrl": "https://api.symblepay.io/v1/marketplace/connect/e3e5f328-4d00-46a7-ba42-5c285add6bbf",
    "tradeId": "295a2546-ee78-4ec4-9e0f-b49af13536b8"
}

Send your users to the redirectUrl in a browser or In-App browser on Android or iOS

Flow was a success​

Wait for the user to be redirected back to your successUrl.

Suceess callback example
https://marketplace.dk/success-url"

Flow was a cancelled​

Wait for the user to be redirected back to your cancelUrl.

Cancel callback example
https://marketplace.dk/cancel-url

Webhook for trade changes​

A webhook is also send to ensure you get the information.

Webhook example
{
    "id": "ed3325d8-b379-444a-9cc1-7d119efefbea",
    "referenceId": "616de408-5f8f-4ef3-ba28-6b4827145070",
    "eventName": "trade.updated",
    "eventDate": "2024-02-16T10:36:20+01:00",
    "payerMarketplaceUserId": "b0531f60-45b6-4eae-a409-eaa668cd56c0",
    "payeeMarketplaceUserId": "a3249659-78d0-4b2c-a054-4f7324895602",
    "tradeId": "014c7bae-9452-4130-8b1d-dc48baca5b77",
    "metadata": {
        "key": "value"
    }
}

Possible eventNames are:

  • trade.created
  • trade.cancelled
  • trade.succeeded
  • trade.shipment_label_created
  • trade.shipment_sent
  • trade.shipment_pickup_ready
  • trade.shipment_returned
  • trade.shipment_lost
  • trade.shipment_delivered
  • trade.condition_accepted
  • trade.condition_rejected
  • trade.return_condition_accepted
  • trade.return_condition_rejected
  • trade.return_shipment_label_created
  • trade.return_shipment_sent
  • trade.return_shipment_pickup_ready
  • trade.return_shipment_returned
  • trade.return_shipment_lost
  • trade.return_shipment_delivered