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.

Enum: "Weekly" "EveryTwoWeeks" "Monthly" "EveryTwoMonths" "EveryThreeMonths" "Annually" "EveryTwoYears"
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.

Enum: "Weekly" "EveryTwoWeeks" "Monthly" "EveryTwoMonths" "EveryThreeMonths" "Annually" "EveryTwoYears"
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 2024 Duck Creek Technologies. All Rights Reserved.