Partner checkout redirects

Approved partners can send HTTPS redirect URLs when Scribeless checkout should return a customer to the partner application. Billing setup and recipient checkout use different request fields.

Billing setup redirects

Send billingRedirectUrl when the customer needs to add a payment method for invoice billing and should return to your app after hosted setup checkout. The URL must use HTTPS and be no longer than 500 characters.

You can provide billingRedirectUrl when provisioning a customer team:

curl --request POST 'https://platform.scribeless.co/api/partner/teams' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_PARTNER_API_KEY' \
  --data '{
    "email": "ada@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "companyName": "Example Co",
    "billingRedirectUrl": "https://partner.example.com/scribeless/billing-return"
  }'

You can also provide it when refreshing account status with the customer-team API key:

curl --request GET 'https://platform.scribeless.co/api/account/status?billingRedirectUrl=https%3A%2F%2Fpartner.example.com%2Fscribeless%2Fbilling-return' \
  --header 'X-API-Key: CUSTOMER_TEAM_API_KEY'

When billing setup is required, Scribeless returns a partner checkout URL:

{
  "billingSetupUrl": "https://platform.scribeless.co/partner-checkout?sessionId=CHECKOUT_SESSION_SECRET"
}

Send the customer to billingSetupUrl. Checkout URLs include a session secret, so do not log them publicly or expose them outside the customer handoff.

After hosted setup checkout completes, Scribeless redirects to billingRedirectUrl and appends checkout result parameters.

Successful setup redirects include status=payment_succeeded:

https://partner.example.com/scribeless/billing-return?status=payment_succeeded

Failed or incomplete setup redirects include status=payment_failed. They may also include a reason parameter:

https://partner.example.com/scribeless/billing-return?status=payment_failed&reason=checkout_not_fulfilled

Recipient checkout redirects

Send redirectUrl when your integration needs Scribeless to send the customer back to your app after hosted checkout for one-time campaign recipients.

POST https://platform.scribeless.co/api/recipients/checkout

Use the customer-team API key returned by POST /api/partner/teams, not the partner account API key.

curl --request POST 'https://platform.scribeless.co/api/recipients/checkout' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: CUSTOMER_TEAM_API_KEY' \
  --data '{
    "campaignId": "CAMPAIGN_ID",
    "redirectUrl": "https://partner.example.com/scribeless/campaign-return"
  }'

When payment setup or payment recovery is required, Scribeless returns a partner checkout URL:

{
  "status": "checkout_required",
  "campaignId": "CAMPAIGN_ID",
  "checkoutUrl": "https://platform.scribeless.co/partner-checkout?sessionId=CHECKOUT_SESSION_SECRET"
}

If automatic invoice payment succeeds without hosted checkout, Scribeless returns:

{
  "status": "payment_succeeded",
  "campaignId": "CAMPAIGN_ID",
  "invoiceUrl": "https://invoice.stripe.com/i/..."
}

After hosted checkout completes, Scribeless redirects to redirectUrl and appends checkout result parameters.

Successful payment redirects include status=payment_succeeded and the campaign ID:

https://partner.example.com/scribeless/campaign-return?status=payment_succeeded&campaignId=CAMPAIGN_ID

Failed or incomplete payment redirects include status=payment_failed. They may also include a reason parameter:

https://partner.example.com/scribeless/campaign-return?status=payment_failed&campaignId=CAMPAIGN_ID&reason=checkout_not_fulfilled

Failure reasons

Notes

• billingRedirectUrl is for invoice billing setup. Use it with partner team provisioning or account status.
• redirectUrl is for one-time campaign recipient checkout. Use it with POST /api/recipients/checkout.
• Both redirect URLs must use HTTPS.
• Billing setup redirects do not include campaignId.
• Recipient checkout redirects include campaignId when the checkout session is tied to a campaign.
• The callback URL should treat query parameters as status signals and fetch current account, campaign, or recipient state from the API before updating local records.

Status codes