action plaid_payment_initiation_consent_create {
  label: "Create payment consent"
  description: "The `/payment_initiation/consent/create` endpoint is used to create a payment consent, which can be used to initiate payments on behalf of the user. Payment consents are created with `UNAUTHORISED` status by default and must be authorised by the user before payments can be initiated.\n\nConsents can be limited in time and scope, and have constraints that describe limitations for payments."
  provider: plaid
  method: POST
  path: "/payment_initiation/consent/create"
  encoding: json
  input: {
    type: "object"
    description: "PaymentInitiationConsentCreateRequest defines the request schema for `/payment_initiation/consent/create`"
    required: ["constraints", "recipient_id", "reference", "scopes"]
    properties: {
      client_id: {
        type: "string"
        description: "Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body."
      }
      constraints: {
        type: "object"
        description: "Limitations that will be applied to payments initiated using the payment consent."
        required: ["max_payment_amount", "periodic_amounts"]
        properties: {
          max_payment_amount: {
            description: "Maximum amount of a single payment initiated using the payment consent."
            type: "object"
          }
          periodic_amounts: {
            type: "array"
            description: "A list of amount limitations per period of time."
            items: {
              type: "object"
              description: "Defines consent payments limitations per period."
              required: ["amount", "interval", "alignment"]
              properties: {
                alignment: {
                  type: "string"
                  description: "Where the payment consent period should start.\n\n`CALENDAR`: line up with a calendar.\n\n`CONSENT`: on the date of consent creation."
                  enum: ["CALENDAR", "CONSENT"]
                }
                amount: {
                  description: "Maximum cumulative amount for all payments in the specified interval."
                  type: "object"
                }
                interval: {
                  type: "string"
                  description: "Payment consent periodic interval."
                  enum: ["DAY", "WEEK", "MONTH", "YEAR"]
                }
              }
            }
          }
          valid_date_time: {
            type: "object"
            description: "Life span for the payment consent. After the `to` date the payment consent expires and can no longer be used for payment initiation."
            properties: {
              from: {
                type: "string"
                format: "date-time"
                description: "The date and time from which the consent should be active, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format."
              }
              to: {
                type: "string"
                format: "date-time"
                description: "The date and time at which the consent expires, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format."
              }
            }
          }
        }
      }
      options: {
        type: "object"
        description: "Additional payment consent options"
        properties: {
          bacs: {
            description: "An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account."
            type: "object"
          }
          iban: {
            type: "string"
            description: "The International Bank Account Number (IBAN) for the payer's account. If provided, the end user will be able to set up payment consent using only the specified bank account."
          }
          request_refund_details: {
            type: "boolean"
            description: "When `true`, Plaid will attempt to request refund details from the payee's financial institution.  Support varies between financial institutions and will not always be available.  If refund details could be retrieved, they will be available in the `/payment_initiation/payment/get` response."
          }
        }
      }
      recipient_id: {
        type: "string"
        description: "The ID of the recipient the payment consent is for. The created consent can be used to transfer funds to this recipient only."
      }
      reference: {
        type: "string"
        description: "A reference for the payment consent. This must be an alphanumeric string with at most 18 characters and must not contain any special characters."
      }
      scopes: {
        type: "array"
        description: "An array of payment consent scopes."
        items: {
          type: "string"
          description: "Payment consent scope. Defines possible directions for payments made with the given consent.\n\n`ME_TO_ME`: Allows moving money between accounts owned by the same user.\n\n`EXTERNAL`: Allows initiating payments from the user's account to third parties."
          enum: ["ME_TO_ME", "EXTERNAL"]
        }
      }
      secret: {
        type: "string"
        description: "Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body."
      }
    }
  }
  output: {
    type: "object"
    description: "PaymentInitiationConsentCreateResponse defines the response schema for `/payment_initiation/consent/create`"
    required: ["consent_id", "request_id", "status"]
    properties: {
      consent_id: {
        type: "string"
        description: "A unique ID identifying the payment consent."
      }
      request_id: {
        type: "string"
        description: "A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive."
      }
      status: {
        type: "string"
        description: "The status of the payment consent.\n\n`UNAUTHORISED`: Consent created, but requires user authorisation.\n\n`REJECTED`: Consent authorisation was rejected by the user and/or the bank.\n\n`AUTHORISED`: Consent is active and ready to be used.\n\n`REVOKED`: Consent has been revoked and can no longer be used.\n\n`EXPIRED`: Consent is no longer valid."
        enum: ["UNAUTHORISED", "AUTHORISED", "REVOKED", "REJECTED", "EXPIRED"]
      }
    }
  }
}