Funds deposit (makeDeposition)

Operation for sending a transfer to a Yandex.Money Wallet, a bank account in rubles, a bank card, or a mobile phone account.

The payment recipient is defined in the value of the dstAccount parameter. Data required for depositing in the appropriate way is transmitted in the paymentParams parameters. This includes the recipient's agreement with the Yandex.Checkout terms (pof_offerAccepted). You need to place the link to the offer on your side: https://money.yandex.ru/pay/doc.xml?offerid=default.

Note.

Before sending the money to the user, the ability to deposit the funds must be checked using the testDeposition request. This request lets you check whether the amount specified can be transferred to the appropriate user, including:

  • Whether the user ID is correct and exists (the account number or phone number).
  • What limits are applied.
  • Whether this operation is allowed.

When a testDeposition request is received, the deposit is not made.

Verification of recipient's passport information

In requests to debit to a bank account or bank card, the recipient's personal data must be passed. Before making the deposit, the Yandex.Money service checks this information against the database of active passports of the Ministry of Internal Affairs (as required by the legislation of the Russian Federation).

This verification takes place immediately after the makeDepostion request is sent. During the day, the verification takes approximately 10 minutes, at night (from 1:00 to 6:00) — up to 3 hours. Passport data needs to be checked once, subsequent requests using the same data will go through quicker.

  1. Initially, the response to the request is "processing" (status=1). This means that Yandex.Money is verifying the data.
  2. In 10 minutes a repeat request can be sent to find out the deposit status:
    1. If it was successful, status=0 is returned in response
    2. If payment didn't go through, the errorDepositionNotification is sent.

If the data does not pass verification, the Yandex.Money service returns a deposition error (error=48) with an explanation.

Interaction format

Described in the Protocol for deposits to Wallets. See Interaction format

Address for sending requests
https://server:port/webservice/deposition/api/testDeposition
https://server:port/webservice/deposition/api/makeDeposition

Request parameters

Parameter

Type

Description

Mandatory parameters
dstAccountYMAccount

Identifier of the transfer recipient.

Depends on where you send the transfer:

clientOrderIdClientTransactionNumber

Operation ID. Must be unique for the Counterparty over the entire history of operations. Recommended values: a positive integer in decimal notation.

requestDTxs:dateTime

The date and time the operation request was formed on the Counterparty's side, according to their system.

amountCurrencyAmount

The transfer amount. For example: 12.34.

currencyCurrencyCode

Currency code of the transfer. Possible values:

  • 643 — Russian ruble.
  • 10643 — Test currency in the Yandex.Money testing environment.
agentIdxs:long

Counterparty ID issued by Yandex.Money.

contract

xs:normalizedString,

up to 128 characters

The reason for making the transfer.
Optional parameters
paymentParamsxs:complexType

Request element for transmitting additional payment parameters. Possible values are described in the sections Transfer to bank card, Transfer to bank account, and Transfer to mobile phone account.

Response parameters of the Yandex.Money service

Parameter

Type

Description

statusxs:int

Result of executing the operation. The value of this field should be used on the Counterparty's side to make a decision about the request state. See Request status codes

errorxs:int

Code of the request execution error. Additional explanation of the status.

clientOrderIdClientTransactionNumber

The value of the clientOrderId request parameter.

processedDTxs:dateTime

Time when the request was processed, according to the Yandex.Money server. For a successful transfer, this is the actual time when money was transferred.

balancexs:decimal

The difference between the security amount that the Counterparty has transferred to the gateway account in Yandex.Money, and the amount of money that Yandex.Money has transferred to users at the request of the Counterparty. This parameter is passed in the response only for the makeDeposition request, and only if the transfer was successful.

techMessagexs:string

Optional field. May contain an additional explanation for refusals to accept the payment. This text contains technical information and should not be displayed in any user interface.

When making a transfer to a bank account, card, or mobile phone, the reason for refusing to accept the payment is only contained in the response to the makeDeposition request.

identificationxs:string

This field contains information about the status of the Wallet in the Yandex.Money service. Only present for deposits to Yandex.Money Wallets.

Possible values:

  • anonymous — no identification;
  • reviewed — simplified identification;
  • identified — full identification.

More about user statuses

Examples

Request examples
Request to check transfer possibility
<testDepositionRequest agentId="123"                         clientOrderId="12345"                         requestDT="2011-07-01T20:38:00.000Z"                         dstAccount="410011234567"                         amount="10.00"                         currency="643"                         contract="Winnings in Sphera game"/>
Request to transfer specifying paymentParams
<makeDepositionRequest agentId="200225"
                         clientOrderId="272517"
                         requestDT="2013-04-12T00:01:54.000Z"
                         dstAccount="2570066957329"
                         amount="249.00"
                         currency="643"
                         contract="">
           <paymentParams>
                    <pof_offerAccepted>1</pof_offerAccepted>
                    <PROPERTY1>905</PROPERTY1>
                    <PROPERTY2>2075556</PROPERTY2>
                    <smsPhoneNumber>79653457676</smsPhoneNumber>
           </paymentParams>
  </makeDepositionRequest>
Examples of responses
Response about deposit possibility
<testDepositionResponse clientOrderId="12345"
                          status="0"
                          processedDT="2011-07-01T20:38:01.000Z"/>
Response about successful deposit
<makeDepositionResponse clientOrderId="12345"
                          status="0"
                          processedDT="2011-07-01T20:38:01.000Z"
                          balance="1000.00"/>

Rules for forming and processing requests

  1. Each transfer must be formed with a unique ID value (clientOrderId).
  2. If the response Success (status=0) is received for the deposit operation, it means the transfer was completed successfully. In some cases of a successful transfer, Yandex.Money might return the error field in the response with an additional explanation of the operation status.
  3. If the request was sent with a previously processed ID (clientOrderId) and the values of the mandatory parameters (clientOrderId, dstAccount and amount) match the previous attempt, Yandex.Money returns the result of processing the previously sent request.
  4. If the request was sent with a previously processed ID (clientOrderId) and the values of mandatory parameters (clientOrderId, dstAccount and amount) differ from the first attempt, Yandex.Money declines this request and returns status=3, error=26 in the response.
  5. The Yandex.Money service processes a received request immediately. If a request can't be handled within a few seconds, the response processing (status=1) is returned. In this case, the result of the operation is unknown, and the merchant should repeat the request with the same data to get a final response. We recommend retrying as follows: the first retry after 1 minute, the next three with an interval of 5 minutes, and then not more than once every 30 minutes. We recommend the same retry attempts if the response from the Yandex.Money service is not received, or if the response contains HTTP status 500.
  6. If there is no response from Yandex.Money, or if the response is indefinite (for example: HTTP status 500), the counterparty's system should repeat the request with the same data until the final response is received. We recommend using the same retry attempts as in the previous point.
  7. The status of a transaction in progress (status=1) may change either to Success (status=0) or Declined (status=3).
  8. If the transfer was declined by the Yandex.Money service, the response returns status=3 and error with the code of the reason for refusal. In some cases the techMessage field may be included, which contains additional information in the form of text in any format. This text is intended for analysis by technical specialists and shouldn't be shown in any user interface.
  9. If the transfer is refused with the error status=3 error=45, the Counterparty's system should deposit accepted transfers to the Yandex.Money account and confirm that the balance increased (by sending a balance request), then make the transfers with new transaction IDs (clientOrderId).
  10. The response status=3 error=21 means that the requested operation is not allowed for this Counterparty.
  11. The response status=0 error=43 means that the transfer was successful and the Counterparty's balance was reduced by the transfer amount, and the Yandex.Money service sent the recipient an SMS message or email with instructions for receiving the money.

See also

Transfer to a Yandex.Money wallet

Transfer to bank card

Transfer to bank account

Transfer to mobile phone balance

Reports on accepted and returned transfers