Skip to main content

API Overview

PayPro Global API is a REST API that provides simple API endpoints to automate data on your subscriptions, products, orders, customers, and affiliates.

The communication method is POST.

PayPro Global API requests need authentication by passing both of the following parameters:

  1. VendorAccountId: can be found in your PayPro Global account in Account settings -> Business info.
  2. ApiSecretKey: is generated upon request to your personal account manager at [email protected]
    Once generated, it will also be visible your PayPro Global account in Store settings -> General settings -> Integration tab.

Also, API calls are verified by IP. Hence, to use API, you will need to send the list of your IP addresses to [email protected], and our team will whitelist them in the system.

Important:

  • Store the ApiSecretKey in a secure place for future reference.
  • The ApiSecretKey is a unique authentication token for your API calls and should never be exposed publicly in your resources.
    If a breach occurs, you will need to regenerate the key, apply it on production and revoke the old key. Please contact your account manager for help.

API Requests Use Cases Overview

Affiliates

Automate affiliate actions.

Request Sampleapplication/json
{
"affiliateAgreementId": 1,
"orderId": 5458995,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
The purchase was made with the affiliate's help, but no dedicated PayPro Global affiliate links were used, and no commission was distributed to the affiliate. You can assign the affiliate agreement ID to the existing order for proper commission re-calculation and further tracking purposes.

Usage notes:
  • Affiliate agreement ID will only be implemented for orders with products mentioned in the agreement.
  • The affiliate's commission will be recalculated taking into account the active agreement settings, gross or net order value, selected market.
  • If the product has an active subscription, the affiliate agreement ID will be implemented only to that particular order. If you want to apply it to your recurring payments, then please use the method api/Affiliates/AssignToSubscription.

Request Sampleapplication/json
{
"affiliateAgreementId": 1,
"subscriptionId": 954874,
"payAffiliateForPastCharges": true,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
The purchase was made with the affiliate's help, but no dedicated PayPro Global affiliate links were used and no commission was distributed to the affiliate. You can assign the affiliate agreement ID to the existing subscription and recalculate the affiliate's commission for past subscription payments (if needed).

Usage notes:
  • Affiliate agreement ID will only be implemented in relation to subscriptions for the products that are mentioned in the agreement.
  • The affiliate's commission will be applied to the future subscription payments.
  • The affiliate's commission will be recalculated taking into account the active agreement settings, gross or net order value, selected market.

Customers

Request Sampleapplication/json
{
"customerEmail": "[email protected]",
"orderId": 5482730,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a customer, and you want him to have a simplified option to log in to his PayPro Global customer account to update his payment information for the subscription. If you use this method, the customer will receive an email with a one-time link to log in, valid for 15 minutes, with no need for him to enter his login & password.

Usage note:
  • The email template is a generic for all vendor accounts.

Subscriptions

Automate subscription actions.

Request Sampleapplication/json
{
"newSubscriptionName": "Monthly premium subscription plan plus 5 extra packages",
"sendCustomerNotification": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a subscription and you need to change the subscription name in the system because of upgrades, downgrades, or any other reason.

Usage note:
  • You can change the name only for one subscription at a time.

Request Sampleapplication/json
{
"quantity": 1,
"newSubscriptionName": "Monthly premium subscription plan plus 5 extra packages",
"sendCustomerNotification": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a subscription, and you need to update its quantity considering the current amount and current subscription total price. It is often used to update the subscriptions with the per-seat model.

Usage note:
  • Formula for calculations: (PreviousSubscriptionPrice / PreviousSubscriptionQuanitity) * NewSubscriptionQuanitity.

Request Sampleapplication/json
{
"newPriceValue": 49.95,
"priceCurrencyCode": "USD",
"quantity": 1,
"newSubscriptionName": "Monthly premium subscription plan plus 5 extra packages",
"sendCustomerNotification": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a subscription and need to update its recurring price for a particular customer because of upgrades, downgrades, or other reasons.

Usage notes:
  • The price you define in NewPriceValue will update the total price regardless of the quantity value you provide in Quantity.
  • The currency of the existing subscription cannot be changed.

Request Sampleapplication/json
{
"productId": 37491,
"newPriceValue": 49.95,
"priceCurrencyCode": "USD",
"quantity": 1,
"newSubscriptionName": "Monthly premium subscription plan plus 5 extra packages",
"sendCustomerNotification": true,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You decided to update the price for your products. At the same time, you have many existing subscriptions and you want to update their prices in the system for the upcoming recurring payments.

Usage notes:
  • The price you define in NewPriceValue will update the total price regardless of the quantity value you provide in Quantity.
  • The currency of the existing subscriptions cannot be changed.
  • Bulk API calls are not instant. They create a delayed task in the system that will be executed within a one-hour window.

Request Sampleapplication/json
{
"newBillingPeriodTypeId": 3,
"newBillingPeriodValue": 2,
"newSubscriptionName": "Monthly premium subscription plan plus 5 extra packages",
"sendCustomerNotification": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a subscription, and you need to update its billing period for a particular customer because of an upgrade, downgrade, or any other reason.

Usage note:
  • BillingPeriodTypeId: 1 - Days, 2 - Weeks, 3 - Months, 4 - Years.

Request Sampleapplication/json
{
"renewalTypeId": 1,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
There are two renewal types, automatic and manual. You have a subscription, and the customer wants to switch from the automatic subscription to the manual or vice versa.

Usage notes:
  • The renewal type can be always be changed from automatic to manual.
  • The subscription can be changed to automatic renewal if it has an active debit/credit card attached or it was paid with PayPal.

Request Sampleapplication/json
{
"newNextPaymentDate": "2022-11-16T03:39:34.4662305-05:00",
"shiftPaymentSchedule": true,
"newSubscriptionName": "Monthly premium subscription plan plus 5 extra packages",
"sendCustomerNotification": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a subscription and need to update the next charge date. You can change it only for the upcoming payment or shift all following payments according to the updated next payment date.


Request Sampleapplication/json
{
"newTrialPeriodEndDate": "2022-11-16T07:29:34.6173213-05:00",
"newSubscriptionName": "Monthly premium subscription plan plus 5 extra packages",
"sendCustomerNotification": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a customer on trial, and you want to update his trial period by extending or reducing it.


Request Sampleapplication/json
{
"cancellationReasonId": 1,
"reasonText": "sample string 1",
"sendCustomerNotification": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have an active subscription and need to cancel it with the ability to renew it later.


Request Sampleapplication/json
{
"subscriptionIds": [
1,
2
],
"sendVendorEmail": true,
"sendCustomerEmail": true,
"sendIpn": true,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a bulk of subscriptions that need to be canceled with the option to renew them later.

Usage note:
  • Bulk API calls are not instant. They create a delayed task in the system that will be executed within a one-hour window.

Request Sampleapplication/json
{
"cancellationReasonId": 1,
"reasonText": "sample string 1",
"sendCustomerNotification": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to cancel an active subscription without the ability to renew it later by yourself or the customer.

Usage note:
  • Subscriptions with the status Terminated can be renewed from PayPro Global's side.

Request Sampleapplication/json
{
"subscriptionIds": [
1,
2
],
"sendVendorEmail": true,
"sendCustomerEmail": true,
"sendIpn": true,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a bulk of subscriptions which needs to be terminated.

Usage note:
  • Bulk API calls are not instant. They create a delayed task in the system that will be executed within a one-hour window.

Request Sampleapplication/json
{
"sendCustomerNotification": true,
"reasonText": "sample string 1",
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to stop a customer's subscription permanently without any option to renew it.


Request Sampleapplication/json
{
"subscriptionIds": [
1,
2
],
"sendVendorEmail": true,
"sendCustomerEmail": true,
"sendIpn": true,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a bulk of subscriptions which needs to be ended.

Usage note:
  • Bulk API calls are not instant. They create a delayed task in the system that will be executed within a one-hour window.

Request Sampleapplication/json
{
"reasonText": "sample string 1",
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to renew a customer's subscription.

Usage notes:
  • Only subscriptions with the Suspended status can be renewed.
  • If a subscription's due date is in the past, we will try to charge it immediately after a successful renewal.

Request Sampleapplication/json
{
"newMaxNumberOfBillingCycles": 1,
"newSubscriptionName": "Monthly premium subscription plan plus 5 extra packages",
"sendCustomerNotification": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a subscription with a fixed number of billing cycles as per your product settings defined in your PayPro Global account. You need to update the max number of billing cycles.

Usage note:
  • Once the defined number of billing cycles is used, subscriptions will get the Finished status.

Request Sampleapplication/json
{
"dateFormat": "sample string 1",
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to know all subscription details in real time for support and/or subscription management purposes.

Usage note:
  • We display the date in three different formats, and you can choose the one that suits you best.
Date format. Possible values:
  • a - "yyyy-MM-ddThh:mm:ss.fff"
  • b - "M/d/yyyy"
  • c - "d-MMM-yyyy"

Request Sampleapplication/json
{
"productId": 37491,
"quantity": 1,
"sendCustomerNotification": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to update the product for a particular subscription because of an upgrade/downgrade.

Usage notes:
  • The next payment date remains the same. Once the scheduled subscription payment occurs, the next payment date will be updated according to the billing cycle of the new product.
  • The payment amount is updated according to the new product settings.
  • Customers cannot be moved to a different product while on trial.

Request Sampleapplication/json
{
"discountValue": 1.0,
"isPercentage": true,
"applyDiscountForAllFuturePayments": true,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to apply a discount (value or percentage) to an existing subscription.

Usage notes:
  • If you selected isPercentage: false, the value you provided in DiscountValue will be treated as a regular amount in the currency the order was placed.
  • If the quantity is more than 1, the discount value will be multiplied by the quantity. For example, if the order total is $30, quantity is 3, you apply API discountvalue=5, isPercentage: false, the next charge amount will be 15.00 USD.
  • If you run this API method a few times for the same subscription, each new result overrides the previous one.

Request Sampleapplication/json
{
"discountValue": 1.0,
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have an existing customer with a subscription and want to give him two months of product usage for free. In this case, you can apply an accumulative discount to an existing subscription. The value in the body parameter discountValue should be equal to the amount of two subscription recurring payments. This way, the discount will be automatically applied and split between two subsequent recurring payments.

Usage note:
  • Any value can be provided in discountValue. If it is less than the next subscription charge amount, then this discount will be applied only to one upcoming subscription payment. If it exceeds the next subscription charge amount, then it will be applied to subsequent recurring payments accordingly.

Request Sampleapplication/json
{
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have an active subscription, and you need to additionally charge this customer for the defined subscription amount.

Usage notes:
  • No subscription price recalculation takes place.
  • The subscription's next payment date will be shifted according to its billing cycle.

For example, we have a monthly subscription. The next payment date is August 14, and the amount to be charged is $10. If you run this method, you will get an additional payment for the existing subscription for $10, and its next payment date will be switched to September 14, next payment amount of $10.

Request Sampleapplication/json
{
"customFields": {
"some-key-1": "your custom value 1",
"some-key-2": "your custom value 2"
},
"subscriptionId": 954874,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have a subscription and are using custom fields to pass additional custom information. If you need to change them, please use this method.

Products

Automate product actions.


Request Sampleapplication/json
{
"couponName": "sample string 1",
"percentageValue": 2,
"couponCodes": [
"sample string 1",
"sample string 2"
],
"validFrom": "2022-11-16T07:29:34.6954393-05:00",
"validTill": "2022-11-16T07:29:34.6954393-05:00",
"productIds": [
1,
2
],
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to create a discount coupon for a single product or a bulk of products.


Request Sampleapplication/json
{
"couponCodes": [
"sample string 1",
"sample string 2"
],
"useTestMode": true,
"secretKey": "sample string 1",
"paymentMethod": 1,
"ipAddress": "sample string 2",
"currency": "sample string 3",
"language": "sample string 4",
"billingCountry": "sample string 5",
"billingState": "sample string 6",
"billingZip": "sample string 7",
"products": [
{
"productId": 37491,
"quantity": 1
},
{
"productId": 37491,
"quantity": 1
}
],
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to get the product pricing based on the customer's data. This method can be used if you are offering a localized pricing model, and want to show local prices on your website and coincide them with the rate for local prices at PayPro Global.


Request Sampleapplication/json
{
"productIds": [
1,
2
],
"productNames": [
"sample string 1",
"sample string 2"
],
"productSKUs": [
"sample string 1",
"sample string 2"
],
"productStatusId": 1,
"productChargingTypeId": 1,
"languageCode": "sample string 1",
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to get specific details from your store products as ID, name, description, logo, and SKU for proper product management.

Orders

Automate order actions.


Request Sampleapplication/json
{
"skip": 1,
"take": 1,
"search": {
"orderIds": [
5458995,
5458996
],
"subscriptionId": 1,
"customerEmail": "[email protected]",
"orderStatusId": 1
},
"sortByDate": "sample string 1",
"includeTestOrders": false,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to get the list of orders along with the order details.

Usage notes:
  • By default, you will get 50 results.
  • You can get a maximum of 100 results per API call.
  • You can sort the results in ascending or descending order.

Request Sampleapplication/json
{
"referencedOrderId": 5458995,
"productId": 37491,
"priceCurrencyCode": "USD",
"priceValue": 99.95,
"referenceChargeName": "Monthly premium subscription plan plus 5 extra packages for May-2017",
"sku": "ABF-478-5297-RI",
"customFields": {
"some-key-1": "your custom value 1",
"some-key-2": "your custom value 2"
},
"orderItemDetails": [
{
"orderItemName": "sample string 1",
"unitPriceValue": 2.0,
"quantity": 3
},
{
"orderItemName": "sample string 1",
"unitPriceValue": 2.0,
"quantity": 3
}
],
"affiliateAgreementId": 1,
"convertToReferenceCurrency": true,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have an existing customer who already purchased your product, and his payment details are on file. You need to manage his future payments because either you track the usage and the customer pays based on that, or the price depends each time on the services provided or any other reason. Also, this method can be used for one-click purchases as you can charge the existing customer without the need to fill in customer details again.

Usage note:
  • The ProductId you will use for the charge could be a one-time fee product or a subscription. However, even if the product's charging type is a subscription, no new subscription will be created.

Request Sampleapplication/json
{
"orderIds": [
5458995,
5458996
],
"emailAddresses": [
"[email protected]",
"[email protected]"
],
"useDelayedRefund": false,
"refundReason": "Product doesn't correspond to customer's expectation.",
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to refund the order(s).

Usage notes:
  • You can refund orders in bulk with this method, putting order IDs and/or emails via comma.
  • Bulk API calls are not instant. They create a delayed task in the system that will be executed within a one-hour window.

Request Sampleapplication/json
{
"orderItemId": 1,
"refundAmount": 2.0,
"changeSubscriptionPrice": true,
"refundReason": "Product doesn't correspond to customer's expectation.",
"cancelSubscription": true,
"subscriptionCancellationReasonText": "sample string 6",
"useDelayedRefund": false,
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You need to partially refund the ordered item.

Usage note:
  • The RefundAmount should be provided in the same currency in which the order was placed.

Request Sampleapplication/json
{
"orderId": 5458995,
"dateFormat": "sample string 2",
"vendorAccountId": 123456,
"apiSecretKey": "your_api_secret_key"
}

Use case:
You have an order and need to get all the order details.