Skip to main content

Connect with Safepay Nordic

This page details how the user connection flow works. It allows you to connect your users with Safepay Nordic so they can be part of a user-to-user trade. This flow is the same for websites and iOS and Android apps. 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 connect with Safepay Nordic in your application, request your backend services to create a connectUrl using Safepay Nordic API.
  • Re-direct user to Safepay Nordic Frontend using https uri.
  • User signs in with existing Safepay Nordic account or creates a new in Safepay Nordic Frontend
  • Your backend services receives notification with coupling between your reference id and Safepay Nordic Account Id.
  • Meanwhile user returns to your application (using re-direct or switching apps) and sees the success screen.

User Connection Flow

Initiate connect flow​

Initiate Flow
curl https://api.safepaynordic.dk/v2/connect \
  -X POST \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -H 'Content-Type: application/json'\
  -d '{
        "referenceId": "{USER_ID}",
        "returnUrl": "{RETURN_URL}",
        "allowPrivate": true,
        "allowBusiness": false
      }'
Response example
{
    "connectUrl": "https://mitsafepay.dk/l/o3a1f9c2/8e7d6c5b-2a14-4f0e-9b3d-1c2a7d3e8b10"
}

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

Optional parameters​

The connect endpoint accepts the following optional parameters to control the flow:

  • returnUrl: Where the user is redirected after the flow. If omitted, the flow ends on a Safepay Nordic exit page.
  • allowPrivate / allowBusiness: Restrict which account types may connect. allowBusiness is only honoured if your tenant allows business users.
  • skipUI: Skips the Safepay Nordic UI. When true, all UI/UX must be handled by you and all other skip properties are ignored.
  • skipPhoneNumber / skipEmail: Skip the phone-number or email verification step.
  • skipBankAccount: Skip the payout bank-account onboarding step (see Select Payout Account).
  • skipKYC / skipKYB: Skip the KYC (private) or KYB (business) verification step.

Missing user information, such as phone number or KYC/KYB, will trigger additional steps in the flow based on these skip properties.

Connect user flow was a success​

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

Return callback example
https://marketplace.dk/return-url

Translate your reference id to a Safepay Account Id​

Once connected, exchange your referenceId for the user's safepayAccountId using the connect lookup endpoint:

Get connect
curl https://api.safepaynordic.dk/v2/connect/{USER_ID} \
  -X GET \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -H 'Content-Type: application/json'
Response example
{
    "safepayAccountId": "f6c4a43f-682e-4559-b8d1-11a63afd134a",
    "connections": [
        {
            "referenceId": "your-user-id",
            "connected": "2026-01-01T12:00:00+01:00"
        }
    ]
}

Receive webhook​

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

Webhook example
{
    "eventName": "user.connected",
    "eventDate": "2024-02-16T10:36:20+01:00",
    "webhookId": "ed3325d8-b379-444a-9cc1-7d119efefbea",
    "safepayAccountId": "f6c4a43f-682e-4559-b8d1-11a63afd134a",
    "connections": [
        {
            "referenceId": "your-user-id",
            "connected": "2024-02-16T10:36:20+01:00"
        }
    ]
}