Safepay API V2 (v2)

Connect flow.

Generates a ConnectUrl where the user can be validated and connected to Safepay.

Missing user information, such as phone number or KYC/KYB this will trigger addtional steps in the flow, based on 'Skip' properties.

After the flow the user will be redirected to the ReturnUrl if supplied, otherwise the flow will end on a exit page.

The user should be redirected to the ConnectUrl to start the flow.

Gets information from the connect flow based on 'ReferenceId'.

This should be used to translate a 'ReferenceId' into a 'SafepayAccountId'.

Creates a new guest user and a connection to Safepay.

NOTICE: This feature is not available for all customers.

Deletes the connection to Safepay.

NOTICE: If there is no connection to Safepay, then the user won't be able to part of a transaction.

This endpoint should not be used unless there is a very specifc purpose.

Create document for signing

List documents

Get document

Sign document.

Generates a unique URL where the user can sign the document. If supplied the user will be redirect to ReturnUrl after signature flow.

Download document.

Returns a URL where the document can be downloaded.

If the document is signed, the URL links to the signed document, otherwise it links to the original uploaded document.

Delete document.

Notice: This will also delete uploaded documents including signed versions.

List users

Get user

List banks.

Lists the banks available for bank account onboarding

List bank accounts connected to user

Initialize bank account onboarding.

This will generate a URL where the user will be validated and able to select bank accounts for the supplied BankId. If ReturnUrl is supplied, the user will be returned after bank account validation.

The user should be redirected to the returned URL.

Results for bank account onboarding.

This should be called this after the user has returned from bank account initialize. The result will include the bank accounts selected by the user.

Use the BankAccountId to add given bank account to the user via /add endpoint.

Notice: This is tempoary data, the results will only be available for a short time period.

Add bank account.

Use the 'BankAccountId' from GET /users/{safepayAccountId}/bank-accounts/initialize to add the specific bank account.

Notice: First bank account added to Safepay Account will be marked as default.

Set bank account as default.

Default bank account will be used for payout.

Delete bank account.

This will remove the bank account from the user.

Notice: There must be at least one bank account connected.

Returns a paginated list of the authenticated tenant's transactions, ordered by creation date (newest first).

Use 'skip' and 'take' to page through results and 'search'/'referenceId' to filter. The 'count' field reports the total number of matches, ignoring pagination.

Creates a 'Marketplace' transaction and initializes a new checkout flow.

At least one of 'payeeId' or 'payeeReferenceId' must be supplied to identify the payee. The 'amount' must cover the sum of the fees and any split payouts. Supply a 'uniquenessKey' to make creation idempotent.

Creates an 'Auto' (vehicle) transaction and initializes a new checkout flow.

Supply vehicle details via 'autoInformation'. Enabling 'autoInformation.billOfSale' or 'autoInformation.debt' requires the corresponding module to be enabled for the tenant. The 'amount' must cover the sum of the fees and any split payouts. Supply a 'uniquenessKey' to make creation idempotent.

Returns the full details of a single transaction owned by the authenticated tenant, including parties, fees, payments and (for Auto transactions) vehicle, bill of sale and debt information.

Delete a transaction by 'transactionId'.

This is only allowed for transactions without payments. Look at 'Cancel transaction' to cancel transaction with payments.

Cancel a transaction on behalf of Safepay Account.

You must supply a reason for the cancel request.

Payments will be returned/refunded to Payer.

Succeeded transactions can't be cancelled.

Succeed a transaction by 'transactionId'.

The transaction will be marked as succeeded and payouts defined in transaction will be scheduled for payout.

Cancelled transactions can't be processed for payout.

Updates modifiable transaction properties: the expected completion date and (for Auto transactions) the vehicle retail amount.

Reimburses the payer of a transaction by the specified amount.

The payer will be identified from the transaction and reimbursed for the given amount.

Adds debt information to a transaction including documentation, amount, FIK code, and bank account details.

Only available for Auto transactions. Maximum file size: 10 MB. Accepted file types: PDF, JPG, JPEG, PNG, GIF, BMP, WEBP.

Returns a temporary URL to download the debt document associated with a transaction. The URL is valid for 5 minutes.

Add or update the bill of sale for an auto transaction.

Two modes are supported (checked in order):

• Document: Upload a PDF file directly (max 10 MB)
• Auto-generate bill of sale from transaction data if 'Document' is null

Only available for Auto transactions.

Allows changes to the transaction amount.

The amount must be equal or higher than the sum of costs for payee and/or split-payouts.

Changes are not allowed after an payment has been authorized.

For Auto transactions: Changes to amount will generate a new bill of sale.

Add a Payee to the transaction. This is not allowed if a Payee is already added.

Add a Payer to the transaction. This is not allowed if a Payer is already added.

Creates a new payment and attaches it to a transaction by 'transactionId'

The user should be redirected to the PaymentUrl to start a payment flow

Generates a new payment link for 'paymentId'

This endpoint can generate direct links to PSD2 and VippsMobilepay payment methods.

If no payment method is supplied, the user will be presented with UI for payment selection.

The user should be redirected to the PaymentUrl to start a payment flow

List webhook examples

Examples of all possible webhooks including payloads.