Complete payment by document ID

The Complete payment by document ID method is used for completing a payment by its number document_id for the current reseller or any of its downstream resellers, for example, when it was paid in a third-party system. Depending on the paid amount compared to the payment amount in the platform and the payment status in the platform, the following situations are possible.

Paid amount	Payment status
Paid amount	Waiting for payment, Expired	Completed, Paid from balance, Cancelled
Equals the payment amount in the platform (full payment)	The payment gets the Completed status. The specified external transaction ID is stored.	The payment status is not changed. The specified external transaction ID is stored. On behalf of the manager whose token was used for calling the method, a correction is created for the full specified paid amount with the comment "Accounting of the amount received on the basis of {document_id} from an external system.". The Paid amount has been received from external system event handler is triggered (see Creating an event handler).
Greater than the payment amount in the platform (overpayment)	The payment gets the Completed status. The specified external transaction ID is stored. The Paid amount has been received from external system event handler is triggered (see Creating an event handler). On behalf of the manager whose token was used for calling the method, a correction is created for the calculated amount of overpayment with the comment "Accounting of the amount received on the basis of {document_id} from an external system.".
Less than the payment amount in the platform (partial payment)	The payment status is not changed. The specified external transaction ID is stored. The Paid amount has been received from external system event handler is triggered (see Creating an event handler). On behalf of the manager whose token was used for calling the method, a correction is created for the full specified paid amount with the comment "Accounting of the amount received on the basis of {document_id} from an external system.".

You can also complete a payment by its ID (see Complete payment by ID).

An API token of a manager is required for authorization. To get an API token via the Operator Control Panel, see Viewing and updating manager's information.

The manager's API token specified in an API request determines:

The role and access level of the manager, which determine the availability of a method.
The current reseller and downstream resellers accessible within a method.

POST {base_url}/api/v3/resellers/{reseller_id}/payments/{document_id}

{
  "data": {
    "attributes": {
        "payment_method_id": "{payment_method_id}",
        "amount": {amount},
        "currency_code": "{currency_code}",
        "external_transaction_id": "{external_transaction_id}"
        }
    }
}

Arguments

Name	Parameter Type	Data type	Required/ Optional	Description
X-Api-Token	header	string	Required	API token of a manager that performs the operation (see Viewing and updating manager's information)
Content-Type	header	string	Required	Media type of the request. Specify the following: application/vnd.api+json
Accept	header	string	Required	Supported media types of the answer. Specify the following: application/vnd.api+json
base_url	path	string	Required	ActivePlatform URL
reseller_id	path	integer	Required	The ID of the current reseller or any of its downstream resellers (see Viewing and updating reseller general information)
document_id	path	integer	Required	The payment number
payment_method_id	form	string	Required	The ID of the payment method to complete the payment (see Viewing the list of payment methods)
amount	form	number	Optional	The paid amount which may be not equal to the payment amount in the platform
currency_code	form	string	Optional	The currency code for paying. Must match the currency code of the payment (see Get payment)
external_transaction_id	form	string	Optional	The ID of an external transaction related to paying: If it is specified, the paid amount and its currency code are required. If it is not specified, the paid amount is ignored, and the payment is considered paid in full. The data format: from 2 to 255 characters, Latin letters Aa-Zz, Cyrillic letters Аа-Яя, numbers 0-9, and symbols ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _` { \| } ~ (except for space)

Response model

If no errors are encountered, the method returns information about the completed payment (see Get payment without the included parameter).

Request example

POST /api/v3/resellers/1/payments/2005258
Host: test.activeplatform.com
Content-Type: application/vnd.api+json
X-Api-Token: vY5fwetestK3gJXZH5uHCw
Accept: application/vnd.api+json

{
    "data": {
        "attributes": {
            "payment_method_id": "2",
            "amount": 123.45,
            "currency_code": "USD",
            "external_transaction_id": "d2a7e121-8636-42a2-a3cf-d8a5d0131a96"
        }
    }
}

Response example

{
    "data": {
        "id": "3212",
        "type": "payments",
        "attributes": {
            "created_at": "2023-10-26T16:37:31.534421+0300",
            "updated_at": "2023-10-26T16:37:43.325470+0300",
            "account_id": 478,
            "discount_amount": "0.0",
            "total": "123.45",
            "currency_code": "USD",
            "comment": "1",
            "status": "completed",
            "document_id": "2005258",
            "expiration_date": null,
            "payment_method_id": 2,
            "requester_ip": "10.11.12.13",
            "manager_id": 6,
            "purpose": "",
            "external_total": null,
            "external_currency": null,
            "due_date": null, 
            "payment_method_name": "Check",
            "closed_at": "2023-10-26T16:37:43.325470+0300"
        },
        "relationships": {
            "orders": {
                "data": []
            },
            "invoices": {
                "data": []
            },
            "charges": {
                "data": []
            },
            "corrections": {
                "data": []
            },
            "reseller": {
                "data": {
                    "id": "1",
                    "type": "resellers"
                }
            },
            "account": {
                "data": {
                    "id": "478",
                    "type": "accounts"
                }
            },
            "payment_method": {
                "data": {
                    "id": "2",
                    "type": "payment_methods"
                }
            }
        }
    }
}

Errors

Status	Error code	Error text	Comment
404	PAYMENT-001	We could not find what you are looking for	A payment with the specified `document_id` is not found for the reseller. Check the payment number and reseller ID (see Get payment)
422	PAYMENT-002	Required parameter payment_method_id is not found (code: PAYMENT-002).	Check the payment method ID (see Просмотр списка способов оплаты)
	PAYMENT-003	Transmitted currency_code does not match the payment currency_code (code: PAYMENT-003).	Check the currency code. The currency code for paying must match the currency code of the payment. To compare, see Get payment. Specify the currency code if the ID of an external transaction is specified
	PAYMENT-004	The payment of the invoice with such external_transaction_id can not be processed again (code: PAYMENT-004).	Repeat payment with the same the ID of an external transaction is prohibited
	PAYMENT-005	The parameter amount should be in currency format and greater then 0. Example: 123.45 (code: PAYMENT-005).	Check the paid amount
	PAYMENT-007	External_transaction_id has invalid format (code: PAYMENT-007).	Check the ID of an external transaction (see the requirements above in the Arguments section)

Error response example

{
    "errors": [
        {
            "status": "422",
            "title": "Unprocessable entity",
            "detail": "External_transaction_id has invalid format (code: PAYMENT-007).",
            "source": {
                "pointer": "/data/attributes/external_transaction_id"
            }
        }
    ]
}