Skip to main content
API docs by Redocly

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

plans

query.plan.getPlans

query Parameters
page
number
Default: 0

The page of data you will fetch. Starts at 0. This is combined with the limit field to provide a result

cursor
string

DEPRECATED 2023-07-13. Offset pagination is only supported with this API. Use a combination of page and limit to get the results you want

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 filterValue field to filter plan statuses instead

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

Content type
application/json
{
  • "nextCursor": "string",
  • "totalRowCount": 0,
  • "plans": [
    ]
}

query.plan.getPlan

path Parameters
planId
required
string

Responses

Response samples

Content type
application/json
{
  • "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": {
    },
  • "merchant": {
    },
  • "items": [
    ],
  • "user": {
    },
  • "createdByUser": {
    },
  • "userPaymentMethod": {
    },
  • "installments": [
    ],
  • "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/json
required
merchantOrderId
required
string

Responses

Request samples

Content type
application/json
{
  • "merchantOrderId": "string"
}

Response samples

Content type
application/json
{
  • "planId": "string",
  • "merchantOrderId": "string"
}

query.plan.getPlanCancellationSummary

path Parameters
planId
required
string

Responses

Response samples

Content type
application/json
{
  • "planTotalCost": 0,
  • "totalPaymentsPaid": 0,
  • "currencyCode": "string",
  • "totalNonRefundableAmount": 0,
  • "suggestedRefundAmount": 0,
  • "items": [
    ]
}

mutation.plan.cancelPlan

path Parameters
planId
required
string
Request Body schema: application/json
required
refundableAmount
required
number
reason
required
string
Enum: "CustomerRequest" "MerchantRequest" "PaymentIssue" "MerchantRequestWithPaymentLink" "Other"
details
string

Responses

Request samples

Content type
application/json
{
  • "refundableAmount": 0,
  • "reason": "CustomerRequest",
  • "details": "string"
}

Response samples

Content type
application/json
{
  • "result": "string"
}

merchant

query.merchant.merchandisingDefaults

path Parameters
merchantId
required
string

Responses

Response samples

Content type
application/json
{
  • "defaultPaymentDeadline": 0,
  • "defaultMinDepositValue": 0,
  • "defaultMinDepositType": "string",
  • "currencies": [
    ]
}

checkout

mutation.checkout.createCheckout

Request Body schema: application/json
required
type
string
Default: "plan"
Value: "plan"

A property that specifies the type of checkout requested. Only plan is currently supported.

merchantId
required
string [ 5 .. 256 ] characters ^((?! ).)*$

The merchant's unique ID provided by PlanPay. Must match the merchant ID value from the Authorization header provided with the request. Example: 8b4f37d2e6a1.

externalCode
string [ 5 .. 128 ] characters ^((?! ).)*$

Merchants can use externalCode to identify a specific sub-merchant. For example, a merchant may have properties in different locations, such as Sydney with an externalCode of SYD and New York with an externalCode of NYC. The externalCode must match one of the sub-merchant externalCode values that they have configured via the portal.

merchantOrderId
required
string [ 1 .. 256 ] characters ^((?! ).)*$

The unique order ID in the merchant's order database. Example: YCPNY-J6P7VZ.

currencyCode
required
string = 3 characters ^((?! ).)*$

The ISO 4217 currency code used for the transaction. Example: provide USD for United States dollar.

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: https://www.yourcompany.com/shopping-cart/outcome?saleId=YCPNY-J6P7VZ.

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 1440 minutes (one day). Example: 60 (for 1 hour).

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

Content type
application/json
{
  • "type": "plan",
  • "merchantId": "string",
  • "externalCode": "string",
  • "merchantOrderId": "string",
  • "currencyCode": "str",
  • "redirectURL": "http://example.com",
  • "callbackURL": "http://example.com",
  • "expiry": 1440,
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "string",
  • "merchantId": "string",
  • "merchantOrderId": "string",
  • "totalCost": 0,
  • "totalMinimumDeposit": 0,
  • "completionDate": "string",
  • "currencyCode": "string",
  • "redirectURL": "string",
  • "callbackURL": "string",
  • "items": [
    ],
  • "checkoutWorkflow": {
    }
}

query.checkout.getCheckoutStatus

path Parameters
checkoutId
required
string

Responses

Response samples

Content type
application/json
null

query.checkout.calculatePlan

path Parameters
checkoutId
required
string
Request Body schema: application/json
required
type
required
string
Value: "plan"
object
object
timeZone
required
string

Responses

Request samples

Content type
application/json
{
  • "type": "plan",
  • "deposit": {
    },
  • "installments": {
    },
  • "timeZone": "string"
}

Response samples

Content type
application/json
{
  • "type": "plan",
  • "deposit": {
    },
  • "installments": {
    },
  • "totalCost": 0,
  • "currencyCode": "string",
  • "redirectURL": "string"
}

mutation.checkout.finalisePlan

path Parameters
checkoutId
required
string
Request Body schema: application/json
required
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

Content type
application/json
{
  • "type": "plan",
  • "deposit": {
    },
  • "installments": {
    },
  • "timeZone": "string",
  • "paymentMethodId": "string",
  • "paymentPlatformVendor": "Stripe",
  • "remainder": 0,
  • "threeDAuthToken": "string",
  • "paymentData": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string"
}

query.checkout.getUserHint

Responses

Response samples

Content type
application/json
{
  • "checkoutId": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "emailAddress": "string",
  • "phoneNumber": "string",
  • "key": "string"
}