PlanPay API reference (1.0.0)
Download OpenAPI specification:Download
The PlayPay API reference provides detailed documentation for developers to integrate with PlayPay's payment system. Explore endpoints, authentication methods, error codes, and request/response formats to enable seamless integration. An interactive version of this spec is available at https://portal.planpay.com/docs/openapi
query.plan.getPlans
query Parameters
page | number Default: 0 The page of data you will fetch. Starts at 0. This is combined with the |
cursor | string DEPRECATED 2023-07-13. Offset pagination is only supported with this API. Use a combination of |
userId | string The user ID to filter plans created by a particular user |
merchantId | string The merchant ID to filter plans associated with a particular merchant |
limit | number [ 1 .. 100 ] Default: 50 The number of results per page |
sortField | string Default: "createdAt" The field to sort by |
sortDirection | string Default: "desc" Enum: "asc" "desc" Sort direction to use, either ASC or DESC |
useQuickFilter | boolean Default: false Specify whether quick filtering is used or not |
quickFilterValue | string The quick filter value to filter by |
filterField | string The field to filter by |
filterValue | string The values of the field to filter by |
filterOperator | string Default: "equals" Enum: "equals" "contains" "not" "in" "notIn" "lt" "lte" "gt" "gte" "startsWith" "endsWith" "is" "isNot" The operator to use for the filter |
status | string Enum: "OnSchedule" "Late" "Completed" "Cancelled" "PendingDeposit" DEPRECATED 2023-07-13. Use the |
updatedAfter | string <date-time> Only show plans that have been updated after a date and time. This can be useful when synchronizing data |
Responses
Response samples
- 200
- default
{- "nextCursor": "string",
- "totalRowCount": 0,
- "plans": [
- {
- "status": "OnSchedule",
- "installmentFrequency": "Weekly",
- "cadenceOnDayOfWeek": "Monday",
- "cancellationReason": "CustomerRequest",
- "checkoutType": "Web",
- "id": "string",
- "merchantId": "string",
- "currencyCode": "string",
- "pausePaymentUntil": "2019-08-24T14:15:22Z",
- "cadenceOnDayOfMonth": 0,
- "timeZone": "string",
- "serviceFeePercentage": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "minimumDepositAmount": 0,
- "merchantOrderId": "string",
- "cancellationDetails": "string",
- "subMerchantId": "string",
- "createdByUserId": "string",
- "totalPaid": 0,
- "completionDate": "2019-08-24T14:15:22Z",
- "items": [
- {
- "minimumDepositPerItemType": "Currency",
- "status": "Active",
- "id": "string",
- "sku": "string",
- "merchantProductURL": "string",
- "quantity": 0,
- "description": "string",
- "costPerItem": 0,
- "minimumDepositPerItemValue": 0,
- "depositRefundable": true,
- "redemptionDate": "2019-08-24T14:15:22Z",
- "paymentDeadline": 0,
- "planId": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}
], - "user": {
- "id": "string",
- "emailAddress": "string",
- "phoneNumber": "string",
- "firstName": "string",
- "lastName": "string",
- "status": "Active",
- "createdAt": "2019-08-24T14:15:22Z"
}, - "merchant": {
- "id": "string",
- "name": "string"
}, - "subMerchant": {
- "externalCode": "string"
}
}
]
}
Response samples
- 200
- default
{- "status": "OnSchedule",
- "installmentFrequency": "Weekly",
- "cadenceOnDayOfWeek": "Monday",
- "cancellationReason": "CustomerRequest",
- "checkoutType": "Web",
- "id": "string",
- "merchantId": "string",
- "pausePaymentUntil": "2019-08-24T14:15:22Z",
- "cadenceOnDayOfMonth": 0,
- "timeZone": "string",
- "serviceFeePercentage": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "minimumDepositAmount": 0,
- "merchantOrderId": "string",
- "cancellationDetails": "string",
- "subMerchantId": "string",
- "createdByUserId": "string",
- "currency": {
- "currencyCode": "string",
- "label": "string",
- "currencySymbol": "string",
- "maximumPaymentAmount": 0,
- "minimumPaymentAmount": 0
}, - "merchant": {
- "defaultMinimumDepositType": "Currency",
- "status": "Active",
- "id": "string",
- "name": "string",
- "companyEmail": "string",
- "phoneNumber": "string",
- "merchantSupportEmail": "string",
- "customerSupportEmail": "string",
- "merchantPageUrl": "string",
- "defaultPaymentDeadlineInDays": 0,
- "serviceFeePercentage": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "defaultMinimumDepositValue": 0,
- "defaultMarkupFeePercentage": 0,
- "defaultTransactionFeeIncludedSalesTax": 0,
- "countryAlpha3Code": "string",
- "googleAnalyticsMeasurementID": "string",
- "merchantGroupId": "string"
}, - "items": [
- {
- "minimumDepositPerItemType": "Currency",
- "status": "Active",
- "id": "string",
- "sku": "string",
- "merchantProductURL": "string",
- "quantity": 0,
- "description": "string",
- "costPerItem": 0,
- "minimumDepositPerItemValue": 0,
- "depositRefundable": true,
- "redemptionDate": "2019-08-24T14:15:22Z",
- "paymentDeadline": 0,
- "planId": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}
], - "user": {
- "id": "string",
- "emailAddress": "string",
- "phoneNumber": "string",
- "firstName": "string",
- "lastName": "string",
- "status": "Active",
- "createdAt": "2019-08-24T14:15:22Z"
}, - "createdByUser": {
- "id": "string",
- "emailAddress": "string",
- "firstName": "string",
- "lastName": "string"
}, - "userPaymentMethod": {
- "cardBrand": "Unknown",
- "funding": "Credit",
- "id": "string",
- "default": true,
- "userPaymentIdentityId": "string",
- "description": "string",
- "last4Digits": "string",
- "expMonth": 0,
- "expYear": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z"
}, - "installments": [
- {
- "installmentNumber": 0,
- "date": "2019-08-24T14:15:22Z",
- "status": "UPCOMING",
- "amount": 0,
- "paymentMethod": "string",
- "transactionId": "string"
}
], - "description": "string",
- "installmentAmount": 0,
- "merchantName": "string",
- "subMerchantName": "string",
- "numPaidInstallments": 0,
- "numberOfInstallments": 0,
- "planCompletionDate": "2019-08-24T14:15:22Z",
- "redemptionDate": "2019-08-24T14:15:22Z",
- "totalCost": 0,
- "totalPaid": 0,
- "remainingAmount": 0,
- "refundAmount": 0,
- "cancellationDate": "2019-08-24T14:15:22Z",
- "planpayFees": 0,
- "merchantRevenue": 0,
- "transactionFeesPaid": 0,
- "maxPayment": 0
}
mutation.plan.updatePlan
path Parameters
planId required | string |
Request Body schema: application/jsonrequired
merchantOrderId required | string |
Responses
Request samples
- Payload
{- "merchantOrderId": "string"
}
Response samples
- 200
- default
{- "planId": "string",
- "merchantOrderId": "string"
}
Response samples
- 200
- default
{- "planTotalCost": 0,
- "totalPaymentsPaid": 0,
- "currencyCode": "string",
- "totalNonRefundableAmount": 0,
- "suggestedRefundAmount": 0,
- "items": [
- {
- "id": "string",
- "name": "string",
- "quantity": 0,
- "costPerItem": 0,
- "totalCost": 0,
- "minNonRefundableDeposit": 0,
- "nonRefundableAmount": 0,
- "refundPolicies": [
- {
- "activeFrom": "2019-08-24T14:15:22Z",
- "name": "string",
- "nonRefundableAmount": 0
}
], - "activeRefundPolicyIndex": 0
}
]
}
mutation.plan.cancelPlan
path Parameters
planId required | string |
Request Body schema: application/jsonrequired
refundableAmount required | number |
reason required | string Enum: "CustomerRequest" "MerchantRequest" "PaymentIssue" "MerchantRequestWithPaymentLink" "Other" |
details | string |
Responses
Request samples
- Payload
{- "refundableAmount": 0,
- "reason": "CustomerRequest",
- "details": "string"
}
Response samples
- 200
- default
{- "result": "string"
}
Response samples
- 200
- default
{- "defaultPaymentDeadline": 0,
- "defaultMinDepositValue": 0,
- "defaultMinDepositType": "string",
- "currencies": [
- {
- "minimumPaymentAmount": 0,
- "maximumPaymentAmount": 0,
- "currencyCode": "string",
- "paymentGatewayVariant": "string"
}
]
}
mutation.checkout.createCheckout
Request Body schema: application/jsonrequired
type | string Default: "plan" Value: "plan" A property that specifies the type of checkout requested. Only |
merchantId required | string [ 5 .. 256 ] characters ^((?! ).)*$ The merchant's unique ID provided by PlanPay. Must match the merchant ID value from the |
externalCode | string [ 5 .. 128 ] characters ^((?! ).)*$ Merchants can use |
merchantOrderId required | string [ 1 .. 256 ] characters ^((?! ).)*$ The unique order ID in the merchant's order database. Example: |
currencyCode required | string = 3 characters ^((?! ).)*$ The ISO 4217 currency code used for the transaction. Example: provide |
redirectURL required | string <uri> [ 5 .. 2048 ] characters ^((?! ).)*$ A URL on the merchant's website to redirect the customer back to once the transaction has been completed or rejected. Should be a HTTPS URL. Example: |
callbackURL | string <uri> [ 5 .. 2048 ] characters ^((?! ).)*$ Deprecated as of 2023-04-18. Use merchant-level webhook instead. |
expiry | number >= 0 Default: 1440 You can set an optional expiry time for the checkout object, which determines how long it will remain valid and able to complete a checkout, expressed in whole minutes. If no expiry time is provided, the default value is |
required | Array of objects non-empty This property holds an array of checkout item objects that collectively define the items included in a checkout, along with their respective costs, quantities, and other relevant details. |
Responses
Request samples
- Payload
{- "type": "plan",
- "merchantId": "string",
- "externalCode": "string",
- "merchantOrderId": "string",
- "currencyCode": "str",
- "expiry": 1440,
- "items": [
- {
- "sku": "string",
- "quantity": 1,
- "description": "string",
- "costPerItem": 0.01,
- "minimumDepositPerItem": {
- "unit": "Currency",
- "value": 0
}, - "depositRefundable": true,
- "redemptionDate": "2019-08-24T14:15:22Z",
- "paymentDeadline": 0,
- "refundPolicies": [
- {
- "type": "percentage_refundable_days_within_redemption_date",
- "daysWithinRedemptionDate": 0,
- "refundablePercentage": 100
}
]
}
]
}
Response samples
- 200
- default
{- "id": "string",
- "created": "string",
- "merchantId": "string",
- "merchantOrderId": "string",
- "totalCost": 0,
- "totalMinimumDeposit": 0,
- "completionDate": "string",
- "currencyCode": "string",
- "redirectURL": "string",
- "callbackURL": "string",
- "items": [
- {
- "id": "string",
- "sku": "string",
- "merchantProductURL": "string",
- "quantity": 0,
- "description": "string",
- "costPerItem": 0,
- "minimumDepositPerItem": {
- "unit": "Currency",
- "value": 0
}, - "depositRefundable": true,
- "redemptionDate": "string",
- "paymentDeadline": 0,
- "refundPolicies": [
- {
- "type": "string",
- "daysWithinRedemptionDate": 0,
- "refundablePercentage": 0
}
]
}
], - "checkoutWorkflow": {
- "sdkWidget": {
- "type": "string",
- "id": "string",
- "scriptUrl": "string"
}
}
}
query.checkout.calculatePlan
path Parameters
checkoutId required | string |
Request Body schema: application/jsonrequired
type required | string Value: "plan" |
object | |
object | |
timeZone required | string |
Responses
Request samples
- Payload
{- "type": "plan",
- "deposit": {
- "amount": 0
}, - "installments": {
- "cadence": {
- "frequency": "Weekly",
- "on": {
- "dayOfWeek": "Monday",
- "dayOfMonth": 0
}
}
}, - "timeZone": "string"
}
Response samples
- 200
- default
{- "type": "plan",
- "deposit": {
- "amount": 0,
- "range": {
- "min": 0,
- "max": 0
}
}, - "installments": {
- "amount": 0,
- "remainder": 0,
- "count": 0,
- "cadence": {
- "frequency": "Weekly",
- "on": {
- "dayOfWeek": "Monday",
- "dayOfMonth": 0
}
}, - "validation": [
- {
- "key": "string",
- "value": "string"
}
]
}, - "totalCost": 0,
- "currencyCode": "string",
- "redirectURL": "string"
}
mutation.checkout.finalisePlan
path Parameters
checkoutId required | string |
Request Body schema: application/jsonrequired
type required | string Value: "plan" |
object | |
object | |
timeZone required | string |
paymentMethodId required | string |
paymentPlatformVendor required | string Enum: "Stripe" "Adyen" "Braintree" "Mint" "Flywire" |
remainder required | number |
threeDAuthToken | string or null |
object |
Responses
Request samples
- Payload
{- "type": "plan",
- "deposit": {
- "amount": 0
}, - "installments": {
- "cadence": {
- "frequency": "Weekly",
- "on": {
- "dayOfWeek": "Monday",
- "dayOfMonth": 0
}
}
}, - "timeZone": "string",
- "paymentMethodId": "string",
- "paymentPlatformVendor": "Stripe",
- "remainder": 0,
- "threeDAuthToken": "string",
- "paymentData": {
- "id": "string",
- "cardToken": "string",
- "currencyCode": "string",
- "card": {
- "last4Digits": "string",
- "expMonth": 0,
- "expYear": 0,
- "cardBrand": "Unknown",
- "funding": "Credit"
}, - "merchantPaymentPlatformId": "string",
- "userPaymentIdentityId": "string"
}
}
Response samples
- 200
- default
{- "id": "string"
}