Initiate new transaction

This page details how the initiate transaction flow works. It allows you make a payer pay for a payee's item and initiate a transaction between the two. To use the flow it requires that payee is connected with Safepay Nordic and you have the SymblepayAccountId for the payee. It assumes that you already have credentials to successfully call Safepay Nordic 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 service, request your backend service to create a checkoutUrl using Safepay Nordic API.
• Redirect user to Safepay Nordic using secure checkoutUrl.
• User chooses payment method and transfers to Safepay Nordic Escrow account.
• Your backend receives notification with transaction id.
• Meanwhile user returns to your application (using redirect or switching apps) and sees the success screen.

Initiate flow

Checkout flow

curl https://api.safepaynordic.dk/v2/checkout/marketplace \
  -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

{
    "checkoutUrl": "https://api.safepaynordic.dk/v1/marketplace/connect/e3e5f328-4d00-46a7-ba42-5c285add6bbf",
    "transactionId": "295a2546-ee78-4ec4-9e0f-b49af13536b8"
}

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

After checkout

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

Return URL example

https://marketplace.dk/return-url"

After returning, verify the status of the transaction server-side.

Webhook for transaction changes

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

Webhook example

{
    "webhookId": "ed3325d8-b379-444a-9cc1-7d119efefbea",
    "eventName": "transaction.created",
    "eventDate": "2024-02-16T10:36:20+01:00",
    "referenceId": "your-reference-id",
    "transactionId": "616de408-5f8f-4ef3-ba28-6b4827145070",
    "payee": {
      "safepayAccountId": "616de408-5f8f-4ef3-ba28-6b4827145070",
      "referenceId": "your-reference-id",
    },
    "payer": {
      "safepayAccountId": "616de408-5f8f-4ef3-ba28-6b4827145070",
      "referenceId": "your-reference-id",
    }    
}

Possible eventNames are:

• transaction.created
• transaction.payment.paid
• transaction.payment.failed
• transaction.cancelled
• transaction.succeeded