Authentication on merchant's request | ECOMMPAY Documentation

General information

Customer authentication performed by the provider on merchant's request is intended to provide additional security for online payments by payment cards. Such authentication is usually used as a replacement for 3‑D Secure in addition to it. This can be appropriate when the 3‑D Secure authentication is not reliable enough, e.g. when issuers use outdated ways of authentication. Customer authentication on merchant's request implies submitting the validation code, which is contained in the information about the debiting of customer funds. The information is received by the customer in a SMS or a bank statement.

The payment platform supports authentication on merchant's request only for some providers, to enable this authentication a merchant project has to be configured. To do this, contact ecommpay technical support at support@ecommpay.com.

When performing a customer authentication by the payment system on merchant's request, the merchant web service is required to do the following:

receive a callback from the payment platform containing the information about the change of payment status to awaiting merchant auth.
obtain user consent.
send the authentication request.
receive the validation code from the customer.
send the request containing the validation code to the payment platform.

Detailed information on authentication on merchant's request is provided in the sections that follow.

Workflow

Authentication on merchant's request is possible when performing one-step and two-step purchases by payment cards. Information about the necessity of such authentication is contained in callbacks. As a general rule, after receiving a callback a response must be sent to the payment platform. Callbacks contain information about the change of payment status to awaiting merchant auth.

The following scenario must be implemented on the web service side in order to successfully react to such callbacks: the web service must obtain the customer's consent to the authentication, send the authentication request to the payment platform, receive the validation code from the customer, send the request containing code to the payment platform to continue payment processing.

The time-out value for this request is unlimited, taking into account the results of authentication. The overall time of payment processing may not exceed the maximum allowed amount, which is set on the provider's side. If the payment is not successful or declined during this time, it automatically assumes the decline status.

After the payment platform receives the request containing the validation code, the payment processing continues.

Figure 1. Authentication on merchant's request

The payment is processed in the payment platform.
The payment platform sends the callback to the web service informing about the necessity of authentication.
The customer is redirected to the web page containing the information on the authentication.
The user agrees to the authentication.
The web service sends the request for authentication initiation to the specified ecommpay URL.
The payment platform receives the request.
The payment platform processes the request.
The payment platform sends the response with request receipt confirmation and correctness check result to the web service.
The payment platform sends the request for authentication initiation request to the provider service.
The provider processes the request and sends the validation code to the customer.
The customer enters the validation code.
The web service sends the request for authentication completion and continuation of payment processing to the specified ecommpay URL.
The payment platform receives the request.
The payment platform processes the request.
The payment platform sends the response with request receipt confirmation and correctness check result to the web service.
The web service sends the request for authentication completion and continuation of payment processing to the provider service.

The sections that follow discuss in more details the request and callback formats. For general information on how to use the API, see Interaction concepts.

Format of callback informing about the necessity of authentication

The information about the necessity of authentication is contained in a callback, which uses a standard format. For more results, see Callbacks.

The following is the example of a callback, with information about the payment and operation assuming the awaiting merchant auth status before the payment processing request is received.

Figure 2. Example of callback data on the necessity of authentication

{  
  "project_id":42,
  "payment":{  
    "id":"456789",
    "type":"purchase",
    "status":"awaiting merchant auth", // Payment status
    "date":"2019-02-20T15:33:11+0000",
    "method":"card",
    "sum":{  
      "amount":400000,
      "currency":"USD"
    },
    "description":""
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "customer":{  
    "id":"customer_12"
  },
  "operation":{  
    "id":171200003265,
    "type":"sale",
    "status":"awaiting merchant auth", // Operation status
    "date":"2019-02-20T15:33:11+0000",
    "created_date":"2019-02-20T15:33:02+0000",
    "request_id":"617c2626f873151a1cf5873ceb7cca0ade292ee-646d...ec",
    "sum_initial":{  
      "amount":400000,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400000,
      "currency":"USD"
    },
    "provider":{  
      "id":4,
      "payment_id":"3301571985",
      "auth_code":"",
      "endpoint_id":4
    },
    "code":"9999",
    "message":"Awaiting processing",
    "eci":"06"
  },
  "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}

Format of request for authentication initiation

To initiate an authentication on merchant's request a request must by sent to the payment platform by using the POST (HTTP) request to the following endpoint /v2/payment/card/merchant_auth. This request must include the general object, containing general request identification information and request type indicator:

project_id—the project ID obtained from ecommpay
payment_id—payment ID unique within the project
type—indicator of request type, must have the start value
signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification

Thus a correct request must include the project and payment IDs, indicator of request type (start) and signature.

Figure 3. Example of request data on authentication initiation

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "type": "start",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}

Format of request for continuation of payment processing

Taking into account the result of authentication, to continue payment processing a request using the POST (HTTP) method must be sent to the endpoint /v2/payment/card/merchant_auth. The request must contain the following objects and parameters:

Object general—general request identification information:
- project_id—the project ID obtained from ecommpay
- payment_id—payment ID unique within the project
- type—indicator of request type, must have the finish value
- signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
confirmation_code—validation code received from the customer.

Thus a correct request must include the project and payment IDs, indicator of request type (finish), signature and validation code.

Figure 4. Example of request data on continuation of payment processing

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "type": "start",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    },
    "confirmation_code": "835"
}