Create agent assist session

The POST /v1/session endpoint initiates a secure, agent-assisted 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.

In this page

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 the call between the customer and agent. This field is mandatory when the API is called by agent’s backend system. If the API is called client side by the agent’s browser it’s automatically set.

paymentData

Type	Required	Example
Dictionary	True	see example request below

Supplies basic payment data such as card holder’s name, payment amount, currency, etc. The actual contents will 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`

This is an optional field used to select an alternative payment account configuration such as different payment flows or other payment gateways. The account configuration ID is a value provisioned on the VCC account and used to map to payment configurations if the account has multiple.

skipCallTransfer

Type	Required	Example
Boolean	False	`false`

This is an optional field used only for testing purposes that makes testing faster. When the passed value is true then the system will not transfer the call to the payment provider and allow to create a payment session without active call. Default value is false.

Example request

{
    "accountConfigurationId": 1,
    "agentID": agent12345,
    "skipCallTransfer": false,
    "paymentData": {
        "FirstName": "John",
        "Surname": "Smith",
        "Email": "test@wp.pl",
    "Street1": "Hubska 52",
    "City": "Wroclaw",
    "Postcode": "50-348",
    "Country": "GB",
    "Amount": "12.40",
    "Currency": "GBP",
    "MerchantReferenceCode": "0123456789098760"
  }
}

Responses

Responses to the POST /v1/session 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.