paypal.php¶

PayPal integration module for managing vault payments, subscription checks, and order creation/capture processes.

API Methods¶

Method	Action	Description
`charge_vault`	charge_vault	Charges a saved PayPal vault against a specific invoice after verifying ownership.
`check_order`	check_order	Captures a PayPal order and handles vault binding if available.
`check_payment`	check_payment	Checks if a subscription payment has been made recently to confirm an order.
`check_subscription`	check_subscription	Verifies the status of a PayPal subscription via transaction history.
`create_order`	create_order	Creates a PayPal order or payment, optionally enabling vaulting.
`create_payment_token`	create_payment_token	Creates a PayPal payment token to enable automatic recurring payments (Vault).
`create_setup_token`	create_setup_token	Initializes a PayPal setup token for recurring billing.
`create_subscription`	create subscription	Creates a new PayPal subscription for the customer based on an invoice.
`revoke_vault`	revoke vault	Revokes a PayPal payment vault associated with the client.

paypal/charge_vault¶

Charges a saved PayPal vault against a specific invoice after verifying ownership.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `charge_vault`
token	✅	string	Authentication token.
invoice_id	✅	integer	The ID of the invoice to charge.
vault_id	✅	string	The ID of the PayPal vault to use for charging.
billing	❌	string	The billing identifier used to locate the customer data.

Request example

curl -s "https://invapi.hostkey.com/paypal.php" -X POST \
--data "action=charge_vault" \
--data "token=HOSTKEY_TOKEN" \
--data "invoice_id=VALUE" \
--data "vault_id=VALUE"

Success response example

{
"result": "OK",
"action": "charge_vault",
"data": {
"status": "captured",
"id": "PAYID-XXXXXXXXXXXXX"
}
}

Error examples

{
"code": -1,
"message": "$module/charge_vault: missing invoice_id or vault_id"
}

paypal/check_order¶

Captures a PayPal order and handles vault binding if available.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: check_order
token	✅	string	Authentication token.
error_description	✅	string	Error description for session initialization.
purchase_units	✅	string	Purchase units data from PayPal response.
status	✅	string	Current status of the order. Допустимые значения: enable.
payment_source	✅	string	Payment source information for vault binding.
invoice_id	❌	string	The unique identifier for the invoice being processed.
order_id	❌	integer	The PayPal order ID used to capture the payment.
billing	❌	string	The billing configuration or provider name used for session initialization.

Request example

curl -s "https://invapi.hostkey.com/paypal.php" -X POST \
--data "action=check_order" \
--data "token=VALUE" \
--data "error_description=VALUE" \
--data "purchase_units=VALUE" \
--data "status=VALUE" \
--data "payment_source=VALUE"

Success response example

{
"result": "OK",
"action": "check_order",
"data": {
"id": "ORD-XXXXXXXXX",
"status": "COMPLETED",
"purchase_units": [
{
"payments": {
"captures": [
{
"status": "COMPLETED"
}
]
}
}
],
"payment_source": {
"paypal": {
"attributes": {
"vault": {
"id": "vault_id_123"
}
}
}
}
}
}

Error examples

{
"code": -1,
"message": "failed to confirm order: error message"
}

paypal/check_payment¶

Checks if a subscription payment has been made recently to confirm an order.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `check_payment`
token	✅	string	Authentication token.
subscription_id	✅	string	The PayPal subscription ID to check transactions for.
invoice_id	❌	integer	The unique identifier of the invoice to be processed.
billing	❌	string	The billing system or platform name used for processing.

Request example

curl -s "https://invapi.hostkey.com/paypal.php" -X POST \
--data "action=check_payment" \
--data "token=HOSTKEY_TOKEN" \
--data "subscription_id=VALUE"

Success response example

{
"result": -1,
"error": "PayPal is not available for USD customers"
}

Error examples

{
"code": -1,
"message": "PayPal is not available for USD customers"
}

paypal/check_subscription¶

Verifies the status of a PayPal subscription via transaction history.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `check_subscription`
token	✅	string	Authentication token.
error_description	✅	string	Error description for session initialization failure.
subscription_id	✅	string	The unique identifier of the PayPal subscription to check.
transactions	✅	string	Параметр `transactions`
invoice_id	❌	string	The unique identifier for the invoice associated with the subscription.
billing	❌	string	The billing system or platform name used for processing transactions.

Request example

curl -s "https://invapi.hostkey.com/paypal.php" -X POST \
--data "action=check_subscription" \
--data "token=VALUE" \
--data "error_description=VALUE" \
--data "subscription_id=VALUE" \
--data "transactions=VALUE"

Success response example

{
"result": "OK",
"action": "check_subscription",
"data": {
"resource": {
"invoice_id": 123,
"custom_id": "whmcs",
"seller_receivable_breakdown": {
"paypal_fee": {
"value": "0.50"
}
},
"amount": {
"value": "49.99",
"currency_code": "EUR"
},
"id": "TRANS-ID",
"status": "COMPLETED",
"origin": "new subscription sub_123",
"subscription_id": "sub_123"
}
}
}

Error examples

{
"code": -1,
"message": "failed to get transactions"
}

paypal/create_order¶

Creates a PayPal order or payment, optionally enabling vaulting.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_order`
token	✅	string	Authentication token.
invoice_id	❌	string	The unique identifier of the invoice to be processed.
vault	❌	integer	Flag indicating whether to use PayPal vault for recurring payments.
billing	❌	string	The billing system or configuration name used for the transaction.

Request example

curl -s "https://invapi.hostkey.com/paypal.php" -X POST \
--data "action=create_order" \
--data "token=HOSTKEY_TOKEN"

Success response example

{
"result": "OK",
"action": "create_order",
"data": {
"id": "ORD-XXXXXXXXX",
"status": "APPROVAL_PENDING",
"purchase_units": []
}
}

Error examples

{
"code": -1,
"message": "PayPal is not available for USD customers"
}

paypal/create_payment_token¶

Creates a PayPal payment token to enable automatic recurring payments (Vault).

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_payment_token`
token	✅	string	Authentication token.
setup_token_id	✅	string	The unique identifier for the PayPal setup token used to create a vault.
billing	❌	string	The billing profile or account name used for processing payments.

Request example

curl -s "https://invapi.hostkey.com/paypal.php" -X POST \
--data "action=create_payment_token" \
--data "token=HOSTKEY_TOKEN" \
--data "setup_token_id=VALUE"

Success response example

{
"result": "OK",
"vault_id": "vault_abc123"
}

Error examples

{
"code": -1,
"message": "missing setup_token_id"
}

paypal/create_setup_token¶

Initializes a PayPal setup token for recurring billing.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_setup_token`
token	✅	string	Authentication token.
whmcs_id	✅	integer	The unique identifier of the WHMCS customer.
billing	✅	string	Billing related parameter for PayPal setup token creation.

Request example

curl -s "https://invapi.hostkey.com/paypal.php" -X POST \
--data "action=create_setup_token" \
--data "token=HOSTKEY_TOKEN" \
--data "whmcs_id=VALUE" \
--data "billing=VALUE"

Success response example

{
"result": "OK",
"action": "create_setup_token",
"data": {
"id": "SETUP-TOKEN-ID"
}
}

Error examples

{
"code": -1,
"message": "PayPal is not available for USD customers"
}

paypal/create_subscription¶

Creates a new PayPal subscription for the customer based on an invoice.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_subscription`
token	✅	string	Authentication token.
invoice_id	❌	string	The unique identifier of the invoice associated with the subscription.
billing	❌	string	The billing system or provider name used for processing.

Request example

curl -s "https://invapi.hostkey.com/paypal.php" -X POST \
--data "action=create_subscription" \
--data "token=HOSTKEY_TOKEN"

Success response example

{
"result": "OK",
"action": "create_subscription",
"resource": {
"invoice_id": 123,
"custom_id": "whmcs",
"seller_receivable_breakdown": {
"paypal_fee": {
"value": "0.50"
}
},
"amount": {
"value": "49.99",
"currency_code": "EUR"
},
"id": "PAYPAL_TRANS_ID",
"status": "COMPLETED",
"origin": "new subscription 123",
"subscription_id": "SUB_ID_456"
}
}

Error examples

{
"code": -1,
"message": "PayPal is not available for USD customers"
}

paypal/revoke_vault¶

Revokes a PayPal payment vault associated with the client.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `revoke_vault`
token	✅	string	Authentication token.
vault_id	✅	integer	The unique identifier of the PayPal vault to be revoked.
billing	❌	string	The billing system or identifier used for customer data retrieval.

Request example

curl -s "https://invapi.hostkey.com/paypal.php" -X POST \
--data "action=revoke_vault" \
--data "token=HOSTKEY_TOKEN" \
--data "vault_id=VALUE"

Success response example

{
"result": "OK"
}

Error examples

{
"code": -1,
"message": "vault 123 is not owned by client 456"
}