process-external-payment method

Description

Making a payment. The application calls the method up until the final payment status is known (status=success/refused).

The recommended retry mode is determined by the "next_retry" response field (by default, 5 seconds).

Request parameters

Request parameters for:

  • The first payment or deposit.
  • A repeated request after entering card data or authenticating using 3-D Secure.
Parameter Type Description
request_id string Payment context ID obtained from the request-external-payment method response.
instance_id string ID of the application instance.
ext_auth_success_uri string Address of the page to return to when card payment has been successfully authenticated using 3-D Secure technology.
ext_auth_fail_uri string Address of the page to return to when card payment has failed 3-D Secure authentication.
request_token boolean If this parameter is present and has the value "true", the application requests a token for repeat payments. By default, the parameter is omitted (a token for repeat payments is not requested).

Parameters for a repeated payment request using a token:

  • Without entering card data.
  • With a repeated request after authentication via 3-D Secure.
Parameter Type Description
request_id string Payment context ID obtained from the request-external-payment method response.
instance_id string ID of the application instance.
ext_auth_success_uri string Address of the page to return to when card payment has been successfully authenticated using 3-D Secure technology.
ext_auth_fail_uri string Address of the page to return to when card payment has failed 3-D Secure authentication.
money_source_token string Token for repeated payments.
csc string, 3 digits Card Security Code, CVV2/CVC2 code on the bank card.

Returns

Response fields:

Parameter Type Description
status string Operation result code (see the table).
error string Error code (explanation of the "status" field). Present only for errors (see the table).
acs_uri string Address of the 3-D secure bank card authentication page on the issuing bank's side. This field must be present if 3-D Secure authentication is required in order to complete a transaction using a bank card.
acs_params object Authentication parameters for 3-D Secure technology in the form of a name-value collection. This field must be present if 3-D Secure authentication is required in order to complete a transaction using a bank card.
money_source object Bank card data for repeated payments. This field is present if the request parameter request_token=true is set, the payment was completed successfully, and the server approved issuing a token for this operation.
Note. If the server refused to issue a token, this field is omitted in the response.
next_retry long The recommended length of time (in milliseconds) before repeating the request. This field is present when status=in_progress
invoice_id string The transaction number in Yandex.Money. Present when payment was successfully made to a merchant.

Operation processing result codes:

Code Description
success Payment processing completed successfully.
refused Payment processing was refused. The reason for refusal is returned in the error field. Final state.
in_progress Payment processing is not yet complete. The application should repeat the request with the same parameters after the amount of time in "next_retry" has passed.
ext_auth_required Processing a bank card payment requires additional verification by the issuing bank (3-D Secure authentication). You should open WebView and use a POST request to send the client to the "acs_uri" address with the "acs_params" parameters.

If an error occurred while processing the transaction, the error code is returned:

Code Description
illegal_param_request_id Invalid value for request_id or missing context with the set request_id
illegal_param_csc The csc parameter has a missing or invalid value.
illegal_param_instance_id The instance_id parameter has a missing or invalid value.
illegal_param_money_source_token The money_source_token parameter has a missing or invalid value, the token was revoked or expired.
payment_refused The payment was refused. Possible reasons:
  • The merchant refused to accept the payment (checkOrder request).
  • The transfer to a Yandex.Money user is not possible (for example, the recipient's wallet has reached the maximum amount allowed).
authorization_reject Authorization of the payment was refused. Possible reasons:
  • The issuing bank refused to perform the transaction for the card.
  • A transaction with the current parameters is forbidden for this user.
illegal_param_ext_auth_success_uri The ext_auth_success_uri parameter has a missing or invalid value.
illegal_param_ext_auth_fail_uri The ext_auth_fail_uri parameter has a missing or invalid value.

Bank card data for repeated payments:

Parameter Type Description
type string Type of funding-source: payment-card — bank card.
payment_card_type string The type of card; may be omitted if unknown. Accepted values: Visa, MasterCard, AmericanExpress, JCB.
pan_fragment string Masked card number; the last four digits are visible.
money_source_token string Generated token for repeated payments.

Examples

Example of a request to make a payment:

POST /api/process-external-payment HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded
Content-Length: 305

request_id=3931303833373438395f3434343164663138646162366132363630633863616638343
36137386537643935383639383062635f3330363333323938&instance_id=1234567890ABCDEF12
34567890ABCDEF1234567890ABCDEF1234567890ABCDEF1&ext_auth_success_ur=yandexmoney
app%3A%2F%2Fsuccess&ext_auth_fail_uri=yandexmoneyapp%3A%2F%2Ffail

Example of a request to get a token:

POST /api/process-external-payment HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded
Content-Length: 324

request_id=3931303833373438395f3434343164663138646162366132363630633863616638343
36137386537643935383639383062635f3330363333323938&instance_id=1234567890ABCDEF12
34567890ABCDEF1234567890ABCDEF1234567890ABCDEF1&ext_auth_success_uri=yandexmoney
app%3A%2F%2Fsuccess&ext_auth_fail_uri=yandexmoneyapp%3A%2F%2Ffail&request_token=
true

Example of a payment request with a token:

POST /api/process-external-payment HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded
Content-Length: 589

request_id=3931303833373438395f3434343164663138646162366132363630633863616638343
36137386537643935383639383062635f3330363333323938&instance_id=1234567890ABCDEF12
34567890ABCDEF1234567890ABCDEF1234567890ABCDEF1&ext_auth_success_uri=yandexmoney
app%3A%2F%2Fsuccess&ext_auth_fail_uri=yandexmoneyapp%3A%2F%2Ffail&money_source_t
oken=B6AE719BAF712404E08EF8A430B0F58CD8F2C592452CA5205F7E52B1FC72BD3D42745714
D60B4E75BD742F22E8120F0861ED99B69EC01C6194CF5D425C89598B959DE0E9EDB13AFD710CF
74ACE08DBFBE2A49F14F9792B32289CE2456EB50EF7DFE6D22E466D417ACD1BF8DE33B5C93BDA
9AAA8C4D693DCD2E9AA2A31A51C185&csc=123

Example of a response document for a successfully processed payment:

{"status": "success", "invoice_id": "3000130505460"}

Example of a response document when 3-D Secure authentication was requested for the card:

{
    "status": "ext_auth_required",
    "acs_uri": "https://acs.alfabank.ru/acs/PAReq",
    "acs_params": {
        "MD": "723613-7431F11492F4F2D0",
        "PaReq": "eJxVUl1T2zAQ/CsZv8f6tCR7LmLSGiidJjAldMpTR7XVxA
N2gmynSX59JeNAebu9O93u7QkuDvXzZG9dW22bWURiHE1sU2zLqlnPo
ofV1VRFFxpWG2dtfm+L3lkNC9u2Zm0nVTmLVvn9r7v5d/uS/UkYt4b8
tjibUiGVxazICMeSSkmtwBmlhYw="
    }
}

Example of a response document if payment processing has not yet been completed:

{"status": "in_progress", "next_retry": "5000"}

Example of a response document if the payment was rejected:

{"status": "refused", "error": "payment_refused"}

Example of a response document when a token was successfully issued for repeated payments:

{
    "status": "success",
    "invoice_id": "3000130505460",
    "money_source": {
        "type": "payment-card",
        "payment_card_type": "VISA",
        "pan_fragment": "**** **** **** 0334",
        "money_source_token": "B6AE719BAF712404E08EF8A430B0F58CD8
F2C592452CA5205F7E52B1FC72BD3D42745714D60B4E75BD742F22E8120F0861E
D99B69EC01C6194CF5D425C89598B959DE0E9EDB13AFD710CF74ACE08DBFBE2A4
9F14F9792B32289CE2456EB50EF7DFE6D22E466D417ACD1BF8DE33B5C93BDA9AA
A8C4D693DCD2E9AA2A31A51C185"
    }
}

Example of a response document when a token for repeated payments was not issued (refused):

{"status": "success", "invoice_id": "3000130505460"}