Create session
POST /v3/payment-tools/session
Create a Payment Tools session for Checkout, Signup or Payment Module.
- To get started, take a look at the examples on the right:
Checkout, Signup or Payment Module - Read about Authentication
Query Parameters
- fields string
Limit which fields are returned by the API. The
fields
query parameter takes a comma-separated list of fields or 'none'. Example:fields=sessionId,htmlSnippet
. If 'none' is specified, an empty 204 will be returned.
Header Parameters
- Content-Type string
Possible values: [
application/json
] - Accept string
Possible values: [
application/json
] - Authorization string
Format: "Basic <base64(username:secret)>"
- application/json
Request Body
product object required
type string requiredPossible values: [
payment
,signup
]Type of payment-tools product.
intent stringPossible values: [
payment_one_time
,signup
]id stringProvide this if you have created an alternate configuration in the backoffice that you want to use.
- customerType customerType required
Possible values: [
business
,consumer
]Which type of customer this session is for.
- country country required
Country code in ISO 3166-1 alpha-2 format.
- locale locale required
Locale in "sv-se" / "en-gb" format.
urls object required
terms stringURL to your terms & conditions, will be shown in the iframe. Required when product.type is 'payment'.
redirect string requiredURL that users will be redirected to after completing the session. Usually some sort of thank-you page.
references object
Your own references, here we recommend using property name "reference1" as your order reference for payments since this property is default for multiple payment providers. But any additional property name can be used e.g. customerId. Example: { "reference1": "000", "customerId": "12345" }
property name*
stringPossible values:
<= 512 characters
hooks object[]
WARNING: These webhooks are unauthenticated so you must read the session after receiving events to vaildate the event.
Subscribe to events submitted by Briqpay.
The hook response consists of "event", "status" and "sessionId".
If using "GET", the response parameters will be sent as query parameters and when using "POST" it will be sent as the request body.
Example response payloads:
session_status:
{ "event": "session_status", "status": "completed", "sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d" }
order_status:
{ "event": "order_status", "status": "order_approved_not_captured", "sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d" }
capture_status:
{ "event": "capture_status", "status": "approved", "sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d", "captureId": "a3811397-a1fc-44f0-99fd-d134063c9c47" }
refund_status:
{ "event": "refund_status", "status": "approved", "sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d", "refundId": "a3811397-a1fc-44f0-99fd-d134063c9c47" }
Array [- oneOf
- Session status
- Order status
- Capture status
- Refund status
eventType stringPossible values: [
session_status
]statuses string[]Possible values: [
completed
]method stringPossible values: [
GET
,POST
]url stringeventType stringPossible values: [
order_status
]statuses string[]Possible values: [
order_pending
,order_rejected
,order_cancelled
,order_approved_not_captured
]method stringPossible values: [
GET
,POST
]url stringeventType stringPossible values: [
capture_status
]statuses string[]Possible values: [
pending
,approved
,rejected
]method stringPossible values: [
GET
,POST
]url stringeventType stringPossible values: [
refund_status
]statuses string[]Possible values: [
pending
,approved
,rejected
]method stringPossible values: [
GET
,POST
]url string]config object
General configuration for this session.
disableInsightsTracking booleanDisable Briqpay Insights tracking for this individual session.
data object
Provide data such as billing details and cart items.
order object
currency currency requiredExample: SEK, EUR, USD
amountIncVat amountIncVat requiredAmount including VAT. Should be in cents / minor units. e.g. 1 SEK = 100.
cart object[] required
Array [productType string requiredPossible values: [
physical
,digital
,discount
,shipping_fee
,sales_tax
,deposit
,surcharge
]The type of items being sold. When using 'discount', the unitPrice should be negative.
reference stringThe SKU of the item
name string requiredquantity integer requiredquantityUnit string requiredunitPrice integer requiredUnit price in minor units (e.g. 1 EUR = 100 unitPrice). Should be excluding VAT and excluding discount.
taxRate integer requiredThe applicable taxrate in minor units. Eg 25% = 2500
discountPercentage integerDiscount value in percentages. 10% = 1000
]company object
data object
Prefill known data of your customer.
cin stringCompany identification number.
consumer object
data object
Prefill known data of your customer.
identificationNumber stringNational identification number, social security number or similar.
dateOfBirth stringDate of birth (YYYY-MM-DD).
billing object
data object
Prefill known data of your customer.
streetAddress stringstreetAddress2 stringzip stringcity stringfirstName stringlastName stringemail stringphoneNumber stringshipping object
data object
Prefill known data of your customer.
streetAddress stringstreetAddress2 stringzip stringcity stringfirstName stringlastName stringemail stringphoneNumber stringmodules object
Configure the module system.
loadModules string[]Possible values: [
company_lookup
,billing
,shipping
,upsell
,cross_border
,payment
,order_note
,custom_form
,terms
]Override which partial set of modules should be loaded, e.g. when you only want payments instead of a full flow.
config object
Configure payment-tools modules.
company_lookup object
companyPrefillLock stringPossible values: [
none
,locked_with_manual_fallback
]billing object
lockFields object
Prevent users from editing addresses and user details. "hard_lock" - no user edits are possible, even with invalid data. "soft_lock" - empty or invalid fields will not be locked.
property name*
stringPossible values: [
none
,soft_lock
,hard_lock
]shipping object
lockFields object
Prevent users from editing addresses and user details. "hard_lock" - no user edits are possible, even with invalid data. "soft_lock" - empty or invalid fields will not be locked.
property name*
stringPossible values: [
none
,soft_lock
,hard_lock
]payment object
pspRulesOverride object
Override rules for payment methods in order to show or hide payment methods. Either 'pspId' or 'category' must be specified in the psp object.
psp object[]
Array [pspId stringThe pspId of the payment method that you wish to manually control.
pspCategory stringThe category of the payment method that you wish to manually control.
handles object required
enabled booleanshould this payment method be enabled in the checkout?
otherHandles string requiredPossible values: [
run_rules
,disable
]How should the other handles (locked, strong auth, etc) configured on this payment method act?
]otherPsps stringPossible values: [
disable
,rul_rules
]purchaseDecision object
enabled booleanorder_note object
Override which inputs will be collected in the Order note module.
customInputs object[]
Inputs that will be collected in the Order note module.
Array [type stringPossible values: [
string
,boolean
,object
]key stringThe input key, must be unique between all inputs.
label stringThe label to be presented in relation to the input.
minLength numbermaxLength numberrequired booleanDefault value:
false
span numberPossible values: [
1
,2
]Control if the input field should span over 1 or 2 columns.
enum string[]Configure available values when using a "enumRadio" or "enumDropdown" component.
component stringPossible values: [
textField
,textArea
,checkbox
,enumRadio
,enumDropdown
]]hideModule booleanupsell object
Configure which inputs will be collected in the Upsell module.
customInputs object[]
Inputs that will be collected in the Upsell module.
Array [type stringPossible values: [
string
,boolean
,object
]key stringThe input key, must be unique between all inputs.
label stringThe label to be presented in relation to the input.
minLength numbermaxLength numberrequired booleanDefault value:
false
span numberPossible values: [
1
,2
]Control if the input field should span over 1 or 2 columns.
enum string[]Configure available values when using a "enumRadio" or "enumDropdown" component.
component stringPossible values: [
textField
,textArea
,checkbox
,enumRadio
,enumDropdown
]]hideModule booleanheader stringPossible values:
<= 64 characters
Module header text.
subheader stringPossible values:
<= 512 characters
Module sub-header text.
footer stringPossible values:
<= 512 characters
Module footer text.
- 201
- 204
- 400
- application/json
- Schema
- Example (from schema)
Schema
- createdAt date
ISO 8601 format, example: "2023-04-12T13:16:08.647Z".
- sessionId uuid
UUID
- status sessionStatus
Possible values: [
started
,modules_in_progress
,completed
]Status of the session. Does not indicate status of payments, that can be read from moduleStatus.payment.orderStatus.
product object
type string requiredPossible values: [
payment
,signup
]Type of payment-tools product.
intent stringPossible values: [
payment_one_time
,signup
]id stringProvide this if you have created an alternate configuration in the backoffice that you want to use.
- customerType customerType
Possible values: [
business
,consumer
]Which type of customer this session is for.
- country country
Country code in ISO 3166-1 alpha-2 format.
- locale locale
Locale in "sv-se" / "en-gb" format.
urls object
terms stringURL to your terms & conditions, will be shown in the iframe. Required when product.type is 'payment'.
redirect string requiredURL that users will be redirected to after completing the session. Usually some sort of thank-you page.
references object
Your own references, here we recommend using property name "reference1" as your order reference for payments since this property is default for multiple payment providers. But any additional property name can be used e.g. customerId. Example: { "reference1": "000", "customerId": "12345" }
property name*
stringPossible values:
<= 512 characters
hooks object[]
WARNING: These webhooks are unauthenticated so you must read the session after receiving events to vaildate the event.
Subscribe to events submitted by Briqpay.
The hook response consists of "event", "status" and "sessionId".
If using "GET", the response parameters will be sent as query parameters and when using "POST" it will be sent as the request body.
Example response payloads:
session_status:
{ "event": "session_status", "status": "completed", "sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d" }
order_status:
{ "event": "order_status", "status": "order_approved_not_captured", "sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d" }
capture_status:
{ "event": "capture_status", "status": "approved", "sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d", "captureId": "a3811397-a1fc-44f0-99fd-d134063c9c47" }
refund_status:
{ "event": "refund_status", "status": "approved", "sessionId": "61c16f84-b42e-4e1c-a114-a117a6e1e27d", "refundId": "a3811397-a1fc-44f0-99fd-d134063c9c47" }
Array [- oneOf
- Session status
- Order status
- Capture status
- Refund status
eventType stringPossible values: [
session_status
]statuses string[]Possible values: [
completed
]method stringPossible values: [
GET
,POST
]url stringeventType stringPossible values: [
order_status
]statuses string[]Possible values: [
order_pending
,order_rejected
,order_cancelled
,order_approved_not_captured
]method stringPossible values: [
GET
,POST
]url stringeventType stringPossible values: [
capture_status
]statuses string[]Possible values: [
pending
,approved
,rejected
]method stringPossible values: [
GET
,POST
]url stringeventType stringPossible values: [
refund_status
]statuses string[]Possible values: [
pending
,approved
,rejected
]method stringPossible values: [
GET
,POST
]url string]- htmlSnippet htmlSnippet
The easiest way to render an iframe, simply add the html snippet where you want.
- clientToken clientToken
Can be used with the client SDK to render iframes.
moduleStatus object
States of individual modules.
company_lookup object
uiStatus uiStatusPossible values: [
locked_by_merchant
,not_yet_reached
,hidden
,visible
,visible_required
,visible_optional
,completed
]Status of the module in the UI.
billing object
uiStatus uiStatusPossible values: [
locked_by_merchant
,not_yet_reached
,hidden
,visible
,visible_required
,visible_optional
,completed
]Status of the module in the UI.
shipping object
uiStatus uiStatusPossible values: [
locked_by_merchant
,not_yet_reached
,hidden
,visible
,visible_required
,visible_optional
,completed
]Status of the module in the UI.
payment object
uiStatus uiStatusPossible values: [
locked_by_merchant
,not_yet_reached
,hidden
,visible
,visible_required
,visible_optional
,completed
]Status of the module in the UI.
orderStatus orderStatusPossible values: [
order_pending
,order_rejected
,order_cancelled
,order_approved_not_captured
,captured_partial
,captured_full
]Order status in the checkout / payment module.
refundStatus refundStatusPossible values: [
not_refunded
,partially_refunded
,captured_amount_fully_refunded
]data object
company object
Only available when the session is completed.
cin stringCompany identification number.
name stringCompany name.
consumer object
data object
Prefill known data of your customer.
identificationNumber stringNational identification number, social security number or similar.
dateOfBirth stringDate of birth (YYYY-MM-DD).
billing object
Only available when the session is completed.
companyName stringB2B only.
cin stringB2B only.
streetAddress stringstreetAddress2 stringzip stringcity stringfirstName stringlastName stringemail stringphoneNumber stringcountry countryCountry code in ISO 3166-1 alpha-2 format.
shipping object
Only available when the session is completed.
companyName stringB2B only.
cin stringB2B only.
streetAddress stringstreetAddress2 stringzip stringcity stringfirstName stringlastName stringemail stringphoneNumber stringcountry countryCountry code in ISO 3166-1 alpha-2 format.
order object
currency currencyExample: SEK, EUR, USD
amountIncVat amountIncVatAmount including VAT. Should be in cents / minor units. e.g. 1 SEK = 100.
cart object[]
Array [productType string requiredPossible values: [
physical
,digital
,discount
,shipping_fee
,sales_tax
,deposit
,surcharge
]The type of items being sold. When using 'discount', the unitPrice should be negative.
reference stringThe SKU of the item
name string requiredquantity integer requiredquantityUnit string requiredunitPrice integer requiredUnit price in minor units (e.g. 1 EUR = 100 unitPrice). Should be excluding VAT and excluding discount.
taxRate integer requiredThe applicable taxrate in minor units. Eg 25% = 2500
discountPercentage integerDiscount value in percentages. 10% = 1000
]transactions object[]
Only available when the session is completed.
Array [createdAt dateISO 8601 format, example: "2023-04-12T13:16:08.647Z".
transactionId stringreservationId stringpspId stringpspName stringemail stringreference stringamountIncVat amountIncVatAmount including VAT. Should be in cents / minor units. e.g. 1 SEK = 100.
currency currencyExample: SEK, EUR, USD
status stringPossible values: [
pending
,approved
,rejected
,cancelled
]captureStatus stringPossible values: [
not_captured
,partially_captured
,fully_captured
]refundStatus refundStatusPossible values: [
not_refunded
,partially_refunded
,captured_amount_fully_refunded
]sessionId string]captures object[]
Only available when the session is completed.
Array [createdAt dateISO 8601 format, example: "2023-04-12T13:16:08.647Z".
captureId stringparentTransactionId stringreservationId stringpspId stringpspName stringemail stringreference stringamountIncVat amountIncVatAmount including VAT. Should be in cents / minor units. e.g. 1 SEK = 100.
currency currencyExample: SEK, EUR, USD
status stringPossible values: [
pending
,captured
,rejected
]sessionId string]refunds object[]
Only available when the session is completed.
Array [createdAt dateISO 8601 format, example: "2023-04-12T13:16:08.647Z".
refundId stringparentTransactionId stringreservationId stringpspId stringpspName stringemail stringreference stringamountIncVat amountIncVatAmount including VAT. Should be in cents / minor units. e.g. 1 SEK = 100.
currency currencyExample: SEK, EUR, USD
status stringPossible values: [
pending
,refunded
,rejected
]sessionId string]paymentTags object
Only available when the session is completed. Tags on the payment method used for the initial payment. Example: "prepaid_invoice", "manual_review".
property name*
booleanorderNote object
Only available when the session is completed. Object containing order notes submitted by the user. The default structure of the object, unless modified by including config for the order_note module, is { "note": { "value": "Note goes here" } }
property name* object
value stringheader stringcustomForm1 object
Only available when the session is completed. Contains the form data of the custom form module.
property name* object
value stringheader stringlabel stringterms object
Only available when the session is completed. Contains data for the checkboxes of the terms module.
property name* object
value booleanheader string
{
"createdAt": "2023-04-12T13:16:08.647Z",
"sessionId": "c5674f4f-7e84-405c-a44b-c83736bb7209",
"status": "started",
"product": {
"type": "payment",
"intent": "payment_one_time",
"id": "a8a7acb2-4c65-4a91-a8e5-d8125bf64fd4"
},
"customerType": "business",
"country": "SE",
"locale": "sv-se",
"urls": {
"terms": "https://example.com/terms",
"redirect": "https://example.com/redirect"
},
"references": {
"reference1": "000",
"orderId": "12345",
"customerId": "54321"
},
"hooks": [
{
"eventType": "session_status",
"statuses": [
"completed"
],
"method": "POST",
"url": "https://example.com/notifications"
},
{
"eventType": "order_status",
"statuses": [
"order_pending",
"order_rejected",
"order_cancelled",
"order_approved_not_captured"
],
"method": "POST",
"url": "https://example.com/notifications"
},
{
"eventType": "capture_status",
"statuses": [
"pending",
"approved",
"rejected"
],
"method": "POST",
"url": "https://example.com/notifications"
},
{
"eventType": "refund_status",
"statuses": [
"pending",
"approved",
"rejected"
],
"method": "POST",
"url": "https://example.com/notifications"
}
],
"htmlSnippet": "<div><iframe/></div>",
"clientToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"moduleStatus": {
"company_lookup": {
"uiStatus": "locked_by_merchant"
},
"billing": {
"uiStatus": "locked_by_merchant"
},
"shipping": {
"uiStatus": "locked_by_merchant"
},
"payment": {
"uiStatus": "locked_by_merchant",
"orderStatus": "order_pending",
"refundStatus": "not_refunded"
}
},
"data": {
"company": {
"cin": "0123456789",
"name": "Example Company"
},
"consumer": {
"data": {
"identificationNumber": "19700101****",
"dateOfBirth": "1970-01-01"
}
},
"billing": {
"companyName": "string",
"cin": "string",
"streetAddress": "string",
"streetAddress2": "string",
"zip": "string",
"city": "string",
"firstName": "string",
"lastName": "string",
"email": "string",
"phoneNumber": "string",
"country": "SE"
},
"shipping": {
"companyName": "string",
"cin": "string",
"streetAddress": "string",
"streetAddress2": "string",
"zip": "string",
"city": "string",
"firstName": "string",
"lastName": "string",
"email": "string",
"phoneNumber": "string",
"country": "SE"
},
"order": {
"currency": "SEK",
"amountIncVat": 3000,
"cart": [
{
"productType": "physical",
"reference": "testproduct1",
"name": "Test product",
"quantity": 2,
"quantityUnit": "pc",
"unitPrice": 1200,
"taxRate": 2500,
"discountPercentage": 1000
}
]
},
"transactions": [
{
"createdAt": "2023-04-12T13:16:08.647Z",
"transactionId": "string",
"reservationId": "string",
"pspId": "string",
"pspName": "string",
"email": "string",
"reference": "string",
"amountIncVat": 3000,
"currency": "SEK",
"status": "pending",
"captureStatus": "not_captured",
"refundStatus": "not_refunded",
"sessionId": "string"
}
],
"captures": [
{
"createdAt": "2023-04-12T13:16:08.647Z",
"captureId": "string",
"parentTransactionId": "string",
"reservationId": "string",
"pspId": "string",
"pspName": "string",
"email": "string",
"reference": "string",
"amountIncVat": 3000,
"currency": "SEK",
"status": "pending",
"sessionId": "string"
}
],
"refunds": [
{
"createdAt": "2023-04-12T13:16:08.647Z",
"refundId": "string",
"parentTransactionId": "string",
"reservationId": "string",
"pspId": "string",
"pspName": "string",
"email": "string",
"reference": "string",
"amountIncVat": 3000,
"currency": "SEK",
"status": "pending",
"sessionId": "string"
}
],
"paymentTags": {},
"orderNote": {},
"customForm1": {},
"terms": {}
}
}
- application/json
- Schema
- Example (from schema)
Schema
error object
code stringPossible values: [
INVALID_CREDENTIALS
,INVALID_DATA
,ORDER_NOT_CAPTURED
,UNKNOWN
,etc
]message string
{
"error": {
"code": "INVALID_CREDENTIALS",
"message": "string"
}
}