Process of saving the client's PAN card

This scenario describes sending a payment to a bank card in case you cannot collect bank card data and store it on your side (you do not have a PCI DSS certificate).

You can receive tokenized card data using the widget and make a secure payment.

The process describes the steps of interaction between an agent and a client with a web application. Interaction steps can involve opening the input form in a separate window or opening the form in an iframe. The process allows the client to enter and save card details through the web-app.

What does the widget look like

Authorization data

• Test authorization data:
  • url = https://a2c-test.qiwi.kz
  • agentId = agent-01
  • agentSecretKey = 22f3b3cc2ae84451
  • host = http://localhost:3019
• Production authorization credentials:
  • url = https://a2c.qiwi.kz/
  • agentId and agentSecretKey = provided upon request through the account manager

Important:

To enable the application to be displayed in an iframe, it is necessary to provide a list of test and production hosts from which embedding will be performed.

The process of opening a page in a separate window.

Process steps

1. Generating URL Opening a web-app by a client

   • Agent is generating URL by format: {host}/form?agentId={agent id}&requestId={request id }&language=ru&agentCallbackUrl={response result return page}&agentSign={signature hmac}.
   • The parameter language can take the values: ru, en, kz. Default is ru.
   • The URL contains the parameters necessary to identify the agent, request, return page, and signature.
   • HMAC SHA256 algorithm. To compute hmac, you need to concatenate the string requestId;agentId;agentCallbackUrl and apply agentSecretKey. For example, use https://www.freeformatter.com/hmac-generator.html. Example of the obtained URL: https://a2c-test.qiwi.kz/form?agentId=agent-01&requestId=12345678&language=ru&agentCallbackUrl=https://agent.site.kz&agentSign=bc305308aa5fa30a56d69ab166a7d5613cf2ca17783d034fdc08eeba23bad901
   • Redirect Client to URL

2. Card number entry and saving

   • Client navigates to the received URL.
   • Client opens Web-app.
   • The client enters their card number into the provided form on the web-app.
   • After entering the data, the client clicks the "Save" button to send the data.

3. Transition with a response to agentCallbackUrl

   • In case of a successful response:
     • A client redirect to agentCallbackUrl occurs with parameters added to the URL: ?requestId={request-id}&panToken={Card Token}.
   • In case of an unsuccessful response:
     • A client redirect to agentCallbackUrl occurs with error parameters added to the URL: ?requestId={request-id}&errorCode={Error Code}&errorMessage={Error Message}.

Request Parameters

Parameters for Redirect URL and Iframe

Parameter	Type	Required	Description
agentId	string	Yes	String identifier of the agent.
requestId	Long	Yes	Unique identifier of the operation.
language	string	No	Language selection: ru, en, kz. Default is ru.
agentCallbackUrl	string	Yes	Agent link for redirection after card data entry completion.
	string	No	For opening form in iFrame. Events will be generated.
agent_sign	string	Yes	HMAC SHA256 signature: requestId;agentId;agentCallbackUrl using agentSecretKey.

Response Parameters after Saving

Parameter	Type	Required	Description
requestId	Long	Yes	Unique identifier of the operation.
panToken	string	No	Card token passed in case of successful response.
errorCode	string	No	Error code passed in case of unsuccessful response. List of Errors
errorMessage	string	No	Error message passed in case of unsuccessful response.

Process for embedding an application in an iframe

This process describes the interaction between a client, an agent, and an application embedded in an iframe on the agent's site.

Process steps

1. Initiation of an action by the client

   • The client at the agent site initiates an action that requires interaction with the web application.

2. Application embedding by agent

   • In response to the client's action, the agent embeds the web application in an iframe on its site using a specially generated URL:

     {host}/form?agentId={agent id}&requestId={request id}&language=ru&agentSign={signature hmac}
   • The parameter language can take the values: ru, en, kz. Default is ru.
   • HMAC SHA256 algorithm. To compute hmac, you need to concatenate the string requestId;agentId; and apply agentSecretKey. For example, use https://www.freeformatter.com/hmac-generator.html. Example of the obtained URL: https://a2c-test.qiwi.kz/form?agentId=agent-01&requestId=123456789&language=ru&agentSign=3e77416dbc65b9225c1ff455d357cdc4200fa83ee273bce727aa34c8dc44c725

   Example of iframe embedding:

   <iframe src="{application address}?agentId={agent id}&requestId={request id}&language=ru&agentSign={signature hmac}" width="100%" height="100%" title="Embedded Iframe" frameBorder="0"></iframe>

   • The iframe is embedded with a width and height value of 100%, allowing it to automatically adjust to the size of the block it is embedded in. Note: the minimum width of the block should be 320px and the height 500px.

3. Waiting for application readiness

   • The agent is waiting for a message about the application readiness, which comes in the form of postMessage with the status "Ready".

4. Checking origin before interaction

   • After receiving the ready message, the agent passes any event to the iframe via postMessage to verify origin, confirming the security of the interaction.

5. Data entry by client

   • The client enters the card data and confirms the action through the application interface embedded in the iframe.

6. Processing data and sending a response

   • The application processes the entered data and sends the result of processing to the agent via postMessage.
     • In case of unsuccessful response: the application sends JSON with error information to the agent:

       {"requestId": "request id", "errorCode": "error code", "errorMessage": "error message"}
     • In case of successful response: the application sends JSON with the processing result to the agent:

       {"requestId": "request id", "panToken": "card token"}

Response processing by agent

• The agent processes the response received from the application and responds accordingly to the result of the operation, informing the client of the processing status.

Possible error types

Error code	Description
AGENT_NOT_FOUND	Agent data transferred incorrectly
AGENT_SIGN_INVALID	Signature is invalid
PARSE_REQUEST_ERROR	Transferred data is invalid
INVALID_SESSION	Client-side process violation
INVALID_PAN	Card number is invalid
PAN_IS_EXISTS_FOR_REQUEST	There is already a saved card number for this request
FORBIDDEN	Requests are blocked. Try again later

Now you can make card payments using the token