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 pay-by-link object

Role Requirements

CustomerToken

Description

This endpoint creates a new session token, as well as a pay-by-link object with the instructions of sending a link for completing the payment.

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, and pay-by-link details for future sending.

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].
	Array of objects or null (Channel)
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.

Responses

201

Session token created successfully

400

Bad Request

401

Unauthorized

403

Forbidden

post/v2/whitelabel-customer/session/checkout/pay-by-link

Request samples

application/json

{"orderRef": "order-ref-123",
"instructionRef": "instruction-ref-123",
"channels": [{"type": "SMS",
"destination": "email address"
}
],
"expirySeconds": 500,
"themeId": "8BB3BCDB-A0EB-4328-8C92-E596E3D7A63C"
}

Response samples

application/json

{"payByLinkId": "df6b16ec-6a19-4091-9d4e-2d0603077655",
"link": "https://www.example_url.com?token=hdksjdhfkshdkfjhkdjshfkjsdhfkjh="
}

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
}