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 transaction. 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 webhooks.

How it works​

  • When a user wants to connect with Safepay Nordic in your application, your backend creates a connectUrl using the Safepay Nordic API.
  • You redirect the user to the connectUrl.
  • The user signs in with an existing Safepay Nordic account or creates a new one.
  • Your backend receives a user.connected webhook linking your referenceId to the user's safepayAccountId.
  • Meanwhile, the user returns to your application (by redirect or by switching apps) and sees your success screen.

Initiate connect flow​

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

Send your users to the connectUrl in a browser or an in-app browser on Android or iOS.

If the referenceId is already connected, the request fails with 400 Bad Request and the title Already connected. Use the lookup to get the existing safepayAccountId instead.

Parameters​

All parameters are optional:

  • referenceId: Your own id for the user. Strongly recommended, so the lookup and webhook tell you which of your users connected. If omitted, Safepay Nordic picks the reference itself, typically the user's safepayAccountId.
  • 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 defaults to your tenant's setting and is always false if your tenant doesn't allow 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. Contact Safepay Nordic before using this option.
  • skipPhoneNumber / skipEmail: Skip the phone-number or email verification step.
  • skipBankAccount: Skip the payout bank-account onboarding step (see Add bank account).
  • skipKYC / skipKYB: Skip the KYC (private) or KYB (business) verification step.

The skip properties default to false. Missing user information, such as phone number or KYC/KYB, triggers additional steps in the flow unless the matching skip property is true.

Complete the connection​

Receive webhook​

When the user is connected, Safepay Nordic sends a user.connected webhook. Treat this as the confirmation that the connection succeeded.

Webhook example
{
    "eventName": "user.connected",
    "eventDate": "2026-01-01T11:00:00Z",
    "webhookId": "ed3325d8-b379-444a-9cc1-7d119efefbea",
    "safepayAccountId": "f6c4a43f-682e-4559-b8d1-11a63afd134a",
    "connections": [
        {
            "referenceId": "your-user-id",
            "connected": "2026-01-01T11:00:00Z"
        }
    ]
}

Handle the return​

If you supplied a returnUrl, the user is redirected there when the flow ends.

When the user was connected, the safepayAccountId is appended as a query parameter. The connection is stored before the redirect, so the lookup succeeds right away:

Return example
https://marketplace.dk/return-url?safepayAccountId=f6c4a43f-682e-4559-b8d1-11a63afd134a

If the flow ended in an error, the user can return to your returnUrl without the safepayAccountId parameter.

The query parameter passes through the user's browser, so don't trust it on its own: confirm the connection with the webhook or the lookup before relying on it. The user may also never return, for example if they close the in-app browser, so don't depend on the redirect to complete the connection on your side.

Look up the Safepay Account Id​

You can exchange your referenceId for the user's safepayAccountId at any time:

Get connect
curl https://sandbox-api.safepaynordic.dk/v2/connect/{referenceId} \
  -H 'Authorization: Bearer {API_TOKEN}'
Response example
{
    "safepayAccountId": "f6c4a43f-682e-4559-b8d1-11a63afd134a",
    "connections": [
        {
            "referenceId": "your-user-id",
            "connected": "2026-01-01T11:00:00Z"
        }
    ]
}

The endpoint returns 404 Not Found if the referenceId isn't connected (yet).