Viatel AgentLine Checkout

Introduction
Viatel provides a payment solution where merchants can sell services online to end-users.

Endpoint
The API has the following base end-points in stage and production:

Environment URL

Stage https://stage-checkout.viatel.se

Production https://checkout.viatel.se

Parameters must be sent using method POST.

ValidateCredentials

POST /api/v1/AgentLine/ValidateCredentials

When the merchant saves the settings, a backend request should be sent to validate that the MerchantId and API
Key was given correctly. The request must be sent to the environment for which it is specified (production or
stage).

Input Parameters

Parameter Datatype Description Value Mandatory

MerchantId int Identifies the payment flow. From Settings Yes

Nonce int64 The value must increase for each purchase. Take Ticks, number of Yes
(long) milliseconds since 1970.

Verification string Hash calculated over selected parameters with the API Yes
Key to make sure the request is untampered.

Result

HTTP Status Code Description

200 OK Credentials are correct

401 Unauthorized Credentials are not correct

500 Server Error Unexpected error, please contact support

Calculation of the parameter Verification
The parameter Verification is a MAC (Message Authentication Code) based on values for some of the
parameters. Each parameter-value is concatenated with the &-sign as a delimiter. The purpose is to make sure
the request is untampered and that the request is sent from a sender knowing the API-key.

Verification is calculated using SHA256 according the following formula:

Base64(SHA256(UTF8Bytes(MerchantId&Nonce&ApiKey))

Request Example

POST https://stage-checkout.viatel.se/api/v1/AgentLine/ValidateCredentials HTTP/1.1

Content-Type: application/json
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Host: stage-checkout.viatel.se
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 117
{
"MerchantId": 11021,
"Verification": "vcZ85UzciBHE0ApDjoXLDkJtmXUwRvVBwpk02Tutwm4=",
"nonce": 100
}

Coding example in C#

using (var algorithm = SHA256.Create())

hash = Convert.ToBase64String(
algorithm.ComputeHash(
Encoding.UTF8.GetBytes(
string.Join("&",
merchantId.ToString(),
nonce.ToString(),
secret))));

CreateOrder
POST /api/v1/AgentLine/CreateOrder

When the end-user clicks his/her preferred purchase-button, a request should be made to Viatel’s API which will
return an HTML snippet that should be displayed to the end-user.

Input Parameters

Parameter Datatype Description Value Mandatory

MerchantId int Identifies the payment flow. From Settings Yes

Viatel Sweden AB I Viatel AgentLine Checkout Page 2/5

 Parameter Datatype Description Value Mandatory

OrderId string(15) Order number that the merchant can use to Set the value to Yes
connect the purchase in their own CRM system. MerchantId + “-” +
The value doesn’t need to be unique. Nonce

AccountNumber string The account to be used. If the value is “0”, a new From Form Yes
account will be created.

Amount int Amount to be paid and specified in minor units From Widget Yes
according to ISO 4217, e.g. 100 is set as 10000. (the value should be
multiplied by 100)

Value int The amount to be deposited to the end- From Widget (if set) No
user. Specified in minor units exactly like Amount. (the value should be
multiplied by 100)

Currency string Currency code, e.g. SEK or EUR, according to From Widget Yes
ISO 4217

OrderText string Text description for the purchase and is shown on From Widget No
the payment page and on the confirmation page.

ApproveTopUp boolean The end-user’s approval to allow topup. From Form Yes

ApproveAutomaticTopUp boolean The end-user’s approval to allow automatic topup From Form Yes
when the account is out of balance.

Name string The end-user’s name. Used in the payment From Form No
confirmation and for customer service.

Email string The end-user’s e-mail address. Used in the From Form No
payment confirmation and for customer service.

PhoneNumber string The end-user’s phone number, e.g. From Form No

46701234567. Used in the payment confirmation
and for customer service.

ConfirmationPage boolean Specifies if a confirmation page should be From Settings No

displayed with the possibility to receive a text
message an e-mail as payment confirmation.
Default is 1.

SuccessURL string URL the end-user will be redirected to after a From Settings No
successful payment or when the end-user clicks
the button on the payment confirmation page.

CancelURL string URL the end-user will be redirected to if the end- From Settings No
user chooses to cancel the payment.

Locale string Language code specified by 2-characters From Widget No

language code and 2-characters country code
according to RFC 1766, e.g. sv-se. Default is en-
us.

Extra string Value being forwarded in SuccessURL and From Widget No

CancelURL.

Nonce int64 The value must increase for each purchase. Take Ticks, number Yes
(long) of milliseconds since
1970.

Verification string Hash calculated over selected parameters with Yes

the API Key to make sure the request is
untampered.

Viatel Sweden AB I Viatel AgentLine Checkout Page 3/5

Output parameters

Parameter Datatype Description

ResultCode int Specifies if the request was successful, or an error code specifying the reason for the failed request.
Positive value (>=0) means request was successful, otherwise means the request failed.

ResultCode Description

100 Successful

-100 Error creating a payment towards the PSP

-300 Database error

Message string Message when the request was not approved.

SessionId int Viatel’s unique id for the payment.

HTML Snippet string The HTML to be displayed to the end-user.

Calculation of the parameter Verification

The parameter Verification is a MAC (Message Authentication Code) based on values for some of the
parameters. Each parameter-value is concatenated with the &-sign as a delimiter. The purpose is to make sure
the request is untampered and that the request is sent from a sender knowing the API-key. Boolean parameters
should be converted to lowercase strings “true” or “false”.

Verification is calculated using SHA256 according the following formula:

Base64(SHA256(UTF8Bytes(MerchantId&AccountNumber&Amount&Value&Currency&ApproveTopUp
&ApproveAutomaticTopUp&SuccessURL&CancelURL&Nonce&ApiKey))

Request Example

POST https://stage-checkout.viatel.se/api/v1/AgentLine/CreateOrder HTTP/1.1

Host: localhost:44305
Accept: application/json, text/json, text/x-json, text/javascript, application/xml,
text/xml
User-Agent: RestSharp/106.11.4.0
Connection: Keep-Alive
Accept-Encoding: gzip, deflate
Content-Type: application/json
Content-Length: 457
{
"MerchantId":11021,
"OrderNumber":null,
"AccountNumber":null,
"Amount":100,
"Value":10000,
"Currency":"SEK",
"Locale":"sv-se",
"OrderText":"OrderText",

Viatel Sweden AB I Viatel AgentLine Checkout Page 4/5

 "CancelUrl":null,
"SuccessUrl":"https://stage-checkout.viatel.se/v1/Example/Success",
"Verification":"F2H5QTXf4sgIqCkWUvuF6nYVH2qfMunzUMEZXEGr11Y=",
"Nonce":11,
"Name":null,
"Email":null,
"PhoneNumber":null,
"ApproveTopUp":true,
"ApproveAutomaticTopUp":true,
"Extra":null,
"VATAmountIncluded":null,
"ConfirmationPage":true
}

Coding example in C#

using (var algorithm = SHA256.Create())

hash = Convert.ToBase64String(
algorithm.ComputeHash(
Encoding.UTF8.GetBytes(
string.Join("&",
merchantId.ToString(),
accountNumber.ToString(),
amount.ToString(),
value.ToString(),
currency.ToString(),
approveTopUp ? "true" : "false",
approveAutomaticTopUp ? "true" : "false",
successUrl ?? "",
cancelUrl ?? "",
nonce.ToString(),
secret))));

The values for approveTopUp and approveAutomaticTopUp in the MAC calculations should be set as "true" and
"false".

Viatel Sweden AB I Viatel AgentLine Checkout Page 5/5