Create digital session

The POST /v1/digitalsession endpoint initiates a secure, digital payment session.

Data, including transaction amount, currency and card holder information can be passed in the request body to pre-populate the payment service with data. This accelerates the payment process and prevents the agent from needing to manually collect and enter payment and card holder information.

Headers

Header parameters in Requests (Payment API) apply to this endpoint.

Authorization scopes supported:

Scope	Access granted
`globalpci`	Entire endpoint

Request body parameters

The endpoint accepts the following body parameters:

agentId

Type	Required	Example
String	False	`agent1234`

The agent’s ID that is used to identify which agent created the session. This field is mandatory when the API is called by the agent’s backend system. If the API is called client side by the agent’s browser it’s set automatically.

paymentData

Type	Required	Example
Dictionary	True	see example request

Supplies basic payment data such as card holder’s name, payment amount, currency, and so on. The actual contents depend on the payment gateway used to process the payment and fields that are contracted between the payment service provider and the merchant.

accountConfigurationId

Type	Required	Example
Integer	False	`123`

An optional field used to select an alternative payment account configuration such as a different payment flow or another payment gateway. The accountConfigurationId is a value provisioned on the VCC account and is used to map to a payment configuration if the account has multiple configurations.

Example request

{
   "agentId": "agent12345",
   "paymentData": {
      "FirstName": "John",
      "Surname": "Smith",
      "Email": "test@wp.pl",
      "Street1": "Hubska 52",
      "City": "Wroclaw",
      "Postcode": "50-348",
      "Country": "GB",
      "Amount": "12.40",
      "Currency": "GBP",
      "CustomerPhoneNumber": "+48500000000",
      "MerchantReferenceCode": "0123456789098760"
   }
}

Responses

Responses to the POST /v1/digitalsession return a collection of data including the session identifier, PCI payment session identifier, and data used to open the payment UI iframe.

Successful response

Success response code and parameters apply to a successful response.

Example response

{
   "sessionGuid": "c97f86c0-4586-4ba6-adc7-e0072f7f1601",
   "agentAccessToken": "eyJ0...Nvtr",
   "agentRefreshToken": "f9d8...c999",
   "iframeUrl": "https://<payment host URL>/view/59aab1be-d652-426e-a7a8-1bf4ca15e2ab/framed",
   "providerSessionGuid": "59aab1be-d652-426e-a7a8-1bf4ca15e2ab"
}

Each response contains the following parameters:

sessionGuid. This is the unique payment session identifier within the VCC system. This GUID can be used by the backend system to query for payment status.
agentAccessToken, agentRefreshToken, iframeUrl. A set of data used to open the payment UI IFrame or pop-up on the agent’s desktop and authorize access to the secure session.
providerSessionGuid. The globally unique identifier of the PCI payment provider session.