Vality Payments API (2.0.1)

API is designed for the merchants who accept payments via user interface such as a website or a mobile app and it is the only interaction point with the system for goods and services payment transactions.

Whenever an API is accessed, its unique ID must be passed in the header X-Request-ID of the corresponding request:

 X-Request-ID: 37d735d4-0f42-4f05-89fa-eaa478fb5aa9

Content type and coding

The system accepts and returns data in JSON format and UTF-8 coding:

  Content-Type: application/json; charset=utf-8

Date formats

The system accepts and returns timestamp values in the format date-time, described in RFC 3339:

  2017-01-01T00:00:00Z
  2017-01-01T00:00:01+00:00

Maximum request processing time

Whenever an API is accessed, the time cutoff parameters, that define maximum request processing time of the transaction completion, can be passed in the header X-Request-Deadline of the corresponding request:

 X-Request-Deadline: 10s

The system stops processing the request upon the specified time. It is recommended to specify a value that is not more than one minute and not less than three seconds. X-Request-Deadline can be:

• specified in the format date-time according to RFC 3339;
• specified in relative values: in milliseconds (150000ms), in seconds (540s) or in minutes (3.5m).

A system party is a data set about your company, structure and conditions of concluded contracts, and also the information about the shops associated with the company.

A shop is a display of your website or a point of sales in the system. Financial terms, that determine, particularly, the system fee percentage, are linked to the shop. Each shop has its linked accounts that accumulate money sent by payers. Only one account can be in each currency. The shop category is determined by the group of offered goods and services. A banking terminal can be linked to a shop on the side of an acquiring bank. Any changes of these shops require system verification. Shops created in the test category are used for test payment. The system creates a test shop automatically during the participant registration. Your website or point of sales may have more than one shop. The closest analogue can be POS-terminals at a point of sales.

It is possible to specify a URL for any shop to receive asynchronous notifications about data status change by setting up webhook. For example, you can set up webhook by specifying URL of your application to which the system will send data about invoice changes. The corresponding public key, created during the webhook setup, is used to verify integrity of data sent to your application URL. You can receive this key in your account.

An invoice is a fundamental model for work with payment acceptance system. It is necessary to create an invoice and find out its ID before rendering the payment form launching debit transactions, holding funds on the payer’s card and launching other similar business processes. In general, an invoice is a container for payments, data about goods and a shop. Invoices have customizable limited lifetime. Once lifetime is expired, invoice status is impossible to change.

Table of invoice statuses:

Invoice statuses are indicated in the diagram nodes, narrows are marked by the processes. Successful completion of processes generates change from one status to another.

The system provides you a possibility to fill and save any necessary metadata both in invoice and payment pattern. Data is described by the JSON array. Later the system will provide this data to you when you request invoice or payment data by its ID or it will send it to webhook in asynchronous mode that is set up for the relevant shop if there is one.

Any data status changes generate events. You can receive a full list of events that led to the specific data status or the latest event that describes the current data status. For example, you can request all events or the latest one within the specified invoice ID to find out an invoice status so that to make a decision about the shipment of goods or providing services to the payer.

Operations:

• invoice creation,
• invoice cancellation,
• invoice fulfillment,
• getting a new invoice access token (after invoice creation)

are authorised with your API key.

Invoice access token

The invoice access token authorises a limited amount of transactions needed to make payments by the specified invoice, in particular:

• tokenization of payment instrument,
• payment creation by this and only this invoice,
• getting the invoice status.

The token is valid for 3 days from the creation. After this it will be impossible to use it to authorise transactions.

You can specify the distribution of funds among several shops within one invoice. If necessary, you can add a fee that will be charged to the shop specified during the invoice creation (hereinafter invoice shop). Total amount of all distribution transactions shouldn’t exceed the invoice amount. There shouldn’t be more than one transaction per one shop in the distribution. The distribution transactions can be:

• With AllocationBodyAmount body which transmits the amount to be transferred to the shop. You must create a transaction in favour of an invoice shop to add a fee.

• With AllocationBodyTotal body which transmits the total amount of transactions and its fee that can be:

  • AllocationFeeFixed or fee amount in favour of an invoice shop.

  • AllocationFeeShare or some percent of the total amount of transaction in favour of an invoice shop.

Invoice templates make invoicing easy. An invoice template is linked to the shop and contains specification that can be used for invoice creation by specifying the cost of goods and services and/or invoice metadata. If a template contains the fixed cost, it can be removed during invoice creation. If invoice metadata is not specified when an invoice is created by a template, they will be taken from a template (if metadata is contained in a template).

The creation, update and deletion of an invoice template doesn’t require the system verification and requests for these changes.

The creation, update and deletion of an invoice template is authorised by your API key.

Invoice template access token

An invoice template access token is created in the result of template creation transaction. It authorises:

• the getting of invoice template by its ID,
• invoice creation by the template.

The actual debiting the payer’s funds is made by calling of payment creation method. Before payments the invoice, within which the system will attempt to debit, has to be created and payer’s payment token has to be specified. This way the system provides you an interface that allows your server code to initiate and control the debiting process. This process can be both synchronous, when you are waiting for system response, and asynchronous, when you are waiting for notifications on the webhook set up for the corresponding shop after the payments are launched.

The system provides two payment methods: one-step and two-step, PaymentFlowInstant and PaymentFlowHold. One-step payment (PaymentFlowInstant) is performed by calling of one API method. The result of it is authorisation and further debiting in favour of a shop within one transaction. Two-step payment (PaymentFlowHold) means the call of two methods: one for authorisation and one for debiting. After the successful authorisation the transaction amount will be blocked on a payer’s account so a payer can’t use it. The debiting (capturePayment) can be confirmed on equal or less authorisation amount. If the less amount is specified, the balance will be refunded to a payer. The successful authorisation can be confirmed or cancelled both manually by calling the corresponding API method (capturePayment or cancelPayment) and automatically according to the chosen strategy onHoldExpiration. The manual confirmation period is set in the system settings by yourself and it is usually from 3 to 7 calendar days.

The system ensures the idempotency of debiting funds from payment instrument by providing the unique payment session ID. This ID is provided during the creation of payment instrument tokens and guarantees the idempotency of debit requests, providing the protection from erroneous repeated debits.

When the payment is created within the system, you can set up the payment processing time in the field processingDeadline. When it is expired, the system is trying to stop processing the payment and changing its status to failed with the error processing_deadline_reached.

Processing time limit should be considered as a recommendation as the system can fail to stop processing on the basis of the payment instrument and the current payment status. If a field value is not set up, the system will choose it by itself to have enough time for payment transfer in general conditions.

Payment processing time limit, similarly to the header X-Request-Deadline, can be specified in format described in RFC 3339 or in relative values.

Payment request APIs are authorised by an invoice access token that is used to create the payment or by API key.