After the payment is initiated it can be processed using the endpoint described on this page.

The processing works like a state machine, i.e your system needs to react based on content of the response (status and step fields). The order of steps in the flow is bank-specific.

Endpoint details (postman documentation): Process single payment

Request

PATCH {{everifin_api_url}}/v1/payments/single/{{payment_id}}

Headers

Request to Process Order Payment endpoint must contain following headers:

Header	Type	Optional	Description
Authorization	Bearer token	no	Authorization token to access API.
x-ef-sender-ip	IP address	no	IP address of your user.
x-ef-sender-user-agent	text	no	Your user`s user agent identification. A valid user agent must be provided, i.e. containing operation system info etc.
x-user-data-encryption-method	text	yes	Method of sensitive data encryption. Send this header, if you are encrypting e.g. user’s credentials. Currently, only supported method is RSAES-OAEP/SHA-256.

Body

The set of required inputs (data that needs to be provided in body of this request) depends on the bank of the payment sender. Client of this API must react to requested inputs that are specified in the responses of this endpoint.

Also, in steps where query parameters are present in redirect towards the integrator (e.g. return from the bank), integrator needs to provide these parameters in body of the payment process request.

To protect sensitive user’s data from being misused, these must be sent in an encrypted form:

userId
userPassword
otp (one-time-password)

The data must be encrypted by client. At the moment, we also accept un-encrypted data during the transition period. For more instructions on how to encrypt data, see specific section further below.

Response

Field	Type	Optional	Response type	Description
id	number, unique	no	All	Payment id, which will be used for the next communication
status	enum	no	All	Status of the payment. Possible statuses are described below in separate table.
type	enum	yes	All	Processing flow step type (given by specific bank): REDIRECT - you should redirect to redirectUrl INPUT - some user input is required NEXT - if status is CONFIRMED/BOOKED or FAILED, processing is done and there is nothing else to do. Otherwise you should call process endpoint. PUSH - waiting for the confirmation of PUSH notification (no action required but status needs to be checked after some time by calling this endpoint). Payer needs to handle the push notification in the mobile device.
redirectUrl	text	yes	REDIRECT	The URL for redirect (only for REDIRECT response types)
inputSet	InputObject[]	yes	INPUT	Array of input objects required for next processing. Values from this set has to be displayed to the user, so she/he can enter or select required values.
input	InputObject	yes	INPUT	Input object required for next processing. Input has to be displayed to the user, so she/he can enter or select required value. Response might contain this field, if only one input is requested. If multiple inputs are requested, response contains inputSet field.
inputsToEncrypt	string[]	yes	INPUT	List of inputs to encrypt, if sensitive user’s data are required in input or inputSet. These inputs must be encrypted in the request body.
inputEncryptionConfig	InputEncryptionConfig	yes	INPUT	If response contains inputsToEncrypt, this field specifies encryption method and encryption key.
Input Object
type	enum	no	INPUT	Type of the input: TEXT - user has to enter some text, e.g. username, sms code etc. PASSWORD - user has to input his bank password BOOLEAN - user has to give consent to some action SELECT - user has to select an option IMAGE_SCAN - user has to scan some image into his mobile app, e.g. QR IBAN - user has to enter his IBAN Based on this field you can set the UI for the user like html input types and validation.
name	text	no	INPUT	Name of the input to identify it by Everifin system. This name must be returned back together with the value the user has provided.
selectOptions	SelectObject[]	yes	INPUT	Only for SELECT input type. User has to select one of offered options.
image		yes	INPUT	Only for IMAGE_SCAN input type. User has to scan the image into his mobile banking app.
Select Object
name	text	no	INPUT	Name of the select option.
value	text	no	INPUT	Value of the select option.
InputEncryptionConfig
encryptionKey	string	no	INPUT	Public key for data encryption.
encryptionMethod	string	no	INPUT	Method of data encryption. Currently, only supported value is RSAES-OAEP/SHA-256.

Example for redirect response type:

200:
{
    "meta": {
        "status": "SUCCESS"
    },
    "data": {
        "id": "12",
        "status": "CREATED",
        "redirectUrl": "http://app.everifin.com/api/v1/ef/router?state=a51048c5f5f4487c935d70cc058d46ed",
        "type": "REDIRECT"
    }
}

Example for input response type:

200:
{
    "meta": {
        "status": "SUCCESS"
    },
    "data": {
        "id": "12",
        "status": "CREATED",
        "type": "INPUT",
        "inputSet": [
            {
                "type": "IBAN",
                "name": "senderIban"
            }
        ]
    }
}

More examples of responses can be found in separate page dedicated to bank SCA flow types and also in Postman documentation in the Examples dropdown .

Sensitive data encryption

As described before, sensitive user’s authentication data (userId, userPassword, otp) must be encrypted before sent to Everifin Paygate via API. To encrypt data correctly, follow these steps:

When response type is INPUT, we might require user to provide his credentials to bank or OTP code. Check value of response field inputsToEncrypt. This array contains list of inputs, which must be encrypted. If this array is present and non-empty, proceed to next step.
Ask the user to provide these values. Before sending these values from the browser, encrypt each input using public key contained in inputEncryptionConfig.encryptionKey and algorithm specified in inputEncryptionConfig.encryptionMethod. Then, encode the encrypted byte-array value into a hexadecimal string. See further for an example.
Send the response with header x-user-data-encryption-method: RSAES-OAEP/SHA-256 and the encrypted values in the body.

Currently, only RSA encryption using SHA-256 hash with OAEP padding is supported.

Examples

This example illustrates, how to encrypt the data using javascript library node-forge:

let publicKey = '-----BEGIN CERTIFICATE-----<...value from encryptionKey...>-----END CERTIFICATE-----';
let input = 'password123';

let encryptionKey = forge.pki.certificateFromPem(publicKey).publicKey;
let encryptedValueBytes = encryptionKey.encrypt(input, 'RSA-OAEP', { md: forge.md.sha256.create() });
let encryptedValueHex = forge.util.createBuffer(encryptedInput).toHex();

Example response from Everifin, specifying encryption requirements might look like this:

{
    "id": "12",
    "status": "PROCESSING",
    "type": "INPUT",
    "inputSet": {
        "0": {
            "name": "userId",
            "label": "LABEL_INPUT_USER_ID",
            "type": "TEXT"
        },
        "1": {
            "name": "userPassword",
            "label": "LABEL_INPUT_PASSWORD",
            "type": "PASSWORD"
        }
    },
    "inputMessage": "MSG_INPUT_BANK_CREDENTIALS",
    "description": "DESC_INPUT_LOGIN_TO_BANK",
    "inSessionProcessingFinished": false,
    "inputsToEncrypt": [
        "userId",
        "userPassword"
    ],
    "inputEncryptionConfig": {
        "encryptionKey": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
        "encryptionMethod": "RSAES-OAEP/SHA-256"
    }
}

In this response, encryption of userId and userPassword is required. Each of these inputs should be encrypted separately and then sent in following request, e.g.:

{
  "userId": <ciphertext>,
  "userPassword": <ciphertext>
}

Transition period

During transition period, we accept also unencrypted user inputs. Before you implement encryption on your side, do not send the header x-user-data-encryption-method in your request, so that we know the data are not encrypted. After transition period is over, we will not accept unencrypted sensitive user data.

Payment statuses

During the payment process the payment changes its status. These are the possible status values.

Status	Final	Description
CREATED	no	Payment is created and waiting for further processing.
PROCESSING	no	The payment is being processed (user is authorizing payment on bank`s page or authorization is finished and payment is being further processed by the bank).
FINISHED	yes	The payment has been successfully authorized in the bank by the payer.
FAILED	yes	Payment has failed.

Single Payment Processing