---
updatedAt: 2026-05-28T16:56:56.000Z
agentTools:
  siteIndex: https://developers.pismo.io/llms.txt
  projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---

# Create payment agreement simulation

Create a payment agreement simulation.

If successful, this endpoint generates a [Payment agreement simulation processed](https://developers.pismo.io/events/docs/balance-installment-payment-processed-1) event.
If it fails, it generates a [Payment agreement simulation not processed](https://developers.pismo.io/events/docs/statement-refinancing-payment-agreement-simulation-not-processed-1) event.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Revolving credit - Statement refinancing",
    "version": "1.0.0",
    "description": "Endpoints to handle statement refinancing",
    "termsOfService": "https://developers.pismo.io/terms/",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/statement-refinancing",
      "description": "Sandbox API server for testing and development"
    }
  ],
  "tags": [
    {
      "name": "Payment agreement simulation",
      "description": "Endpoints to manage payment agreement simulations"
    }
  ],
  "components": {
    "parameters": {
      "AccountIdPath": {
        "name": "accountId",
        "in": "path",
        "description": "Account ID",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int64",
          "example": 101
        }
      }
    },
    "schemas": {
      "DownPayment": {
        "type": "number",
        "format": "double",
        "description": "Down payment amount",
        "example": 500.99
      },
      "ErrorResponse": {
        "title": "ErrorResponse",
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "example": "Internal error",
            "description": "Error message"
          }
        },
        "description": "Standard error response"
      },
      "OrgID": {
        "type": "string",
        "description": "Organization ID",
        "example": "TN-e7091464-cd1e-4c20-8c68-1e4c5774d972"
      },
      "OverriddenAmountDue": {
        "type": "number",
        "format": "double",
        "description": "Overridden amount due. If provided, it overrides the total amount due for the account in the payment agreement simulation. Must be greater than zero and less than or equal to the current amount due.",
        "example": 2000
      },
      "PaymentAgreementSimulationCorrelationID": {
        "type": "string",
        "format": "uuid",
        "description": "Correlation ID for tracking the simulation request",
        "example": "1144f6a7-ed73-4fd2-ba45-80d3b881cad6"
      },
      "PaymentAgreementSimulationCreatedAt": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp when the payment agreement simulation was created. Format = YYYY-MM-DDThh:mm:ss.ssssssZ.",
        "example": "2025-06-17T15:22:51.978005295"
      },
      "PaymentAgreementSimulationRequest": {
        "type": "object",
        "properties": {
          "plan_ids": {
            "$ref": "#/components/schemas/SimulationPlanIDs"
          },
          "down_payment": {
            "$ref": "#/components/schemas/DownPayment"
          },
          "type": {
            "$ref": "#/components/schemas/PaymentAgreementType"
          },
          "payment_date": {
            "$ref": "#/components/schemas/SimulationPaymentDate"
          },
          "overridden_amount_due": {
            "$ref": "#/components/schemas/OverriddenAmountDue"
          }
        }
      },
      "PaymentAgreementSimulationResponse": {
        "type": "object",
        "properties": {
          "created_at": {
            "$ref": "#/components/schemas/PaymentAgreementSimulationCreatedAt"
          },
          "plan_ids": {
            "$ref": "#/components/schemas/SimulationPlanIDs"
          },
          "down_payment": {
            "$ref": "#/components/schemas/DownPayment"
          },
          "overridden_amount_due": {
            "$ref": "#/components/schemas/OverriddenAmountDue"
          },
          "payment_date": {
            "$ref": "#/components/schemas/SimulationPaymentDate"
          },
          "type": {
            "$ref": "#/components/schemas/PaymentAgreementType"
          },
          "status": {
            "$ref": "#/components/schemas/PaymentAgreementSimulationStatus"
          },
          "cid": {
            "$ref": "#/components/schemas/PaymentAgreementSimulationCorrelationID"
          },
          "org_id": {
            "$ref": "#/components/schemas/OrgID"
          }
        }
      },
      "PaymentAgreementSimulationStatus": {
        "type": "string",
        "description": "Status of payment agreement simulation",
        "enum": [
          "PENDING",
          "PROCESSED",
          "ERROR"
        ],
        "example": "PENDING"
      },
      "PaymentAgreementType": {
        "type": "string",
        "description": "Payment agreement type. Possible values:\n- `STATEMENT_INSTALLMENT`: Customer makes an agreement with their credit card issuer stating that they aren't able to pay off their debt within the current month, so they intend to settle the amount over the next few bills.\n- `STATEMENT_INSTALLMENT_COMPULSORY`: Issuer-imposed installment agreement renegotiated without customer input.\n- `STATEMENT_AGREEMENT`: Customer renegotiates all pending debt for all their statements.\n\nFor more information, refer to the [Create payment agreement](https://developers.pismo.io/pismo-docs/reference/installmentpaymentsv4) endpoint and the [Credit card refinancing](https://developers.pismo.io/pismo-docs/docs/negotiating-credit-card-debt) guide.\n",
        "enum": [
          "STATEMENT_INSTALLMENT",
          "STATEMENT_INSTALLMENT_COMPULSORY",
          "STATEMENT_AGREEMENT"
        ],
        "example": "STATEMENT_AGREEMENT"
      },
      "SimulationPaymentDate": {
        "type": "string",
        "format": "date",
        "description": "Date of first payment. Format = YYYY-MM-DD.",
        "example": "2025-06-20"
      },
      "SimulationPlanIDs": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "List of plan IDs used in the payment agreement simulation",
        "example": [
          "id1",
          "id2",
          "id3"
        ]
      },
      "StandardErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "1020030"
          },
          "message": {
            "type": "string",
            "example": "Error message"
          }
        }
      }
    },
    "responses": {
      "400BadRequest": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/StandardErrorResponse"
            },
            "examples": {
              "Missing request header": {
                "description": "Missing request header",
                "value": {
                  "code": "EX0002",
                  "message": "Missing request header for method parameter of type String"
                }
              }
            }
          }
        }
      },
      "423Locked": {
        "description": "Locked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "Account Locked": {
                "description": "The operation could not be completed because another process is manipulating the account. Try again in a moment.",
                "value": {
                  "message": "The operation could not be completed because another process is manipulating the account (the account lock could not be obtained). Try again in a moment."
                }
              }
            }
          }
        }
      },
      "500InternalServerError": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              ]
            },
            "examples": {
              "Internal Server Error": {
                "description": "Service is unavailable",
                "value": {
                  "code": "GN0001",
                  "message": "Service is unavailable"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Account JWT"
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/accounts/{accountId}/payment-agreement-simulations": {
      "post": {
        "tags": [
          "Payment agreement simulation"
        ],
        "summary": "Create payment agreement simulation",
        "description": "Create a payment agreement simulation.\n\nIf successful, this endpoint generates a [Payment agreement simulation processed](https://developers.pismo.io/events/docs/balance-installment-payment-processed-1) event.\nIf it fails, it generates a [Payment agreement simulation not processed](https://developers.pismo.io/events/docs/statement-refinancing-payment-agreement-simulation-not-processed-1) event.\n",
        "operationId": "create-payment-agreement-simulation",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentAgreementSimulationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK - Indicates that the simulation was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentAgreementSimulationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400BadRequest"
          },
          "423": {
            "$ref": "#/components/responses/423Locked"
          },
          "500": {
            "$ref": "#/components/responses/500InternalServerError"
          }
        }
      }
    }
  }
}
```