CarderPlanet
Professional
- Messages
- 2,552
- Reaction score
- 724
- Points
- 113
Let's talk about payment technologies and what happens when a client wants to pay for a service on the website or in the Internet Bank, make a transfer, or we just need to set up integration with an aggregator, store or payment system in order to display their services in their remote service channels.
A series of articles will be presented here that will help novice IT specialists dealing with payment technologies to answer the question: "how to write an outbound gateway with a payment system or aggregator", "how to resolve the issue with reconciliation discrepancies", how to implement integration with an international payment system ...
Make yourself comfortable, it will be interesting.
Further in the Internet Bank, he chooses a service for payment: replenishment of a mobile phone, payment for the Internet or housing and communal services.
In the base of a service provider, for example, a cellular operator, the client has its own unique identifier - a phone number.
To pay for the service, the client enters his ID and the amount of replenishment, clicks the "confirm payment" button.
And then it displays a pre-check with the replenishment identifier and the replenishment amount. He confirms the payment and then the Internet Bank displays a receipt for him. The happy client leaves. The money "instantly" goes to his phone number.
This is the case for the client. Let's see how it looks inside the systems.
Our online messaging will consist of several members:
I will use the entities: Bank, Merchant and Showcase to describe online interactions within systems.
The central figure in our interaction is the client's bank.
The Bank's task is not only to check the client's availability of funds, but also to deliver them to the Service Provider. To fulfill this condition, the Bank, as a rule, writes two gateways or uses the current ones:
We will consider the simplest option: the Bank's showcase, the Bank and the Merchant work using one end-to-end protocol, represented by only two methods: check and pay.
The description of the process of making and confirming the payment in this case is as follows:
Sequence of execution and confirmation of payment.
Very often, at this step, the minimum requirements for the response time of the response to the request from the Merchant are set, since the client will not wait for the Bank Showcase, the Bank itself and the Merchant to check the availability of the service.
A distinctive feature of this step is also the calculation of the commission. Commissions are:
The structure of the check / XML request, the gateway of the Showcase - Bank contour:
where
Further, if there is money, it checks the possibility of crediting money to the phone number (phone_number in the value 86248541234)
Wait a second - you ask. Something doesn't add up here. How can you check the availability of funds on the client's card using the masked PAN in the type_number field?
That's right, attentive readers have noticed that this cannot be done using a masked PAN.
Processing authorization is performed before check and it is a separate method and a separate process, look at the process diagram above. We are already working with a masked PAN during the payment process. at this step, we check the possibility of making a payment, and not the presence of funds on the client's card.
Next, we form a request to the Merchant.
We do not indicate either the PAN or the type of the withdrawal source, we are only interested in the possibility of making a payment for a specific service.
Structure of a check / XML request, gateway of the Bank - Merchant contour:
In the response, the Merchant returns all the same fields, but an additional container appears with the processing status of the operation, as well as the transaction ID in the id field
Structure of the check / XML response, gateway of the Merchant - Bank contour:
Such a response will mean that the Merchant is ready to confirm the payment by the client.
In response, we will have a temporary transaction id of the Merchant, as well as the status of payment processing: status_id == Success (success) and an error code equal to 0 (success) in the errorCode field
Successful transaction statuses do not always come to us and we do not always have error codes, but we will talk about this in the following articles.
We save the response and enrich it with the fields necessary for the storefront, assign the merchant's transaction identifier - the identifier in the Bank, and send the response to the storefront.
The structure of the check / XML response, the gateway of the contour Bank - Showcase
The client sees the screen form of the bill, which each of us is familiar with: there will be the payment amount, date, as well as the identifier of the replenished service.
If the client agrees with everything, he clicks the "pay" button. Now the payment can be canceled only by a written order of the payer, as a rule - by contacting the Bank in person.
In the request, the storefront can transmit both all the fields from the previous check response, or simply the amount of the payment and the ID of the transaction received in the previous step.
We will use the first option.
The bank registers the payment, and immediately sends a response with an intermediate status of processing the transaction "in progress" in response to the storefront
Pay / XML response structure, gateway of the Bank - showcase contour:
The client is printed a receipt for payment acceptance, with the seal of the Bank, and he leaves.
Wait - you ask. Does the Bank not send payments to the anti-fraud system? It sends, of course, just so that clients have no problems with translations to the address of "security services from places of detention." To do this, each payment is sent for verification by the system and only after that to the Merchant. But this process is unique in each organization and there are no general rules.
But you haven’t gone to the Merchant yet, haven’t confirmed the payment with him, have not registered the payment with him, and are already letting the client go - you ask again?
That's right, the client will not wait until we go off and register the payment with the Merchant, and he will turn to his suppliers on remote systems. We have already checked the possibility of making a payment online at the previous check step, and now we can release the client with the Bank's seal “in progress” and register the payment with the merchant offline.
To register a payment with the merchant, for the transferred id of the storefront transaction, we find the merchant's transaction from the previous step and register the payment with it.
Structure of a pay / XML request, gateway of the Bank - merchant contour:
Pay / XML response structure, merchant circuit gateway - Bank:
In response, the merchant reports the status of the transaction processing, which can take the status of success, in execution, or, if the payment was declined, an error.
Two statuses are final, and one is intermediate.
We can say that on these statuses, the obligations of both the Bank and the Merchant to the client are completed.
Wait, wait - you summarize. How are commitments completed? After all, the client left with a check, which says that the Bank only accepted the operation for execution, and the Merchant can reject the operation, but the client has already left, what should I do?
Yes, this happens quite often, and to solve this problem there is a separate process for requesting the final status of the operation both on the side of the storefront and on the side of the Bank, but more on that in the following articles.
In Part 1, we covered the basics of making a payment. We found out that the process is very simple and consists of several participants: the Client, the Showcase, the Bank and the Merchant, as well as two basic methods: check and pay.
Now let's talk about a method that will allow the Bank to avoid discrepancies when reconciling with the Merchant.
Reconciliation is the process of matching the register of payments received from the shop windows where the Merchant's services are located, with the register of payments actually made by the Merchant.
Simply put, the success of this reconciliation shows the Bank if there are any services where money was accepted from the Client, but not credited by the Merchant.
If all systems have worked synchronously, then successful payments will be automatically uploaded to the nearest transfer register for further matching.
But what if we have not received a response to the pay request or received a response, but the Merchant's operation is in an intermediate status?
For this there is a request for the final status of the getStatus operation.
The interaction type is asynchronous.
We will initiate it if:
And the second event occurs when the Merchant is not a Provider of the services provided, but orders them from third parties and sells them to the Bank for a certain percentage. The Merchant needs time to go to the remote systems of the Supplier and give an assignment for crediting. Therefore, in response to the pay status InProgress, he informs the Bank: the money has been accepted, but I don’t know about the status of crediting. Try to find out later.
This is how it looks in the diagram of the general payment process.
GetStatus / XML Request Example
System initiator: Bank
Receiving system: Merchant
In the request, we indicate the transaction id received in response to pay. If we have not received it, the Bank's system should try to complete the payment by sending pay once every few minutes, usually no more than three. Next, the operation is put into InProgress, getStatus is initiated.
Example getStatus / XML response
System initiator: Merchant
Receiving system: Bank
In response to the getStatus request, the Merchant can also report not the final status of the operation (success or error), but an intermediate InProgress. For these cases, the same rules apply as for the case of not receiving a response to pay: we continue to poll the Merchant's system until the final status of the operation is received, usually no more than 24 hours.
The structure of the request and response from the Storefront to the Bank is identical, except for the names of fields and transaction Id values.
The Bank's system analyzes the value of the status_id field. Successful transactions are immediately uploaded to the nearest register of transfers, for matching and further refund of funds to the Merchant.
Refunds are not made for erroneous transactions. If, in response to the getStatus request, a status_id with the value error was received, the funds are automatically returned to the client's card.
We will talk more about refunds and reconciliations in the following articles.
A series of articles will be presented here that will help novice IT specialists dealing with payment technologies to answer the question: "how to write an outbound gateway with a payment system or aggregator", "how to resolve the issue with reconciliation discrepancies", how to implement integration with an international payment system ...
Make yourself comfortable, it will be interesting.
Part 1: Making and confirming the payment
To pay for services, the client, as a rule, is authorized in the Internet Bank that issued his card: the Bank-Issuer of his card.Further in the Internet Bank, he chooses a service for payment: replenishment of a mobile phone, payment for the Internet or housing and communal services.
In the base of a service provider, for example, a cellular operator, the client has its own unique identifier - a phone number.
To pay for the service, the client enters his ID and the amount of replenishment, clicks the "confirm payment" button.
And then it displays a pre-check with the replenishment identifier and the replenishment amount. He confirms the payment and then the Internet Bank displays a receipt for him. The happy client leaves. The money "instantly" goes to his phone number.
This is the case for the client. Let's see how it looks inside the systems.
Our online messaging will consist of several members:
- Showcase - in this case, the client's Internet Bank;
- Client's bank - he is also a money transfer operator, he is also the Issuer Bank that issued the client's card, and he is also the settlement Bank for transfers of client funds to the Service Provider;
- Service Provider is a legal entity that provides services for crediting funds to the Supplier, it is often called the "Merchant". The Service Provider has direct contracts with many service providers, and in order for the Bank not to set up integration with each of them, there are intermediary companies on the market: Service Providers, also called aggregators, payment systems. They have already set up integration with Service Providers and provide a large number of services for a certain percentage;
- Our mobile operator is a Service Provider;
I will use the entities: Bank, Merchant and Showcase to describe online interactions within systems.
The central figure in our interaction is the client's bank.
The Bank's task is not only to check the client's availability of funds, but also to deliver them to the Service Provider. To fulfill this condition, the Bank, as a rule, writes two gateways or uses the current ones:
- Incoming: from Showcase to Bank;
- Outgoing: from the Bank to the Merchant;
We will consider the simplest option: the Bank's showcase, the Bank and the Merchant work using one end-to-end protocol, represented by only two methods: check and pay.
The description of the process of making and confirming the payment in this case is as follows:
Sequence of execution and confirmation of payment.
Description of the process of making and confirming the payment
- The client chooses a service;
- The Bank Showcase checks the availability of the service in its Database;
2.1 If the service is found, generates a request to the Bank for holding funds in Processing. Next, it generates a request for the possibility of making a check payment:
2.2 If the service is not found, ends the process with an error, the client leaves; - Showcase initiates check;
- The Bank receives a check request. Then the Bank routes the request to the Merchant;
- The merchant accepts the request, checks the payment;
5.1 If enrollment is possible, sends success, the customer is shown a guest bill. The Bank's system is awaiting confirmation of the payment;
5.2 If the deposit is not possible, the Bank sends an error code, the storefront completes the process, the process is impossible, the client leaves; - The client gets acquainted with the bill, clicks the "confirm payment" button. Showcase initiates pay;
- The bank assigns a transaction ID and immediately sends a response to the storefront;
- The funds are credited to the Merchant already offline. The Bank initiates pay and, if crediting is possible, the Merchant assigns its transaction ID and sends a successful response to the Bank. And if enrollment is impossible - you ask? Then the Merchant sends a response to the Bank with an error code, and the Bank automatically refunds the funds to the client on the same day.
CHECK - payment processing
The method is responsible for the ability to make a payment. At this step, the availability of the service is checked on the storefront, in the Bank and at the Merchant. The Merchant, in turn, online, can go to the Supplier and check the validity of the replenishment identifier with the Supplier, and, if it is not found or an error, reject the payment.Very often, at this step, the minimum requirements for the response time of the response to the request from the Merchant are set, since the client will not wait for the Bank Showcase, the Bank itself and the Merchant to check the availability of the service.
A distinctive feature of this step is also the calculation of the commission. Commissions are:
- The upper, or hot, is the commission from the client in excess of the payment body (the amount credited);
- Low or cold, this is the commission that the Merchant Bank pays;
- Mixed - in this section we will not talk about them;
The structure of the check / XML request, the gateway of the Showcase - Bank contour:
Code:
<check>
<payment>
<Time>2021-02-08T00:16:19</Time>
<type>CARD</type>
<type_number>505266***2025</type_number>
<code>643</code>
<amount>20100</amount>
<comission_amount>20241</comission_amount>
<service>123456789</service>
</payment>
<account>
<name>phone_number</name>
<value>86248541234</value>
</account>
</check>where
- Time - payment date;
- type - the type of the write-off source;
- type_number - masked PAN of the card (note: PAN - card number) by PCI DSS;
- code - the code of the transfer currency, in the example, rubles;
- amount - the amount credited or, in other words, the body of the payment
- commission_amount - amount including the upper commission;
- service - digital identifier of the service, which checks whether there is such a service at all in the Bank and on the storefront;
- account - container with the replenishment identifier, in our case - the phone number;
Further, if there is money, it checks the possibility of crediting money to the phone number (phone_number in the value 86248541234)
Wait a second - you ask. Something doesn't add up here. How can you check the availability of funds on the client's card using the masked PAN in the type_number field?
That's right, attentive readers have noticed that this cannot be done using a masked PAN.
Processing authorization is performed before check and it is a separate method and a separate process, look at the process diagram above. We are already working with a masked PAN during the payment process. at this step, we check the possibility of making a payment, and not the presence of funds on the client's card.
Next, we form a request to the Merchant.
We do not indicate either the PAN or the type of the withdrawal source, we are only interested in the possibility of making a payment for a specific service.
Structure of a check / XML request, gateway of the Bank - Merchant contour:
Code:
<check>
<payment>
<Time>2021-02-08T00:16:19</Time>
<code>643</code>
<amount>20100</amount>
<comission_amount>20241</comission_amount>
<service>123456789</service>
</payment>
<account>
<name>phone_number</name>
<value>86248541234</value>
</account>
</check>In the response, the Merchant returns all the same fields, but an additional container appears with the processing status of the operation, as well as the transaction ID in the id field
Structure of the check / XML response, gateway of the Merchant - Bank contour:
Code:
<check>
<payment>
<Time>2021-02-08T00:16:20</Time>
<id>123456789</id>
<code>643</code>
<amount>20100</amount>
<comission_amount>20241</comission_amount>
<service>123456789</service>
<account>
<name>phone_number</name>
<value>86248541234</value>
</account>
</payment>
<StatusInfo>
<status_id>Success</status_id>
<disсriptin>Успех</disсriptin>
<errorCode>0</errorCode>
</StatusInfo>
</check>Such a response will mean that the Merchant is ready to confirm the payment by the client.
In response, we will have a temporary transaction id of the Merchant, as well as the status of payment processing: status_id == Success (success) and an error code equal to 0 (success) in the errorCode field
Successful transaction statuses do not always come to us and we do not always have error codes, but we will talk about this in the following articles.
We save the response and enrich it with the fields necessary for the storefront, assign the merchant's transaction identifier - the identifier in the Bank, and send the response to the storefront.
The structure of the check / XML response, the gateway of the contour Bank - Showcase
Code:
<check>
<payment>
<Time>2021-02-08T00:16:20</Time>
<type>BOUND_CARD</type>
<type_number>427684***3619</type_number>
<id>123</id>
<code>643</code>
<amount>20100</amount>
<comission_amount>20241</comission_amount>
<service>123456789</service>
<account>
<name>phone_number</name>
<value>86248541234</value>
</account>
</payment>
<StatusInfo>
<status_id>Success</status_id>
<disсriptin>Успех</disсriptin>
<errorCode>0</errorCode>
</StatusInfo>
</check>The client sees the screen form of the bill, which each of us is familiar with: there will be the payment amount, date, as well as the identifier of the replenished service.
If the client agrees with everything, he clicks the "pay" button. Now the payment can be canceled only by a written order of the payer, as a rule - by contacting the Bank in person.
In the request, the storefront can transmit both all the fields from the previous check response, or simply the amount of the payment and the ID of the transaction received in the previous step.
We will use the first option.
PAY - confirmation of payment
Structure of a pay / XML request, gateway of the Showcase - Bank contour:
Code:
<pay>
<payment>
<Time>2021-02-08T00:16:25</Time>
<type>CARD</type>
<type_number>505266***2025</type_number>
<id>123</id>
<code>643</code>
<amount>20100</amount>
<comission_amount>20241</comission_amount>
<service>123456789</service>
</payment>
<account>
<name>phone_number</name>
<value>86248541234</value>
</account>
</pay>The bank registers the payment, and immediately sends a response with an intermediate status of processing the transaction "in progress" in response to the storefront
Pay / XML response structure, gateway of the Bank - showcase contour:
Code:
<pay>
<payment>
<Time>2021-02-08T00:16:20</Time>
<type>CARD</type>
<type_number>505266***2025</type_number>
<id>123</id>
<code>643</code>
<amount>20100</amount>
<comission_amount>20241</comission_amount>
<service>123456789</service>
<account>
<name>phone_number</name>
<value>86248541234</value>
</account>
</payment>
<StatusInfo>
<status_id>Inprogress</status_id>
<disсriptin>В проведении</disсriptin>
<errorCode>0</errorCode>
</StatusInfo>
</pay>The client is printed a receipt for payment acceptance, with the seal of the Bank, and he leaves.
Wait - you ask. Does the Bank not send payments to the anti-fraud system? It sends, of course, just so that clients have no problems with translations to the address of "security services from places of detention." To do this, each payment is sent for verification by the system and only after that to the Merchant. But this process is unique in each organization and there are no general rules.
But you haven’t gone to the Merchant yet, haven’t confirmed the payment with him, have not registered the payment with him, and are already letting the client go - you ask again?
That's right, the client will not wait until we go off and register the payment with the Merchant, and he will turn to his suppliers on remote systems. We have already checked the possibility of making a payment online at the previous check step, and now we can release the client with the Bank's seal “in progress” and register the payment with the merchant offline.
To register a payment with the merchant, for the transferred id of the storefront transaction, we find the merchant's transaction from the previous step and register the payment with it.
Structure of a pay / XML request, gateway of the Bank - merchant contour:
Code:
<pay>
<payment>
<Time>2021-02-08T00:16:25</Time>
<id>123456789</id>
<code>643</code>
<amount>20100</amount>
<comission_amount>20241</comission_amount>
<service>123456789</service>
</payment>
<account>
<name>phone_number</name>
<value>86248541234</value>
</account>
</pay>Pay / XML response structure, merchant circuit gateway - Bank:
Code:
<pay>
<payment>
<Time>2021-02-08T:16:25</Time>
<id>123456789</id>
<code>643</code>
<amount>20100</amount>
<comission_amount>20241</comission_amount>
<service>123456789</service>
<account>
<name>phone_number</name>
<value>86248541234</value>
</account>
</payment>
<StatusInfo>
<status_id>Success</status_id>
<disсriptin>Успех</disсriptin>
<errorCode>0</errorCode>
</StatusInfo>
</pay>In response, the merchant reports the status of the transaction processing, which can take the status of success, in execution, or, if the payment was declined, an error.
Two statuses are final, and one is intermediate.
We can say that on these statuses, the obligations of both the Bank and the Merchant to the client are completed.
Wait, wait - you summarize. How are commitments completed? After all, the client left with a check, which says that the Bank only accepted the operation for execution, and the Merchant can reject the operation, but the client has already left, what should I do?
Yes, this happens quite often, and to solve this problem there is a separate process for requesting the final status of the operation both on the side of the storefront and on the side of the Bank, but more on that in the following articles.
In Part 1, we covered the basics of making a payment. We found out that the process is very simple and consists of several participants: the Client, the Showcase, the Bank and the Merchant, as well as two basic methods: check and pay.
Now let's talk about a method that will allow the Bank to avoid discrepancies when reconciling with the Merchant.
Reconciliation is the process of matching the register of payments received from the shop windows where the Merchant's services are located, with the register of payments actually made by the Merchant.
Simply put, the success of this reconciliation shows the Bank if there are any services where money was accepted from the Client, but not credited by the Merchant.
If all systems have worked synchronously, then successful payments will be automatically uploaded to the nearest transfer register for further matching.
But what if we have not received a response to the pay request or received a response, but the Merchant's operation is in an intermediate status?
For this there is a request for the final status of the getStatus operation.
The interaction type is asynchronous.
We will initiate it if:
- The waiting time for a response to pay has exceeded the allowed threshold. In the Bank, we put the operation into execution and initiate the getStatus request;
- In response to the pay request, we received an intermediate status of the operation - InProgress.
And the second event occurs when the Merchant is not a Provider of the services provided, but orders them from third parties and sells them to the Bank for a certain percentage. The Merchant needs time to go to the remote systems of the Supplier and give an assignment for crediting. Therefore, in response to the pay status InProgress, he informs the Bank: the money has been accepted, but I don’t know about the status of crediting. Try to find out later.
This is how it looks in the diagram of the general payment process.
- The bank analyzes transactions where no response to the pay request was received or where a response was received, but the status of the transaction is intermediate: InProgress;
- Then it interrogates the Merchant's system with a certain frequency: usually once every 15 minutes during the day. Further, the operation is translated into an error on the entire information exchange loop;
- The showcase, in turn, does the same, but in relation to the Bank.
GetStatus / XML Request Example
System initiator: Bank
Receiving system: Merchant
Code:
<pay>
<payment>
<time>2021-02-08T00:16:25</time>
<id>123456789</id>
</payment>
</pay>In the request, we indicate the transaction id received in response to pay. If we have not received it, the Bank's system should try to complete the payment by sending pay once every few minutes, usually no more than three. Next, the operation is put into InProgress, getStatus is initiated.
Example getStatus / XML response
System initiator: Merchant
Receiving system: Bank
Code:
<pay>
<payment>
<Time>2021-02-08T:16:25</Time>
<id>123456789</id>
</payment>
<StatusInfo>
<status_id>Success</status_id>
<disсriptin>Успех</disсriptin>
<errorCode>0</errorCode>
</StatusInfo>
</pay>In response to the getStatus request, the Merchant can also report not the final status of the operation (success or error), but an intermediate InProgress. For these cases, the same rules apply as for the case of not receiving a response to pay: we continue to poll the Merchant's system until the final status of the operation is received, usually no more than 24 hours.
The structure of the request and response from the Storefront to the Bank is identical, except for the names of fields and transaction Id values.
The Bank's system analyzes the value of the status_id field. Successful transactions are immediately uploaded to the nearest register of transfers, for matching and further refund of funds to the Merchant.
Refunds are not made for erroneous transactions. If, in response to the getStatus request, a status_id with the value error was received, the funds are automatically returned to the client's card.
We will talk more about refunds and reconciliations in the following articles.
