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].

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

Used for ACH only

The authorization code indicates how the mandate authorization was obtained.

This defaults to PPD for B2C and CCD for B2B

Enum: "CCD" "PPD" "TEL" "WEB"
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.

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,
  • "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",
  • "themeId": "be4bc9c1-c3fb-43c8-ab1a-908a86123682"
}
Response samples
application/json
{
  • "sessionToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb3JyZWxhdGlvbm...",
  • "expires": 1641990742
}

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.

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"
}
Response samples
application/json
{
  • "sessionToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb3JyZWxhdGlvbm...",
  • "expires": 1641990742
}

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
required
number <decimal> (Amount)

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.

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.

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.

object or null (BankAccount)

The bank account details [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
{
  • "customerRef": "customer1",
  • "direction": "Debit",
  • "schemeId": "299EED4F2F04915CCAFC50E17103179F",
  • "expirySeconds": 500,
  • "amount": 1.23,
  • "currency": "GBP",
  • "country": "UK",
  • "billingStreet1": "Flat 30 Lynton Mansions",
  • "billingStreet2": "53 Cottington St",
  • "billingCity": "London",
  • "billingState": "California",
  • "billingCountry": "United Kingdom",
  • "billingPostCode": "SE1 4BN",
  • "customerEmail": "JohnDangerSmith@imbursepayments.com",
  • "cardholderName": "John Danger Smith",
  • "customerMobilePhone": "07723456789",
  • "themeId": "8BB3BCDB-A0EB-4328-8C92-E596E3D7A63C",
  • "bankAccount": {
    • "accountHolderName": "John James",
    • "number": "234234234",
    • "extraCode": "234234"
    }
}
Response samples
application/json
{
  • "sessionToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb3JyZWxhdGlvbm...",
  • "expires": 1641990742
}
Copyright 2024 Duck Creek Technologies. All Rights Reserved.