Create order

Every payment on the Viva Wallet platform needs an associated payment order. A payment order is represented by a unique numeric orderCode.

Request information

POST /api/orders

Authentication

This API call uses Identity Server authentication.

Parameters

Amount (int64): The amount requested in cents (amount in euros x 100). E.g. If you want to create a payment for €100.37, you need to pass the value 10037. The amount must always be greater than 30 cents (which is the minimum amount you can charge with Viva Payments).

A number of optional parameters are supported.

Sample request

{
  "Tags": [
    "sample string 1",
    "sample string 2",
    "sample string 3"
  ],
  "Email": "customer@domain.com",
  "Phone": "2117604000",
  "FullName": "Customer Name",
  "PaymentTimeOut": 86400,
  "RequestLang": "en-US",
  "MaxInstallments": 12,
  "AllowRecurring": true,
  "IsPreAuth": true,
  "Amount": 1000,
  "MerchantTrns": "Your reference",
  "CustomerTrns": "Description that the customer sees"
}

Response information

OrderCode (int64): The OrderCode is your unique Payment Order ID. This is now all that is required by Viva in order for the payment to be completed.

ErrorCode (int32): If the call is not successful, an error code is generated. For successful calls the value 0 is returned.

ErrorText (string): If the ErrorCode is not 0, a descriptive error message is returned.

TimeStamp (datetime): The server date and time that the Payment Order creation was completed in ISO 8601 format.

Sample response

{
  "OrderCode": 175936509216,
  "ErrorCode": 0,
  "ErrorText": "",
  "TimeStamp": "2012-12-24T15:23:21.6871106+02:00"
}

Optional parameters

The following optional parameters can be passed and are supported when creating an order via the API.

ParameterTypeValidationDescription
IsPreAuthbooleanA value of true will perform a PreAuth transaction. This will hold the selected amount as unavailable (without the customer being charged) for a period of time. Default value is false. PreAuth transactions done with a debit card or credit card, hold the balance as unavailable either until the merchant clears the transaction, or the hold 'falls off.' In the case of debit cards, authorisation holds can fall off the account (thus rendering the balance available again) anywhere from 1–5 days after the transaction date depending on the issuing bank's policy; in the case of credit cards, holds may last as long as 30 days, depending on the issuing bank.
ServiceIdint32If you wish to create a Payment Order without redirecting the customer to the payment page, use this parameter with value 4. The system will automatically send your customer an e-mail notification. This is equivalent to the Payment Notification option from the merchant environment.
RequestLangstringIf no parameter is passed, the system assumes el-GR. The payment form is currently displayed in the English language for all values other than el-GR.The language (in ISO format) that the payment form is displayed. This parameter is also included in the target URL the application uses to redirect the user after the successful/unsuccessful completion of a payment.
FullNamestringThe cardholder's full name, in order to be filled in on the payment form.
EmailstringThe cardholder's e-mail address, in order to be filled in on the payment form.
PhonestringThe cardholder's telephone number, in order to be filled in on the payment form.
MaxInstallmentsintAcceptable values 1 to 36.The maximum number of installments that the cardholder can choose for this transaction. If this parameter is omitted, the cardholder will not see an option for selecting number of installments.
MerchantTrnsstringThe maximum length of this parameter is limited to 50 characters.This can either be an ID or a short description that helps you uniquely identify the transaction. For example, this can be your customer order reference number.
CustomerTrnsstringThe maximum length of this parameter is limited to 255 characters.This optional parameter adds a friendly description to the payment order that you want to display to the cardholder on the payment form. It can either be your customer order code or a short description of items/services purchased.
SourceCodestringSourceCode is case-sensitive.Sources can be created and managed from the merchant's profile. A source is used for grouping and filtering transactions (ie a merchant may have more than one websites, or different product categories).
PaymentTimeOutint32By default, the life span of every Payment Order is 300 seconds (5 minutes). This is the time given to the cardholder to complete an online payment. If the cardholder does not complete the payment within the given time frame, the Payment Order is automatically cancelled. By using this parameter, you can define a different life span for your Payment Order.
ExpirationDatedatetimeValue is in seconds and can be either smaller or greater than 300 secs. Use value 65535 if you want your Payment Order to never expire.Same as PaymentTimeOut but expressed in absolute datetime in ISO 8601 format. Note that if set, ExpirationDate overrides the PaymentTimeOut option.
AllowRecurringbooleanCardholder’s consent is required in order to be able to perform Recurring Payments. AllowsRecurring also works.If this parameter is passed with value true, the payment form asks the cardholder to optionally accept recurring payments from the merchant. Default value is false.
Tagsstring arrayYou can add several tags to a transaction that will help in grouping and filtering from your merchant profile.
ActionUserstringThe username that initiated this action, used optionally for your own logging purposes.
DisableIVRbooleanIf this parameter is passed with value true, the customer will not have the option to pay over the phone (IVR).
DisableCashbooleanEven if this option is set and the E-Banking/Phone banking options will not be displayed, the customer will still be able to make a payment from these channels if they know how to use the Viva Payments Order Code from their e-banking environment. In order for the Cash tab to be available, the PaymentTimeOut option should also be at least one hour.If this parameter is passed with value true, the customer will not have the option to pay in cash at a Viva Spot, and the checkout page will not display the Cash and E-Banking/Phone banking options. Default value is false.
DisableCardbooleanIf this parameter is passed with value true, the customer will not have the option to pay by (credit, debit or prepaid) card, and the checkout page will not display the Card payment option. Default value is false.
DisablePayAtHomebooleanIn order for the Pay@Home tab to be available the PaymentTimeOut option should also be at least two working days.If this parameter is passed with value true, the customer will not have the option to pay using the Pay@Home service.
DisableWalletbooleanIf this parameter is passed with value true, the customer will not have the option to pay using his Viva Wallet. Default value is false.
DisableExactAmountbooleanIf this parameter is passed with value true, the Order can accept any amount, irrespective of the RequestAmount option. It will also allow multiple payments to be performed for the same Payment Order.