Whitelabel

Create session token

Role Requirements

CustomerToken

Description

Create a checkout session token to be used with the whitelabel (checkout) component

Validation

Based on the customerType selection, the validation of the payload in this endpoint changes with the following fields: - B2C: customerFirstName, customerLastName - B2B: companyName

Securitybearer
Request
header Parameters
x-account-id
required
string <uuid> = 36 characters

The Account Id.

Example: 00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid> = 36 characters

The Tenant Id.

Example: 00000000-0000-0000-0000-000000000000
x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

Customer details for the session token

orderRef
required
string (OrderRef) <= 50 characters ^[a-zA-Z0-9-_\.]+$

The order reference. [Required].

instructionRef
required
string (InstructionRef) <= 50 characters ^[a-zA-Z0-9-_\.]+$

The instruction reference. [Required].

expirySeconds
required
integer <int64> (ExpirySeconds) >= 1

The number of seconds till the session expires [Required].

themeId
string or null <uuid> (ThemeId)

The ThemeId associated with the session [Optional]. The theme is used to style elements when the session is used in the checkout component/page. If left empty/null, will default to the tenant's default.

billingHouseNumber
string or null (BillingHouseNumber)

The billing address house number [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingStreet1
string or null (BillingStreet1)

The billing address street 1 (line 1 out of possible 2) [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingStreet2
string or null (BillingStreet2)

The billing address street 2 (line 2 out of possible 2) [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingCity
string or null (BillingCity)

The billing address state [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingState
string or null (BillingState)

The billing address state [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingCountry
string or null (BillingCountry)

The billing address country [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingPostCode
string or null (BillingPostCode)

The billing address post code [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerEmail
string or null (CustomerEmail)

The customer email [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerMobilePhone
string or null (CustomerMobilePhone)

The customer mobile phone number [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

cardholderName
string or null (CardholderName)

The card-holder's name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerFirstName
string or null (CustomerFirstName)

The customer's first name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerLastName
string or null (CustomerLastName)

The customer's last name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

companyName
string or null (CompanyName)

The customer's company name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerType
string or null (CustomerType)
Default: "B2C"

The customer type to denote if it's a business or a customer.

Enum: "B2B" "B2C"
authorizationSource
string

The authorization code indicates how the session was authorized.

This defaults to WEB for CustomerType B2C and B2B.

Credit direction only supports PAPER.

Enum: "PAPER" "WEB" "TEL"
authorizationFrequency
string (AuthorizationFrequency)

Required for ACH only

The authorization frequency indicates how often the mandate is authorized.

If set to Other, the authorizationFrequencyOtherWording field must be provided.

Enum: "Weekly" "EveryTwoWeeks" "Monthly" "EveryTwoMonths" "EveryThreeMonths" "EverySixMonths" "Annually" "EveryTwoYears" "Other"
object or null (WLSAuthorizationFrequencyOtherWording)

Required for ACH only

If authorizationFrequency set to Other, then this field is required

This is the wording displayed to the customer on the ACH Authorization screen during checkout flow, when the authorization frequency is set to Other.

Value must be a string with a minimum length of 1 and a maximum length of 100 characters, and can contain only the following characters: lowercase letters, numbers, space, comma, parentheses, single quote, hyphen, ampersand, forward slash.

It will be displayed within the following sentence: "To be collected [authorizationFrequencyOtherWording]."

object or null (BankAccount)

The bank account details [Optional].

Array of objects or null (Channel)

The channels indicates the method of how you would like the link to be sent directly to the end-user. Where information is provided on the channels array, a link will be sent directly to the specified email address or phone number [Optional].

Responses
201

Session token created successfully

400

Bad Request

401

Unauthorized

403

Forbidden

post/v2/whitelabel-customer/session/checkout
Request samples
application/json

B2B flow

{
  • "orderRef": "order-ref-123",
  • "instructionRef": "instruction-ref-123",
  • "expirySeconds": 500,
  • "themeId": "be4bc9c1-c3fb-43c8-ab1a-908a86123682",
  • "billingHouseNumber": "4",
  • "billingStreet1": "Thing Mansions",
  • "billingStreet2": "Somewhere St",
  • "billingCity": "Placington",
  • "billingState": "Hampshire",
  • "billingCountry": "United Kingdom",
  • "billingPostCode": "AB1 2CD",
  • "customerEmail": "john.smith@example.com",
  • "customerMobilePhone": "07123456789",
  • "cardholderName": "MR J SMITH",
  • "companyName": "Payments LLC",
  • "customerType": "B2B",
  • "authorizationSource": "WEB",
  • "authorizationFrequency": "Monthly",
  • "bankAccount": {
    • "accountHolderName": "MR J SMITH",
    • "number": "10001000",
    • "extraCode": "100100"
    },
  • "channels": [
    • {
      • "type": "Email",
      • "destination": "an-email@duckcreek.com"
      }
    ]
}
Response samples
application/json
{}

Create a mandate session token.

Role Requirements

CustomerToken

Description

Create a checkout session token for the management of a mandate.

Securitybearer
Request
header Parameters
x-account-id
required
string <uuid> = 36 characters

The Account Id.

Example: 00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid> = 36 characters

The Tenant Id.

Example: 00000000-0000-0000-0000-000000000000
x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

Customer details for the session token

customerRef
required
string (CustomerRef) <= 50 characters ^[a-zA-Z0-9-_\.]+$

The client defined unique Customer Reference.

mandateId
required
string <uuid> (MandateIdV2) [ 1 .. 50 ] characters

The system's unique identifier for the mandate.

action
required
string (MandateAction)

The action to perform against the mandate.

Value: "Amendment"
expirySeconds
required
integer <int64> (ExpirySeconds) >= 1

The number of seconds till the session expires [Required].

themeId
string or null <uuid> (ThemeId)

The ThemeId associated with the session [Optional]. The theme is used to style elements when the session is used in the checkout component/page. If left empty/null, will default to the tenant's default.

billingHouseNumber
string or null (BillingHouseNumber)

The billing address house number [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingStreet1
string or null (BillingStreet1)

The billing address street 1 (line 1 out of possible 2) [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingStreet2
string or null (BillingStreet2)

The billing address street 2 (line 2 out of possible 2) [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingCity
string or null (BillingCity)

The billing address state [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingState
string or null (BillingState)

The billing address state [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingCountry
string or null (BillingCountry)

The billing address country [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingPostCode
string or null (BillingPostCode)

The billing address post code [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerEmail
string or null (CustomerEmail)

The customer email [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerMobilePhone
string or null (CustomerMobilePhone)

The customer mobile phone number [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerFirstName
string or null (CustomerFirstName)

The customer's first name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerLastName
string or null (CustomerLastName)

The customer's last name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

companyName
string or null (CompanyName)

The customer's company name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

object or null (BankAccount)

The bank account details [Optional].

Array of objects or null (Channel)

The channels indicates the method of how you would like the link to be sent directly to the end-user. Where information is provided on the channels array, a link will be sent directly to the specified email address or phone number [Optional].

Responses
201

Session token created successfully

400

Bad Request

401

Unauthorized

403

Forbidden

post/v2/whitelabel-customer/session/mandate
Request samples
application/json

B2B flow

{
  • "customerRef": "customer-ref-123",
  • "mandateId": "be4bc9c1-c3fb-43c8-ab1a-908a86123682",
  • "action": "Amendment",
  • "expirySeconds": 500,
  • "billingHouseNumber": "4",
  • "billingStreet1": "Thing Mansions",
  • "billingStreet2": "Somewhere St",
  • "billingCity": "Placington",
  • "billingState": "Hampshire",
  • "billingCountry": "United Kingdom",
  • "billingPostCode": "AB1 2CD",
  • "customerEmail": "john.smith@example.com",
  • "customerMobilePhone": "07123456789",
  • "companyName": "Payments LLC",
  • "themeId": "be4bc9c1-c3fb-43c8-ab1a-908a86123682",
  • "bankAccount": {
    • "accountHolderName": "MR J SMITH",
    • "number": "10001000",
    • "extraCode": "100100"
    },
  • "channels": [
    • {
      • "type": "Email",
      • "destination": "an-email@duckcreek.com"
      }
    ]
}
Response samples
application/json
{}

Create a financial instrument session token

Role Requirements

CustomerToken

Description

Create a checkout session token for the generation of a financial instrument.

Securitybearer
Request
header Parameters
x-account-id
required
string <uuid> = 36 characters

The Account Id.

Example: 00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid> = 36 characters

The Tenant Id.

Example: 00000000-0000-0000-0000-000000000000
x-correlation-id
string

Correlation Id for the request.

Request Body schema: application/json

Customer details for the session token

customerRef
required
string (CustomerRef) <= 50 characters ^[a-zA-Z0-9-_\.]+$

The client defined unique Customer Reference.

direction
required
string (Direction)

The direction of the instruction: Debit or Credit. The Scheme used must match this direction.

Enum: "DEBIT" "CREDIT"
schemeId
required
string (SchemeId)

The Payout or Collect scheme Id from the tenant portal.

expirySeconds
required
integer <int64> (ExpirySeconds) >= 1

The number of seconds till the session expires [Required].

amount
number or null <decimal>

Currency amount. The number of decimal digits is validated against the currency code of the payment.

currency
required
string (Currency) ^[A-Z]{3}$

ISO 4217 code (3 uppercase letters) for the chosen currency.

country
required
string (Country) ^[A-Z]{2}$

The ISO 3166-1 alpha 2 country code (2 letter code) for the chosen country of the future transaction.

billingHouseNumber
string or null (BillingHouseNumber)

The billing address house number [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingStreet1
string or null (BillingStreet1)

The billing address street 1 (line 1 out of possible 2) [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingStreet2
string or null (BillingStreet2)

The billing address street 2 (line 2 out of possible 2) [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingCity
string or null (BillingCity)

The billing address state [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingState
string or null (BillingState)

The billing address state [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingCountry
string or null (BillingCountry)

The billing address country [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

billingPostCode
string or null (BillingPostCode)

The billing address post code [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerEmail
string or null (CustomerEmail)

The customer email [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

cardholderName
string or null (CardholderName)

The card-holder's name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerFirstName
string or null (CustomerFirstName)

The customer's first name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerLastName
string or null (CustomerLastName)

The customer's last name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

companyName
string or null (CompanyName)

The customer's company name [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

customerMobilePhone
string or null (CustomerMobilePhone)

The customer mobile phone number [Optional]. Note: Personal details - NOT SAVED, exists only in the token.

themeId
string or null <uuid> (ThemeId)

The ThemeId associated with the session [Optional]. The theme is used to style elements when the session is used in the checkout component/page. If left empty/null, will default to the tenant's default.

customerType
string or null (CustomerType)
Default: "B2C"

The customer type to denote if it's a business or a customer.

Enum: "B2B" "B2C"
authorizationSource
string

The authorization code indicates how the session was authorized.

This defaults to WEB for CustomerType B2C and B2B.

Credit direction only supports PAPER.

Enum: "PAPER" "WEB" "TEL"
authorizationFrequency
string (AuthorizationFrequency)

Required for ACH only

The authorization frequency indicates how often the mandate is authorized.

If set to Other, the authorizationFrequencyOtherWording field must be provided.

Enum: "Weekly" "EveryTwoWeeks" "Monthly" "EveryTwoMonths" "EveryThreeMonths" "EverySixMonths" "Annually" "EveryTwoYears" "Other"
object or null (WLSAuthorizationFrequencyOtherWording)

Required for ACH only

If authorizationFrequency set to Other, then this field is required

This is the wording displayed to the customer on the ACH Authorization screen during checkout flow, when the authorization frequency is set to Other.

Value must be a string with a minimum length of 1 and a maximum length of 100 characters, and can contain only the following characters: lowercase letters, numbers, space, comma, parentheses, single quote, hyphen, ampersand, forward slash.

It will be displayed within the following sentence: "To be collected [authorizationFrequencyOtherWording]."

object or null (BankAccount)

The bank account details [Optional].

Array of objects or null (Channel)

The channels indicates the method of how you would like the link to be sent directly to the end-user. Where information is provided on the channels array, a link will be sent directly to the specified email address or phone number [Optional].

Responses
201

Session token created successfully

400

Bad Request

401

Unauthorized

403

Forbidden

post/v2/whitelabel-customer/session/financial-instrument
Request samples
application/json

B2C flow

{
  • "customerRef": "customer-ref-123",
  • "direction": "DEBIT",
  • "schemeId": "299EED4F2F04915CCAFC50E17103179F",
  • "expirySeconds": 500,
  • "currency": "GBP",
  • "country": "GB",
  • "billingHouseNumber": "4",
  • "billingStreet1": "Thing Mansions",
  • "billingStreet2": "Somewhere St",
  • "billingCity": "Placington",
  • "billingState": "Hampshire",
  • "billingCountry": "GB",
  • "billingPostCode": "AB1 2CD",
  • "customerEmail": "JohnDangerSmith@imbursepayments.com",
  • "cardholderName": "MR J SMITH",
  • "customerFirstName": "John",
  • "customerLastName": "Smith",
  • "customerMobilePhone": "07123456789",
  • "themeId": "be4bc9c1-c3fb-43c8-ab1a-908a86123682",
  • "customerType": "B2C",
  • "authorizationSource": "WEB",
  • "authorizationFrequency": "Monthly",
  • "bankAccount": {
    • "accountHolderName": "MR J SMITH",
    • "number": "10001000",
    • "extraCode": "100100"
    },
  • "channels": [
    • {
      • "type": "SMS",
      • "destination": "+4401234567890"
      }
    ]
}
Response samples
application/json
{}

Get Session

Role Requirements

tenant-white-label-read

Description

Get the details of a whitelabel session.

Securitybearer
Request
path Parameters
sessionId
required
string <uuid>

The session ID

header Parameters
x-account-id
required
string <uuid> = 36 characters

The Account Id.

Example: 00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid> = 36 characters

The Tenant Id.

Example: 00000000-0000-0000-0000-000000000000
x-correlation-id
string

Correlation Id for the request.

Responses
201

Session details

400

Bad Request

401

Unauthorized

403

Forbidden

get/v2/whitelabel-customer/session/details/{sessionId}
Request samples 
Response samples 
application/json
Successful Checkout session


{
  • "sessionId": "59d3068b-f5f3-4212-978f-e2b9181f302e",
  • "sessionType": "Checkout",
  • "customerRef": "customer1",
  • "status": "SUCCESS",
  • "paymentOptionSelected": "VISA",
  • "instructionRef": "instruction1",
  • "orderRef": "order1"
}
Copyright 2025 Duck Creek Technologies. All Rights Reserved.