Purchase API Guide

The Purchase API allows you to retrieve information about the purchases of your products.

In this guide, you can find information to help you understand and integrate the following Purchase API resources:

Get Purchase

GET /purchase/getpurchase?purchaseid={purchaseid}&reimbursementid={reimbursementid}

The Get Purchase V1 endpoint retrieves all information about a particular purchase. When you make a call, you get a PurchaseType element. The element contains a collection of purchase items, including customer information, the product(s) that were purchased by the customer, pricing information, and other customized data (for example: x-parameters and license keys) that are related to the purchase.

Get Purchase List

GET /purchase/getpurchaselist?startdatetime={startdatetime}&enddatetime={enddatetime}&purchasestatusids={purchasestatusids}

The Get Purchase List endpoint retrieves an extensive list of purchases for a specified time period.

Get Purchase List By IDs

GET /purchase/getpurchaselistbyids?startpurchaseid={startpurchaseid}&endpurchaseid={endpurchaseid}&purchasestatusids={purchasestatusids}

The Get Purchase List endpoint retrieves a list purchases for a specified range of PurchaseIDs or ReimbursementIDs.

Update License Key

POST /purchase/updatelicensekey

The Update License Key resource updates the license key for an item in an existing purchase.

Update Purchase Parameters

GET /purchase/updatepurchaseparameters

The Update Purchase Parameters endpoint updates the x-parameters for a purchase. If the parameter key existed in the purchase, the parameter value will be overwritten. If the parameter key did not exist in the purchase, the parameter key and value pair will be created.

Retry Payment

POST /purchase/retrypayment

When a payment is declined by the credit card issuer, the Retry Payment endpoint retries payment for the purchase up to the max of the following:

• Up to 8 times in addition to the first failed attempt (This is also limited by the maximum retries allowed by the credit card provider)

• The maximum number of retries specified in your account by the Cleverbridge Client Experience team.

Important

When you use the Retry Payment endpoint to set up payment retries, the Cleverbridge retry schedule gets deactivated. For more information, see Retry Logic in Collect Failed Online Payments Automatically.

When the payment is declined by the credit card issuer, the purchase status is Payment Declined by Card Issuer. For more information, see Purchase Status.

To set up retries:

  1. Contact the Cleverbridge Client Experience team to ensure:
    • The Retry Failed Payments option in your account is enabled to use the Retry Payment endpoint.
    • The number of retries to be made is specified in your account.
  2. Submit the relevant PurchaseId. You can retrieve the relevant PurchaseID from the GetPurchase API. Or you can get the PurchaseID from the payment declined notification.

Important

Retry attempts are more likely to be successful when they are triggered at certain intervals. To set the best retry frequency/interval, contact the Cleverbridge Client Experience team.

Cancel Retry

POST /purchase/cancelretry

The Cancel Retry endpoint cancels a retry attempt that was scheduled after a customer's payment failed. To cancel a scheduled retry, submit the PurchaseId that you received in the response payload from the Process Cart API endpoint. To learn whether a retry has been scheduled, see the IsPaymentRetryScheduled field in the Process Cart response. For more information, see Process Cart.

Important

If you receive a CCA_EXP status in PaymentResult.Code field in the Process Cart response, then a payment retry has been scheduled for one hour after an immediate call to the Cleverbridge Expiration Date Checker. In this situation, it is not possible to cancel the scheduled payment retry. For more information, see Process Cart.