Submission of additional payment information

Overview

Normally, when performing payment, mandatory parameters that are required to initiate the payment provide enough information. A payment system or the payment platform may require your web service to submit some optional parameters that otherwise are not required, this may be due to regional or country-specific requirements or additional fraud testing procedures. The additional payment information submission procedure implemented on the payment platform allows you to handle these cases. When performing the procedure, the payment platform require your web service to provide additional mandatory data and waits for the data to be submitted. Also, the payment platform is flexible as to the ways this additional information is requested and accepted from the web service.

Additional information the payment platform requests typically concerns the customer and the payment method. If the payment is performed by using payment cards, the payment platform may request the parameters of the avs_data—Address Verification Service requirements, AVS—or any parameters of the customer objects. If the payment is performed by using alternative payment method, the payment platform may request any optional parameters of the initial payment request.

If you provide all the mandatory and optional parameters in each payment initiation request, you will never be required to submit additional information. Otherwise, you should implement the scenario in which during the payment processing, the payment platform requests additional information and you submit the information.

The following sections provides more details about the workflow.

The workflow

The payment platform or provider, as well as a payment system may require additional payment information.

There are two ways the payment platform requests any additional information: callbacks and responses. Normally, the payment platform requests additional data in callbacks; in which case you are not required to issue any additional requests. Alternatively, you can issue a request for payment status and have the payment platform respond with a response that specifies what additional information is required.

Then, the web service needs to generate and send the request that contains additional information. After the payment platform discovers that additional information is required, it waits for submission of the additional information for 30 minutes. If the payment platform does not receive the request with the additional information within these 30 minutes, the payment is automatically declined. Although, your web service can resend the request with partial or even empty additional data, in this case, the 30-minutes time-out is reset. This way, you can prolong payment processing, if you need more time to collect all the additional data. Note though, that you can not prolong payment processing beyond the payment processing threshold.

The parameter set inside the request body may vary—you can specify all the parameters, part of the parameters, or no parameters at all, but you always must specify the additional_data object inside the request. If the request the payment system receives does not contain the object, the payment system considers the request incorrect and sends an error response. If the request contains all the required parameters, the payment platform responds with the 200 OK response. If the request contains the additional_data object with no the required parameters or only a part of required parameters, the payment platform responds with a callback or a response that lists with the rest of the required parameters.

As soon as the payment platform obtains all the required information, the payment platform continues to process payment.

During interaction with the payment platform, your web service is required to do the following:

  1. Receive a callback or a response with the clarification_fields object that lists the required parameters.
  2. Send the request that contains all the required objects and parameters including the additional_data object and signature to the /v2/payment/clarification endpoint by using POST HTTP method.
  3. Receive and handle the 200 OK response.

The payment platform responds with the 200 OK response when payment platform receives all the required parameters with correct values. If not, the payment platform requests additional data again starting at step 1.

The information about the format of a callback and a response that may list with parameters and the request format are covered in greater details below.

Callback and response format

There are two ways the payment platform requests any additional information: callbacks and responses to a request for payment status.

The callbacks that the payment platform sends to request additional payment information use the standard format described in Callbacks. Note that in this case, the callbacks contain the clarification_fields object that lists with required parameters. The following is the example of the callback that is used to request the customer postal code and address that AVS requires when payment processing by using payment card.

Figure 1. Callback
POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: example.com

{
    "sum_request": {
        "amount": 45000,
        "currency": "USD"
    },
    "request_id": "80bdc0831c3f8e1",
    
    "payment": {
        "id": "",
        "method": "card",
        "date": "2019-07-29T11:19:33+0000",
        "result_code": "9999",
        "result_message": "Awaiting processing",
        "is_new_attempts_available": false,
        "attempts_timeout": 0,
        "provider_id": 3
    },
    "sum_real": {
        "amount": 45000,
        "currency": "USD"
    },
    "status": "awaiting clarification",        // The payment status
    "customer": {
        "id": "4314220000000056"
    },
    "account": {
        "number": "431422******0056",
        "type": "visa",
        "card_holder": "JUDY DOE",
        "expiry_month": "03",
        "expiry_year": "2021"
    },
    "clarification_fields": {                  // The additional information requested
        "avs_data": [
            "avs_post_code",
            "avs_street_address"
        ]
    },
    "general": {
        "project_id": 11,
        "payment_id": "EPr-bf14",
        "signature": "99q4lpCEuNpxp3ugvxF1qPbinWUIwNSLaxcVbF0A=="
    },
    "description": "",
    "operations": [
        {
            "id": 7282148104130,
            "type": "sale",
            "status": "awaiting clarification",
            "date": "2019-07-29T11:19:33+0000",
            "processing_time": null,
            "sum": {
                "amount": 45000,
                "currency": "USD"
            },
            "code": "9999",
            "message": "Awaiting processing"
        }
    ]
}

The responses that the payment platform sends to request additional payment information use the same format that the callbacks use. The following is the example of the response to the request that a merchant web service sends to the /v2/payment/status endpoint. The response is used to request the customer email, first and last name, billing address, and the day of birth.

Figure 2. Response
HTTP/1.1 200 OK                       
Server: api.com
Date: Wed, 29 July 2019 09:27:45 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 875
Connection: keep-alive
Keep-Alive: timeout=60
Cache-Control: no-cache
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Origin: *
X-Powered-By: PHP/7.0.32
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,
X-Requested-With,If-Modified-Since,Cache-Control,Content-Type

{
    "sum_request": {
        "amount": 500,
        "currency": "CNY"
    },
    "request_id": "563c42d4846d105e77",
    "payment": {
        "method": "cup-card",           
        "date": "2019-07-29T09:27:45+0000",
        "result_code": "9999",
        "result_message": "Awaiting processing",
        "status": "awaiting clarification",      // The payment status
        "is_new_attempts_available": false,
        "attempts_timeout": 0,
        "id": "E2E_01_0868",
        "cascading_with_redirect": false,
        "provider_id": 1145
    },
    "sum_real": {
        "amount": 500,
        "currency": "CNY"
    },
    "customer": {
        "id": "7826"
    },
    "clarification_fields": {                     // The additional information requested
        "customer": [ 
            "email",
            "first_name",
            "last_name",
            "billing.address",
            "billing.city",
            "billing.country",
            "billing.postal",
            "day_of_birth"
        ]
    },
    "general": {
        "project_id": 245,
        "payment_id": "E2E_01_0868",
        "signature": "MYiga7aoW0UBFBfeTdIiF0QFOokEfyuSA=="
    },
    "description": "",
    "operations": [
        {
            "id": 1315207090506,
            "type": "sale",
            "status": "awaiting clarification",
            "date": "2019-07-29T09:27:45+0000",
            "processing_time": null,
            "request_id": "563c42d4846d105e77",
            "sum": {
                "amount": 500,
                "currency": "CNY"
            },
            "code": "9999",
            "message": "Awaiting processing"
        }
    ]
}

Request format

Your web service needs to submit the requested additional payment information in a request to the /v2/payment/clarification endpoint by using POST HTTP method. The request must contain the following:

  • general—object that contains general request identification information:
    • project_id—the project ID obtained from ecommpay
    • payment_id—payment ID unique within the project
    • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
  • additional_data — object that contains additional payment information that payment platform requests. The object may list all the parameters, part of the parameters, or no parameters at all.
    Note: The interface_type object is optional.

Thus, a correct request must include project and payment IDs, signature and additional payment information. In the following example, the requested additional information includes the customer postal code and address that the payment platform requests in the callback example above.

{
  "general": {
    "project_id": 11,
    "payment_id": "EPr-bf14",
    "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...=="
  },
  "additional_data": {
    "avs_data":{
        "avs_post_code": "99546",
        "avs_street_address": "01 Main Street, CA"
    }
  }
}

The following is the example that contains two request bodies. In this way, a merchant web service prolongs payment processing, when it needs more than 30 minutes to collect all the additional data. In the example, a merchant web service sends the first request with empty additional data just to prolong payment processing. Then, a merchant web service resends the request with all the requested additional data that includes the customer email address, first and last name, billing address and date of birth that the payment platform requests in the response example above.

// The request body that the merchant web service sends
// to prolong the payment processing.
{
    "general": {
        "project_id": 245,
        "payment_id": "E2E_01_0868",
        "signature": "5uco0y4eeTdf59R/1SQXdfepidfw=="
    },
    "additional_data": {
    }
}

// The request body that the merchant web service sends
// to submit the additional information the payment system requests.

{    
    "general": {
        "project_id": 245,
        "payment_id": "E2E_01_0868",
        "signature": "5u5468co0fgfgfg/1fgfSfggdffg=="
    },
    "additional_data": {
        "customer": {
            "email": "test@testmail.com",
            "first_name": "杨",
            "last_name": "思荣",
            "billing": {
                 "address": "和飞机的事",
                 "city": "市区-东城区",
                 "country": "CN",
                 "postal": "156114"
            },
            "day_of_birth": "12-12-1990"
        }
    }
}