Additional Features

Order Status

After registering an order, you can check its status in one of the following ways:

Set up callback notifications. This method is preferred. Contact support to enable the callback feature.
Periodically poll the order status for no more than half an hour or the time specified in the sessionTimeoutSecs parameter during order registration. The status can be obtained via the getOrderStatusExtended.do request.

Example request:

curl -X POST 'https://api.uat.all2pay.net/v2/getOrderStatusExtended.do'
-H 'Content-Type: application/json' \
--data-raw '{
    "orderId": "5ab8fb6a-421e-4396-9bf8-d7d77cc1e706",
    "userName": "test_user",
    "password": "test_user_password"
}'

curl -X POST 'https://api.uat.all2pay.net/v1/getOrderStatusExtended.do'
-H 'Content-Type: application/json' \
--data-raw '{
    "orderId": "5ab8fb6a-421e-4396-9bf8-d7d77cc1e706",
    "userName": "test_user",
    "password": "test_user_password"
}'

The structure of the response varies depending on whether the order is registered only in the Payment Service or has already been transferred to a bank.

The order status is represented by the state parameter. It can take the following values:

PREREGISTERED — the order is registered only in the Payment Service;
CREATED — the order is created in the bank (but not paid);
APPROVED — the order is approved (funds on the buyer’s account are blocked);
DEPOSITED — the order is completed (funds are debited from the buyer's account);
DECLINED — the order is declined;
PENDING — order payment is being processed;
REVERSED — the order is canceled;
REFUNDED — a refund has been issued.

Example response for an order registered in the Payment Service:

{
    "state": "PREREGISTERED",
    "depositedAmount": 0,
    "orderStatusResultModel": {
        "allowedPaymentWays": [
            "CARD_BINDING",
            "CARD",
            "MIR_PAY"
        ],
        "amount": 247,
        "clientId": "259753456",
        "currency": "643",
        "date": 1730530148222,
        "depositFlag": "PURCHASE",
        "gwId": null,
        "gwOrderId": null,
        "failUrl": "http://mybestmerchantreturnurl.com",
        "hasTimeout": false,
        "merchantLogin": "test_user",
        "orderDescription": "Test order",
        "orderId": "8e4c2673-98e6-11ef-ab20-4989eedfa34b",
        "orderNumber": "1730530146_3302",
        "orderParams": {
            "paramE": "deposit"
        },
        "orderStatus": -1,
        "paymentWay": null,
        "successUrl": "https://mybestmerchantreturnurl.com"
    }
}

Example response for a successfully paid order:

{
    "state": "DEPOSITED",
    "depositedAmount": 920,
    "orderStatusResultModel": {
        "actionCode": 0,
        "actionCodeDescription": "",
        "amount": 920,
        "authDateTime": 1730537059726,
        "authRefNum": "152733574684",
        "bankInfo": {
            "bankName": "SBERBANK OF RUSSIA",
            "bankCountryCode": "RU"
        },
        "cardInfo": {
            "approvalCode": "123456",
            "cardholderName": "CARDHOLDER NAME",
            "expirationDate": "202412",
            "maskedPan": "427601**7761",
            "paymentSystem": "VISA"
        },
        "clientId": "259753456",
        "currency": "643",
        "date": 1730537058969,
        "depositFlag": "PURCHASE",
        "depositedDate": 1730537060295,
        "errorCode": "0",
        "errorMessage": "Success",
        "gwId": "SBERBANK",
        "gwOrderId": "e369c6ed-ea47-7b11-8087-bba24a87c214",
        "failUrl": "http://error.info?abc-123&def=567",
        "hasTimeout": false,
        "merchantLogin": "test_user",
        "operations": [
            {
                "amount": 920,
                "authCode": "123456",
                "cardHolder": "CARDHOLDER NAME",
                "currencyCode": "643",
                "operationDate": 1730537059726,
                "operationType": "PURCHASE",
                "maskedPan": "427601**7761",
                "processingResultCode": 0,
                "referenceNumber": "152733574684",
                "success": true,
                "terminalId": "22334477"
            }
        ],
        "orderDescription": "Monitored background synergy",
        "orderId": "954aab72-98f6-11ef-ab20-7d13eddab10a",
        "orderNumber": "1730537029_6667",
        "orderParams": {
            "binProductCategory": "CREDIT",
            "mdOrder_svip": "954aab72-98f6-11ef-ab20-7d13eddab10a",
            "paramE": "deposit",
            "paramF": "BG71MQIC844222679G7L4X",
            "binProductCode": "F"
        },
        "orderStatus": 2,
        "payerData": {
            "email": "Magdalena_Moen21@hotmail.com",
            "phone": "628-243-6459"
        },
        "paymentWay": "CARD",
        "processingId": "33224466",
        "refunds": [],
        "transactionAttributes": {
            "paymentNetRefNum": "ac4329d2-2031-416c-9e5b-836b5125c0c5"
        }
    }
}

Order Lifetime

By default, an order can be paid within 30 minutes after registration. You can specify a different session time in the sessionTimeoutSecs parameter during register.do order registration. The session time applies even if the payment is made via API without using the Payment Service payment page.

When using the payment page, after the session time expires, the payment page will no longer be accessible, and any attempt to open it will redirect to failUrl.

If the order is not paid within the session time and no payment attempts were made, the order status will become DECLINED with actionCode = -2007 without specifying a bank once the time expires. If the order is not paid within the session time but payment attempts were made, the order status will also be DECLINED with actionCode = -2007 but a bank will be specified. More about actionCodes can be found in Payment Response Codes.

Cancellations, Refunds

Decline an unpaid order

Use the /decline.do method to cancel an order that has not yet been paid or authorized (has the status CREATED or PREREGISTERED). After cancelling an unpaid order, its status becomes DECLINED with actionCode=4005.

Reverse a paid order

Use the /reverse.do method to cancel a paid order (in status DEPOSITED). This operation may be possible within a specific time frame after payment, such as within the banking day before clearing has taken place (i.e. while funds have not been sent to another bank), or within another period agreed upon by the Partner and the bank.

If clearing has already passed, use /refund.do instead.

After cancellation of a paid order, its status changes to REVERSED.

Applicability for one-phase payment

Cancellation type	DEPOSITED status	Other status
Full cancellation	Cancels the order completely and changes its status to REVERSED. The entire debited amount is returned to the customer.	Not allowed
Partial cancellation (first call)	Depends on the acquirer: Either performs a full cancellation. Or reduces the debited amount by the refund amount (i.e., actually returns part of the already debited funds to the customer). In any case, changes the order status to REVERSED.	Not allowed
Partial cancellation (repeated call)	Depends on the acquirer: Either not supported (most common). Or the same as on the first `reverse.do` — reduces the debited amount.	Not allowed

Applicability for two-phase payment

Cancellation type	APPROVED status	DEPOSITED status	Other status
Full cancellation	Changes the order status to REVERSED. The entire authorized amount is returned to the customer.	Depends on the acquirer: Either returns the order to APPROVED status, returns the already debited amount to the authorized balance, and allows `deposit.do` to be called again for a different amount, or another `reverse.do` without an amount for final cancellation and change to REVERSED. Or changes the order status to REVERSED. The entire debited amount and the remaining authorized amount are returned to the customer.	Not allowed
Partial cancellation (first)	Depends on the acquirer: Either reduces the authorization amount by the cancellation amount. Or not supported.	Depends on the acquirer: Either reduces the debited amount by the refund amount (i.e., actually returns part of the already debited funds to the customer) and changes the order status to REVERSED. Or not supported.	Not allowed
Partial cancellation (repeated)	Depends on the acquirer: Either the same as on the first `reverse.do`. Or not supported.	Depends on the acquirer: Either the same as on the first `reverse.do`. Or not supported.	Not allowed

Refund

The Payment service AntiDDOS Router supports the /refund.do API method to refund for a paid order (in DEPOSITED status).

The method features the following options:

Full refund can be made by omitting the amount in the request, or by specifying the value 0 or the entire order amount in the amount parameter.
Partial refunds can be made: if product items were specified during order registration, the request should list the items being refunded in refundItems; if no items were specified, simply pass the amount in the request.
Multiple refunds can be performed for the same order. To distinguish and track such operations, the Partner can pass the externalRefundId identifier. If it is specified in the refund operation, it will be returned in the refunds block of the order status getOrderStatusExtended.do. Using this identifier, the Partner will be able to match the data from their system with the data in the order status.

In addition, externalRefundId prevents the same refund from being performed twice. During each refund attempt, the Payment service AntiDDOS Router checks the externalRefundId: if it already exists, a response is returned immediately; otherwise, a refund is performed.
After a successful refund, the order status becomes REFUNDED, even it was a partial refund.

Example of a partial refund by product items:

curl --location 'https://api.uat.all2pay.net/v2/refund.do' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 102729,
    "orderNumber": "1730538506_7044",
    "password": "test_user_password",
    "userName": "test_user",
    "refundItems": {
        "items": [
            {
                "positionId": "1",
                "name": "Advance Received",
                "quantity": {
                    "value": 1027.29,
                    "measure": "pcs"
                },
                "itemAmount": 102729,
                "itemCurrency": 643,
                "itemCode": "36035_10.1",
                "itemAttributes": {
                    "attributes": [
                        {
                            "name": "paymentMethod",
                            "value": "3"
                        },
                        {
                            "name": "paymentObject",
                            "value": "10"
                        }
                    ]
                },
                "tax": {
                    "taxType": "4"
                },
                "itemPrice": 100
            }
        ]
    }
}'

curl --location 'https://api.uat.all2pay.net/v1/refund.do' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 102729,
    "orderNumber": "1730538506_7044",
    "password": "test_user_password",
    "userName": "test_user",
    "refundItems": {
        "items": [
            {
                "positionId": "1",
                "name": "Advance Received",
                "quantity": {
                    "value": 1027.29,
                    "measure": "pcs"
                },
                "itemAmount": 102729,
                "itemCurrency": 643,
                "itemCode": "36035_10.1",
                "itemAttributes": {
                    "attributes": [
                        {
                            "name": "paymentMethod",
                            "value": "3"
                        },
                        {
                            "name": "paymentObject",
                            "value": "10"
                        }
                    ]
                },
                "tax": {
                    "taxType": "4"
                },
                "itemPrice": 100
            }
        ]
    }
}'

Example response:

{
    "errorCode": 0,
    "errorMessage": "Successful"
}

Two-phase payments

Types of payment

A company may use two types of payments, depending on the specifics of its business:

One-phase - transactions for payment for goods/services made over the Internet using bank cards that do not require additional confirmation, i.e. holding and debiting of funds takes place in one stage. This type of payments is preferable if the goods or service is provided immediately after payment
Two-phase - transactions for payment for goods/services made via the Internet with the use of bank cards that require additional confirmation, i.e. payment is made in two stages. At the first stage the check of availability and holding of funds of the payer (pre-authorization) takes place; then, at the second stage, the company either confirms to debit funds, or cancels holding of funds

The amount to be debited may be less than the amount that was held. Debits exceeding the held amount are available as well (with configurable limits). If you need this feature please contact our Support Service.

Two-phase payments should be used if some time elapses between the buyer's decision to pay and delivery of the selected good or service.

For the payment to be a two-phase payment, the order must be registered via registerPreAuth.do, not register.do.

With instantPayment.do method, the payment type (one- or two-phase) is set by the preAuth parameter.

Two-phase payment is suitable for any method of integration:

However, SBP has some limitations for two-phase payments. Learn more at Two-phase payments with SBP

The Partner must have permission for two-phase payment in the bank to which the payment is routed.

Captures

A capture of a pre-authorized amount happens in the second phase of the two-phase payment, when the funds are debited from card holder's account. Once the capture occurs, the order becomes completed and goes in the DEPOSITED status. The amount captured can be greater or less than the pre-authorization amount, and partial capture in increments is available as well. If you do not pass the amount, then the full amount will be executed.

The capture is performed via the deposit.do method.

To cancel an authorized but not yet completed order, use the reverse.do method. The Partner must have permission for reversal in the bank to which the payment is routed.

It is available to do a partial capture. It will be less than the order amount and immediately final.

Autocompletion and autoreversal

If you have this feature enabled for you by our support team, you can set up your payment integration so that all preauthorized (Approved) two-phase orders would be completed or reversed automatically after a specific time period. This means that you don't have to call deposit.do or /reverse.do API methods.

To set the period after which the order will be automatically confirmed or cancelled, in the order registration request register.do pass the autocompletionDate or autoReverseDate parameter correspondingly.