# Create Pay Plan

Create a pay plan and payment token from a successful pay plan offer.
The payment token can be used to pay for an order for the matching amount and merchant.

If called with a customer JWT, the pay plan is created for that customer,
otherwise the customer must be provided via the Customer-Id request header.

Endpoint: POST /payplans
Version: 3.0
Security: Marketplace API Key | Merchant Public Token | Merchant Secret Token | Customer JWT | Merchant JWT | Marketplace JWT

## Request fields (application/json):

  - `termsAndConditionsAccepted` (boolean, required)
    Has the customer accepted the terms and conditions of the pay plan

  - `offerDetails` (object, required)
    Details of the pay plan offered to the customer

  - `offerDetails.merchantId` (string, required)
    System unique identifier for the merchant the pay plan was created for.

  - `offerDetails.customerId` (string, required)
    System unique identifier for the merchant customer who owns the pay plan.

  - `offerDetails.isCounterOffer` (boolean, required)
    Indicates that this is a revision (counter-offer) of a payment schedule proposed by the merchant customer.

  - `offerDetails.threeDSecureRequired` (boolean, required)
    When true, 3DS must be requested when paying for the order.

  - `offerDetails.payPlanParameters` (object)
    The parameters of the offered pay plan. If empty, the pay plan was declined outright.

  - `offerDetails.payPlanParameters.amount` (object, required)
    The full plan amount

  - `offerDetails.payPlanParameters.amount.minorCurrencyUnits` (integer, required)
    The amount in minor currency units (e.g. cents for AUD).

  - `offerDetails.payPlanParameters.amount.currency` (string, required)
    The currency of the given amount as a 3 letter ISO code.

  - `offerDetails.payPlanParameters.initialPayment` (integer, required)
    The amount that the customer will pay up front in minor currency units (eg cents for AUD). May be 0 if no upfront payment is required.

  - `offerDetails.payPlanParameters.instalmentLength` (integer, required)
    The number of instalment payments expected for this pay plan (min 2, max 52).

  - `offerDetails.payPlanParameters.instalmentFrequency` (string, required)
    The time period between instalments.
    Enum: "Weekly", "Fortnightly", "EveryFourWeeks", "EverySevenWeeks", "EveryThirtyDays", "EveryTenMinutes"

  - `offerDetails.payPlanParameters.proposedSchedule` (array)

  - `offerDetails.payPlanParameters.proposedSchedule.at` (string, required)

  - `offerDetails.payPlanParameters.proposedSchedule.amount` (integer, required)

  - `offerDetails.payPlanParameters.payPlanVariant` (string, required)
    The variant of the plan to construct. This implies the number of instalments; the minimum initialPayment expected; and the frequency of payments (e.g. fortnightly, weekly, etc.)
    Enum: "payplan_fortnight_25_25_25_25", "payplan_4_weekly_payments", "payplan_8_weekly_payments", "payplan_26_fortnightly_payments", "payplan_52_weekly_payments", "payplan_2_monthly_payments", "payplan_3_monthly_payments", "payplan_4_monthly_payments", "payplan_5_monthly_payments", "payplan_6_monthly_payments", "payplan_7_monthly_payments", "payplan_8_monthly_payments", "payplan_9_monthly_payments", "payplan_10_monthly_payments", "payplan_11_monthly_payments", "payplan_12_monthly_payments", "payplan_fortnight_0_100", "payplan_4_week_0_100", "payplan_7_week_0_100", "payplan_30_days_0_100"

  - `offerDetails.createdAt` (string, required)
    When the time limited offer was generated.

  - `offerVerificationToken` (string, required)
    Tamper detection digital signature

  - `paymentSource` (any, required)

  - `threeDsSessionId` (string)
    3DS session id, optional as it is only used in extended 3DS scenarios such as Cardinal 3DS2, which performs an extended device data check cycle returning a session id that is passed to the backend as part of the payment token data

  - `surchargeRequirement` (any)

## Response 200 fields (application/json):

  - `payPlan` (object, required)
    Details of the newly created pay plan

  - `payPlan.payPlanId` (string, required)
    System unique identifier for the pay plan

  - `payPlan.merchantId` (string, required)
    System unique identifier for the merchant the pay plan was created for

  - `payPlan.customerId` (string, required)
    System unique identifier for the merchant customer who owns the pay plan.

  - `payPlan.state` (string, required)
    These are all the statuses a pay plan can be in.

* Created - The pay plan object has been created, but has not been successfully associated with an order yet. No payment or money transfers will occur when the pay plan is in this state.
* Active - The pay plan has successfully been established, the initial payment, if any, has been received and one or more instalments are yet to be paid.
* Completed - The payment plan has been completely paid, including any fees/penalties.
* InDefault - The plan is overdue and has not been paid after several soft collection attempts.
    Enum: "Created", "Active", "Completed", "InDefault"

  - `payPlan.amount` (object, required)
    The full plan amount

  - `payPlan.amount.minorCurrencyUnits` (integer, required)
    The amount in minor currency units (e.g. cents for AUD).

  - `payPlan.amount.currency` (string, required)
    The currency of the given amount as a 3 letter ISO code.

  - `payPlan.surchargeAmount` (integer, required)
    The surcharge passed to the customer for creating this pay plan in minor currency units.

  - `payPlan.platformFee` (integer, required)
    The fee charged for creating this pay plan in minor currency units.

  - `payPlan.taxAmount` (integer, required)
    Tax owed by the merchant on the fees in minor currency units.

  - `payPlan.payPlanVariant` (string, required)
    The variant of the plan to construct. This implies the number of instalments; the minimum initialPayment expected; and the frequency of payments (e.g. fortnightly, weekly, etc.)
    Enum: "payplan_fortnight_25_25_25_25", "payplan_4_weekly_payments", "payplan_8_weekly_payments", "payplan_26_fortnightly_payments", "payplan_52_weekly_payments", "payplan_2_monthly_payments", "payplan_3_monthly_payments", "payplan_4_monthly_payments", "payplan_5_monthly_payments", "payplan_6_monthly_payments", "payplan_7_monthly_payments", "payplan_8_monthly_payments", "payplan_9_monthly_payments", "payplan_10_monthly_payments", "payplan_11_monthly_payments", "payplan_12_monthly_payments", "payplan_fortnight_0_100", "payplan_4_week_0_100", "payplan_7_week_0_100", "payplan_30_days_0_100"

  - `payPlan.nextInstalmentDate` (string)
    The next computed date in which an instalment should be charged.

  - `payPlan.nextInstalment` (integer)
    The instalment number of the next instalment.

  - `payPlan.planAmountOutstanding` (integer, required)
    The outstanding amount still to be paid on the plan in minor currency units.

  - `payPlan.paymentSourceType` (string)
    The type of payment source used to pay off the plan. Not present for source-less methods, such as bank transfers.
    Enum: "Card", "DirectDebit", "PayTo"

  - `payPlan.merchantOrderId` (string)
    System unique identifier for the order corresponding to this plan.

  - `payPlan.transactionId` (string)
    System unique identifier for the transaction corresponding to this plan.

  - `payPlan.charges` (array)
    All charges including failed attempts made on the pay plan.

  - `payPlan.charges.chargeId` (string, required)
    System unique identifier for the charge.

  - `payPlan.charges.amount` (integer, required)
    How much was charged in minor currency units.

  - `payPlan.charges.isSuccess` (boolean, required)
    Was the charge successfully captured.

  - `payPlan.charges.instalmentNumber` (integer)
    If this is a regular instalment charge, what instalment does it correspond to.

  - `payPlan.charges.instalmentCharge` (boolean)
    Was this charge made as part of a scheduled instalment payment.

  - `payPlan.charges.createdAt` (string, required)
    When the charge was created.

  - `payPlan.refunds` (array)
    All refunds applied to the pay plan.

  - `payPlan.refunds.refundId` (string, required)
    System unique identifier for the refund.

  - `payPlan.refunds.amount` (integer, required)
    How much was refunded in minor currency units.

  - `payPlan.refunds.createdAt` (string, required)
    When the refund was created.

  - `payPlan.isRefunded` (boolean, required)
    Has the pay plan been fully refunded.

  - `payPlan.isOverdue` (boolean, required)
    Is the pay plan overdue.

  - `payPlan.overdueAmount` (integer)
    If set, this is the amount that was expected to be paid on the last scheduled instalment but was not in minor currency units.

  - `payPlan.overdueAt` (string)
    If set, when the pay plan became overdue.

  - `payPlan.bankTransferDetails` (object)
    Details necessary to pay this pay plan via bank transfer. Only present if payment method is enabled for this merchant

  - `payPlan.bankTransferDetails.reference` (string, required)
    Reference to specify to link a bank transfer to this payment

  - `payPlan.bankTransferDetails.bankAccountNumber` (string, required)
    Account number to specify when paying via classic bank transfer

  - `payPlan.bankTransferDetails.bankAccountBsb` (string, required)
    BSB to specify when paying via classic bank transfer

  - `payPlan.bankTransferDetails.payId` (string, required)
    PayID to specify when paying via instant transfer

  - `payPlan.bankTransferDetails.metadata` (object, required)
    Extra information reserved for future use

  - `payPlan.createdAt` (string, required)
    When the pay plan was created.

  - `payPlan.updatedAt` (string, required)
    When the pay plan was last updated.

  - `paymentTokenId` (string, required)
    Payment token representing this pay plan used to pay for an order

## Response 400 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata

## Response 401 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata

## Response 403 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata

## Response 404 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata

## Response 405 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata

## Response 406 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata

## Response 409 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata

## Response 422 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata

## Response 429 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata

## Response 500 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata

## Response 503 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code for this error

  - `errorCode` (string, required)
    An April code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.

  - `message` (string, required)
    Human readable description of the error

  - `tracer` (string)
    An unique identifier for the request. Provide this to the support team if you wish to query a particular error.

  - `detail` (string)
    Optional additional details for the error.

  - `errorTypeDescription` (string)
    A description of the category of errors for the given statusCode.

  - `metadata` (any)
    Optional key value list of metadata