Create onboarding link - Yativo

curl -X POST 'https://api.yativo.com/api/v1/card-checkout/customers/4f0c1e1a-8d2b-4c7e-9b1a-3e5f6a7b8c9d/onboarding' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 0c4f9e1d-2a7b-4e3c-8d6f-5b1a9c2e7f40' \
  -H 'Content-Type: application/json' \
  -d '{ "return_url": "https://app.example.com/done", "refresh_url": "https://app.example.com/link-expired" }'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "customer_id": "<string>",
    "endorsement_status": "<string>",
    "onboarding_url": "<string>",
    "expires_at": "2023-11-07T05:31:56Z"
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

POST

/

card-checkout

/

customers

/

{customer_id}

/

onboarding

curl -X POST 'https://api.yativo.com/api/v1/card-checkout/customers/4f0c1e1a-8d2b-4c7e-9b1a-3e5f6a7b8c9d/onboarding' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 0c4f9e1d-2a7b-4e3c-8d6f-5b1a9c2e7f40' \
  -H 'Content-Type: application/json' \
  -d '{ "return_url": "https://app.example.com/done", "refresh_url": "https://app.example.com/link-expired" }'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "customer_id": "<string>",
    "endorsement_status": "<string>",
    "onboarding_url": "<string>",
    "expires_at": "2023-11-07T05:31:56Z"
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

The link is valid for 2 hours. return_url is the Back to app link. refresh_url is where the customer lands after the link expires. See Get a fresh onboarding link.

curl -X POST 'https://api.yativo.com/api/v1/card-checkout/customers/4f0c1e1a-8d2b-4c7e-9b1a-3e5f6a7b8c9d/onboarding' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 0c4f9e1d-2a7b-4e3c-8d6f-5b1a9c2e7f40' \
  -H 'Content-Type: application/json' \
  -d '{ "return_url": "https://app.example.com/done", "refresh_url": "https://app.example.com/link-expired" }'

Authorizations

X-Api-Key

string

header

required

Your API key (yativo_pk_...) from Developers → API Keys. Send together with X-Api-Secret.

X-Api-Secret

string

header

required

Your API secret (yativo_sk_...), shown once when the key is created.

Headers

Idempotency-Key

string

required

A unique string per request to ensure idempotent processing.

Path Parameters

customer_id

string

required

Body

application/json

return_url

string<uri>

HTTPS Back to app link on the page.

Example:

"https://app.example.com/done"

refresh_url

string<uri>

HTTPS URL the customer lands on after the link expires.

Example:

"https://app.example.com/link-expired"

Response

Onboarding link

status

string

Example:

"success"

status_code

integer

Example:

200

message

string

Example:

"Request successful"

data

object

Show child attributes