Creates a URL that onboards a user for selling: the user signs in or registers (with your identifier linked when you provide one), verifies a payout account (bank account, card or PayPal) and is handed back to your returnUrl. No order is placed; afterwards you place sell orders for the user through the API.

POST

/api/v2/sell/onboarding

Authorizations

• Client

Request Body ^required

object

locale

Display language as an IETF locale, case-insensitive (e.g. nl-nl, en-gb, de-at). The language must be one of nl, en, de, fr, es; the region is free-form. Omit to show the onboarding in English.

string

nullable

Example

nl-nl

identifier

Your own identifier for the user, used to link the onboarding to a BTC Direct account. Provide it here to skip the separate register-identifier call. Must be 36-255 characters. The identifier embedded in the returned onboardingUrl is not this value, so always use onboardingUrl exactly as returned.

string

nullable >= 36 characters <= 255 characters

Example

partner-unique-user-id-at-least-36-characters-long

returnUrl

required

URL the user is handed back to once a payout account is verified, typically a deep link into your app. Opened as-is.

string

nullable

Example

https://example.com/return

payoutMethods

The payout types you accept payouts on, as an allow-list of at least one. The user is only offered these (further limited to what your sell payment methods enable); when only one is left it is chosen for them. Omit the field to offer every enabled type; an empty list is refused. Ends up in the URL as one comma-separated payoutMethod parameter.

Array<string>

nullable >= 1 items

Allowed values: bankTransfer creditCard paypal

Example

[
  "bankTransfer",
  "paypal"
]

kycShareToken

Optional Sumsub KYC share token. When provided, the user’s existing KYC data is imported at registration, reducing verification steps.

string

nullable

Responses

200

Returns the onboarding URL

object

onboardingUrl

The URL to send the user to. Use it exactly as returned: do not modify it or read values out of it. Your identifier is included in a transformed form and cannot be read back.

string

returnUrl

string

partner

string

identifier

Your identifier for the user, as provided.

string

nullable

locale

string

nullable

payoutMethods

Array<string>

nullable

400

A list of possible errors for this endpoint.

object

code

required

string

Allowed values: ER047 ER053 ER099 ER102 ER308 ER331 ER340 ER367 ER417 ER800 ER801 ER802 ER803 ER805 ER806 ER999

message

required

string

solution

required

string

Example

{
  "errors": {
    "ER047": {
      "code": "ER047",
      "message": "Invalid return URL.",
      "solution": "Provide a valid return URL."
    },
    "ER053": {
      "code": "ER053",
      "message": "Missing identifier.",
      "solution": "Provide a valid identifier."
    },
    "ER099": {
      "code": "ER099",
      "message": "Invalid locale provided.",
      "solution": "Provide a valid locale."
    },
    "ER102": {
      "code": "ER102",
      "message": "User identifier length out of bounds.",
      "solution": "Provide a user identifier with a minimum of 36 characters and a maximum of 255."
    },
    "ER308": {
      "code": "ER308",
      "message": "Return URL should not be blank.",
      "solution": "Provide a valid Return URL."
    },
    "ER331": {
      "code": "ER331",
      "message": "Secret not set",
      "solution": "Please contact support for assistance."
    },
    "ER340": {
      "code": "ER340",
      "message": "Api Key not found.",
      "solution": "Please contact support for assistance."
    },
    "ER367": {
      "code": "ER367",
      "message": "KYC share token should not be blank.",
      "solution": "Provide a non-empty KYC share token or omit the field."
    },
    "ER417": {
      "code": "ER417",
      "message": "Invalid payout method.",
      "solution": "Use only bankTransfer, creditCard or paypal in payoutMethods, and at least one of them."
    },
    "ER800": {
      "code": "ER800",
      "message": "Authorization token is invalid.",
      "solution": "Provide a valid authorization token."
    },
    "ER801": {
      "code": "ER801",
      "message": "Authorization token has expired.",
      "solution": "Request a new authorization token."
    },
    "ER802": {
      "code": "ER802",
      "message": "Authorization token not found.",
      "solution": "Provide an authorization token."
    },
    "ER803": {
      "code": "ER803",
      "message": "Multiple authorization methods used.",
      "solution": "Use exactly one authorization method."
    },
    "ER805": {
      "code": "ER805",
      "message": "API key is invalid.",
      "solution": "Provide a valid API key."
    },
    "ER806": {
      "code": "ER806",
      "message": "API key not found.",
      "solution": "Provide an API key."
    },
    "ER999": {
      "code": "ER999",
      "message": "A general error has occurred. Please contact our support team.",
      "solution": "Contact our support team."
    }
  }
}