Skip to main content
Version: 3.0.0 (current)

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)>"

Request Body
  • product object required
  • type string required

    Possible values: [payment, signup]

    Type of payment-tools product.

  • intent string

    Possible values: [payment_one_time, signup]

  • id string

    Provide 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 string

    URL to your terms & conditions, will be shown in the iframe. Required when product.type is 'payment'.

  • redirect string required

    URL 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* string

    Possible 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
  • eventType string

    Possible values: [session_status]

  • statuses string[]

    Possible values: [completed]

  • method string

    Possible values: [GET, POST]

  • url string
  • ]
  • config object

    General configuration for this session.

  • disableInsightsTracking boolean

    Default value: false

    Disable Briqpay Insights tracking for this session.

  • disableSessionCompleteRedirect boolean

    Default value: false

    Disable session complete redirect for this session.

  • data object

    Provide data such as billing details and cart items.

  • order object
  • currency currency required

    Example: SEK, EUR, USD

  • amountIncVat amountIncVat required

    Amount including VAT. Should be in cents / minor units. e.g. 1 SEK = 100.

  • amountExVat amountExVat required

    Amount excluding VAT. Should be in cents / minor units. e.g. 1 SEK = 100.

  • cart object[] required
  • Array [
  • productType string required

    Possible 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 string

    The SKU of the item

  • name string required
  • quantity integer required
  • quantityUnit string required
  • unitPrice integer required

    Unit price in minor units (e.g. 1 EUR = 100 unitPrice). Should be excluding VAT and excluding discount.

  • taxRate integer required

    The applicable taxrate in minor units. Eg 25% = 2500

  • discountPercentage integer

    Discount value in percentages. 10% = 1000

  • ]
  • company object
  • cin string

    Company identification number.

  • consumer object
  • identificationNumber string

    National identification number, social security number or similar.

  • dateOfBirth string

    Date of birth (YYYY-MM-DD).

  • billing object
  • streetAddress string
  • streetAddress2 string
  • zip string
  • city string
  • firstName string
  • lastName string
  • email string
  • phoneNumber string
  • shipping object
  • streetAddress string
  • streetAddress2 string
  • zip string
  • city string
  • firstName string
  • lastName string
  • email string
  • phoneNumber string
  • modules 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 string

    Possible 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* string

    Possible 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* string

    Possible 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 string

    The pspId of the payment method that you wish to manually control.

  • handles object required
  • enabled boolean

    should this payment method be enabled in the checkout?

  • otherHandles string required

    Possible values: [run_rules, disable]

    How should the other handles (locked, strong auth, etc) configured on this payment method act?

  • ]
  • otherPsps string

    Possible values: [disable, run_rules]

  • order_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 string

    Possible values: [string, boolean, object]

  • key string

    The input key, must be unique between all inputs.

  • label string

    The label to be presented in relation to the input.

  • minLength number
  • maxLength number
  • required boolean

    Default value: false

  • span number

    Possible 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 string

    Possible values: [textField, textArea, checkbox, enumRadio, enumDropdown]

  • ]
  • hideModule boolean
  • upsell object

    Configure which inputs will be collected in the Upsell module.

  • customInputs object[]

    Inputs that will be collected in the Upsell module.

  • Array [
  • type string

    Possible values: [string, boolean, object]

  • key string

    The input key, must be unique between all inputs.

  • label string

    The label to be presented in relation to the input.

  • minLength number
  • maxLength number
  • required boolean

    Default value: false

  • span number

    Possible 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 string

    Possible values: [textField, textArea, checkbox, enumRadio, enumDropdown]

  • ]
  • hideModule boolean
  • header string

    Possible values: <= 64 characters

    Module header text.

  • subheader string

    Possible values: <= 512 characters

    Module sub-header text.

  • footer string

    Possible values: <= 512 characters

    Module footer text.

    • Responses
    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 required

      Possible values: [payment, signup]

      Type of payment-tools product.

    • intent string

      Possible values: [payment_one_time, signup]

    • id string

      Provide 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 string

      URL to your terms & conditions, will be shown in the iframe. Required when product.type is 'payment'.

    • redirect string required

      URL 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* string

      Possible 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
    • eventType string

      Possible values: [session_status]

    • statuses string[]

      Possible values: [completed]

    • method string

      Possible 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 uiStatus

    Possible values: [locked_by_merchant, not_yet_reached, hidden, visible, visible_required, visible_optional, completed]

    Status of the module in the UI.

  • billing object
  • uiStatus uiStatus

    Possible values: [locked_by_merchant, not_yet_reached, hidden, visible, visible_required, visible_optional, completed]

    Status of the module in the UI.

  • shipping object
  • uiStatus uiStatus

    Possible values: [locked_by_merchant, not_yet_reached, hidden, visible, visible_required, visible_optional, completed]

    Status of the module in the UI.

  • payment object
  • uiStatus uiStatus

    Possible values: [locked_by_merchant, not_yet_reached, hidden, visible, visible_required, visible_optional, completed]

    Status of the module in the UI.

  • orderStatus orderStatus

    Possible values: [order_pending, order_rejected, order_cancelled, order_approved_not_captured, captured_partial, captured_full]

    Order status in the checkout / payment module.

  • refundStatus refundStatus

    Possible values: [not_refunded, partially_refunded, captured_amount_fully_refunded]

  • data object
  • company object

    Only available when the session is completed.

  • cin string

    Company identification number.

  • name string

    Company name.

  • vatValidation object
  • vatNo string
  • valid boolean
  • country string
  • consumer object
  • identificationNumber string

    National identification number, social security number or similar.

  • dateOfBirth string

    Date of birth (YYYY-MM-DD).

  • billing object

    Only available when the session is completed.

  • companyName string

    B2B only.

  • cin string

    B2B only.

  • streetAddress string
  • streetAddress2 string
  • zip string
  • city string
  • firstName string
  • lastName string
  • email string
  • phoneNumber string
  • country country

    Country code in ISO 3166-1 alpha-2 format.

  • shipping object

    Only available when the session is completed.

  • companyName string

    B2B only.

  • cin string

    B2B only.

  • streetAddress string
  • streetAddress2 string
  • zip string
  • city string
  • firstName string
  • lastName string
  • email string
  • phoneNumber string
  • country country

    Country code in ISO 3166-1 alpha-2 format.

  • order object
  • currency currency

    Example: SEK, EUR, USD

  • amountIncVat amountIncVat

    Amount including VAT. Should be in cents / minor units. e.g. 1 SEK = 100.

  • amountExVat amountExVat

    Amount excluding VAT. Should be in cents / minor units. e.g. 1 SEK = 100.

  • cart object[]
  • Array [
  • productType string required

    Possible 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 string

    The SKU of the item

  • name string required
  • quantity integer required
  • quantityUnit string required
  • unitPrice integer required

    Unit price in minor units (e.g. 1 EUR = 100 unitPrice). Should be excluding VAT and excluding discount.

  • taxRate integer required

    The applicable taxrate in minor units. Eg 25% = 2500

  • discountPercentage integer

    Discount value in percentages. 10% = 1000

  • ]
  • transactions object[]

    Only available when the session is completed.

  • Array [
  • createdAt date

    ISO 8601 format, example: "2023-04-12T13:16:08.647Z".

  • transactionId string
  • reservationId string
  • pspId string

    Unique UUID identifier ot the payment method.

  • pspDisplayName string

    Localized name of the payment method that is showed to end users.

  • email string
  • reference string
  • amountIncVat amountIncVat

    Amount including VAT. Should be in cents / minor units. e.g. 1 SEK = 100.

  • amountExVat amountExVat

    Amount excluding VAT. Should be in cents / minor units. e.g. 1 SEK = 100.

  • currency currency

    Example: SEK, EUR, USD

  • status string

    Possible values: [pending, approved, rejected, cancelled]

  • captureStatus string

    Possible values: [not_captured, partially_captured, fully_captured]

  • refundStatus refundStatus

    Possible values: [not_refunded, partially_refunded, captured_amount_fully_refunded]

  • sessionId string
  • ]
  • captures object[]

    Only available when the session is completed.

  • Array [
  • createdAt date

    ISO 8601 format, example: "2023-04-12T13:16:08.647Z".

  • captureId string
  • parentTransactionId string
  • reservationId string
  • pspId string

    Unique UUID identifier ot the payment method.

  • pspDisplayName string

    Localized name of the payment method that is showed to end users.

  • email string
  • reference string
  • amountIncVat amountIncVat

    Amount including VAT. Should be in cents / minor units. e.g. 1 SEK = 100.

  • amountExVat amountExVat

    Amount excluding VAT. Should be in cents / minor units. e.g. 1 SEK = 100.

  • currency currency

    Example: SEK, EUR, USD

  • status string

    Possible values: [pending, captured, rejected]

  • sessionId string
  • ]
  • refunds object[]

    Only available when the session is completed.

  • Array [
  • createdAt date

    ISO 8601 format, example: "2023-04-12T13:16:08.647Z".

  • refundId string
  • parentTransactionId string
  • reservationId string
  • pspId string

    Unique UUID identifier ot the payment method.

  • pspDisplayName string

    Localized name of the payment method that is showed to end users.

  • email string
  • reference string
  • amountIncVat amountIncVat

    Amount including VAT. Should be in cents / minor units. e.g. 1 SEK = 100.

  • amountExVat amountExVat

    Amount excluding VAT. Should be in cents / minor units. e.g. 1 SEK = 100.

  • currency currency

    Example: SEK, EUR, USD

  • status string

    Possible 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* boolean
  • orderNote 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 string
  • header string
  • customForm1 object

    Only available when the session is completed. Contains the form data of the custom form module.

  • property name* object
  • value string
  • header string
  • label string
  • terms object

    Only available when the session is completed. Contains data for the checkboxes of the terms module.

  • property name* object
  • value boolean
  • header string
  • strongAuth object
  • provider string
  • output object
  • signedAt string
  • name string
  • surname string
  • givenName string
  • dateOfBirth string
  • validateSigneeIsCompanySignatory boolean
  • signeeIsCompanySignatory string nullable

    Possible values: [unknown, approved, rejected]

  • companyExtraData object
  • output object
  • fields object

    Example: { "score": 50, "netTurnover": 2155 }

    • Loading...