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.

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 Handling callbacks. Note that in this case, the callbacks contain the clarification_fields object that lists with required parameters.

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
{
  "project_id": 200,
  "payment": {
    "id": "abc12345",
    "type": "purchase",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "method": "Greek Banks",
    "sum": {
      "amount": 1000,
      "currency": "EUR"
    },
    "description": "Success"
  },
  "customer": {
    "id": "123"
  },
  "clarification_fields": {                  // The additional information requested
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the customer's consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The text to be displayed on the payment form",
          "default": "The consent text to be displayed to the customer"
        }
      }
    }
  }
  "operation": {
    "id": 9529253065607,
    "type": "sale",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "created_date": "2025-03-20T14:22:00+0000",
    "request_id": "f1de353331a01fd14163fe4226-00009530",
    "sum_initial": {
      "amount": 1000,
      "currency": "EUR"
    },
    "sum_converted": {
      "amount": 1000,
      "currency": "EUR"
    },
    "code": "0",
    "message": "Success",
    "provider": {
      "id": 1914,
      "payment_id": "",
      "auth_code": ""
    }
  },
  "signature": "OBjT3RaJnOWsDXOclvWoC6+CFSCtLprTo8VFbN6BYVQD2tVK/3d9k+RRA/7N9TV6OQqk+0uPUnx4/c8uaUurw=="
}

The responses that the payment platform sends to request additional payment information use the same format that the callbacks use.

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 Benker
    • 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.

Thus, a correct request must include project and payment IDs, signature and additional payment information.

{
    "general": {
        "project_id": 200,
        "payment_id": "abc12345",
        "signature": "PJkV8ej\/UG0Di8jQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "additional_data": {
        "customer": {
            "psu_consent": "1",
            "psu_consent_text": "The consent text displayed to the customer"
        }
    }
 ...
}