Payment Onboarding Link

This API reference provides information on how to generate and retrieve payment onboarding links for businesses to enable payouts and start receiving payments to their bank account.

The PaymentOnboardingLink model

Once generated, businesses need to visit the Payment Onboarding Link to set up their payment processes. During this visit, they can provide essential payout details, including information about their bank, enabling a seamless integration for receiving payments.

Properties

Name
id
Type
string
Description
Unique identifier for the payment onboarding link.
Name
url
Type
string
Description
The URL to redirect the business to after they have completed the onboarding process.
Name
return_url
Type
string
Description
The URL to redirect after the business has completed the onboarding process.
Name
refresh_url
Type
string
Description
The URL the user will be redirected to if the account link is expired, has been previously-visited, or is otherwise invalid. The URL you specify should attempt to generate a new onboarding link with the same parameters used to create the original account link, then redirect the user to the new account link’s URL so they can continue with Onboarding. If a new link cannot be generated or the redirect fails you should display a useful error to the user.
Name
business
Type
object
Description
The business associated with the payment onboarding link.

GETapi/v2/payment-onboarding-links

List all payment onboarding links

This endpoint allows you to retrieve a paginated list of all your payment onboarding links.

Parameters

Name
limit
Type
integer
Description
A limit on the number of onboarding links to be returned on a single page.
Name
page
Type
integer
Description
Page number (for pagination).

Request

GET

api/v2/payment-onboarding-links

curl --request GET \
  --get "https://payments.your-domain.com/api/v2/payment-onboarding-links" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "data": [
    {
      "id": "9988df6b-a4ef-4678-b039-06a8a8337ccf",
      "url": "http://payments.your-domain.com/public/onboarding/9988df6b-a4ef-4678-b039-06a8a8337ccf?
      signature=0e3e3bf17128d83fbf6676aa9c4b916e4364179b651682f319e5a638220d73bf",
      "return_url": "http://payments.your-domain.com/return",
      "refresh_url": "http://payments.your-domain.com/dashboard",
    },
    {
      "id": "9988de81-f5f3-476b-af77-0a0cfae3ded8",
      "url": "http://payments.your-domain.com/public/onboarding/9988de81-f5f3-476b-af77-0a0cfae3ded8?
      signature=2d8b35ec511bb059dd532d9fa7bce80f9f9fed9dbb6040e55aa9b003292f3438",
      "return_url": "http://payments.your-domain.com/return",
      "refresh_url": "http://payments.your-domain.com/dashboard"
    }
  ]
}

POSTapi/v2/payment-onboarding-links

Create a payment onboarding link

This endpoint allows you to create a new payment onboarding link.

Parameters

Name
return_url
Type
string
Description
The URL to redirect after the business has completed the onboarding process.

Optional Parameters

Name
refresh_url
Type
string
Description
The URL the user will be redirected to if the account link is expired, has been previously-visited, or is otherwise invalid. The URL you specify should attempt to generate a new onboarding link with the same parameters used to create the original account link, then redirect the user to the new account link’s URL so they can continue with Onboarding. If a new link cannot be generated or the redirect fails you should display a useful error to the user.

Request

POST

api/v2/payment-onboarding-links

curl --request POST \
  "https://payments.your-domain.com/api/v2/payment-onboarding-links" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
  --data "{
    \"return_url\": \"http://payments.your-domain.com/dashboard\",
    \"refresh_url\": \"http://payments.your-domain.com/refresh\",
  }"

Response

{
  "data": {
    "id": "9988df6b-a4ef-4678-b039-06a8a8337ccf",
    "url": "http://payments.your-domain.com/public/onboarding/9988df6b-a4ef-4678-b039-06a8a8337ccf?
    signature=cf673747acb059a6357bd8ad4cc4ffb49f6b23344624ec36cbe4f64f5bad9fb5",
    "return_url": "http://payments.your-domain.com/dashboard",
    "refresh_url": "http://payments.your-domain.com/refresh",
    "business": {
      "id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "name": "XYZ Business",
      "website": null,
      "phone": null,
      "email": "john@xyz.com",
      "logo_url": null,
      "contact_first_name": "John",
      "contact_last_name": "Doe",
      "payouts_enabled": false,
      "business_type": "company",
      "created_at": 1683292509,
      "timezone": "America/New_York",
      "underwriting_status": {
        "bnpl": "PENDING",
        "factoring": "PENDING"
      },
    }
  }
}

GETapi/v2/onboarding-links/{id}

Retrieve an onboarding link

This endpoint allows you to retrieve an onboarding link.

Parameters

Name
id
Type
string
Description
ID of the onboarding link.

Request

GET

api/v2/payment-onboarding-links/{id}

curl --request GET \
  --get "https://payments.your-domain.com/api/v2/payment-onboarding-links/9988df6b-a4ef-4678-b039-06a8a8337ccf" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "data": {
    "id": "9988df6b-a4ef-4678-b039-06a8a8337ccf",
    "url": "http://payments.your-domain.com/public/onboarding/9988df6b-a4ef-4678-b039-06a8a8337ccf?
    signature=cf673747acb059a6357bd8ad4cc4ffb49f6b23344624ec36cbe4f64f5bad9fb5",
    "return_url": "http://payments.your-domain.com/dashboard",
    "refresh_url": "http://payments.your-domain.com/refresh",
  }
}

DELETEapi/v2/payment-onboarding-links/{id}

Delete an onboarding link

This endpoint allows you to delete a specific onboarding link.

Parameters

Name
id
Type
string
Description
The ID of the onboarding link.

Request

DELETE

api/v2/payment-onboarding-links/{id}

curl --request DELETE \
  "https://payments.your-domain.com/api/v2/payment-onboarding-links/9988df6b-a4ef-4678-b039-06a8a8337ccf" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "id": "9988df6b-a4ef-4678-b039-06a8a8337ccf",
  "object": "PaymentOnboardingLink",
  "deleted": true
}