> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Create mandate

> Creates a mandate that sets the terms for charging the card of an `ACTIVE` enrollment at one merchant. The response is `REQUIRES_ACTION` with a redirect to a Reap-hosted page where the user reviews and approves the terms. After approval the user returns to `presentation.returnUrl` and the mandate becomes `ACTIVE`. Mandates work only for merchants that Reap has approved for your integration.

Required scope: [AGENTIC\_WRITE](https://docs.reap.global/api-reference/scopes.md)


## OpenAPI

````yaml /api-reference/openapi.json post /agentic/mandates
openapi: 3.1.0
info:
  title: Reap API
  version: 1.0.0
  description: Reap platform API
servers:
  - url: https://sg.sandbox.api.reap.global
    description: Singapore sandbox
  - url: https://sg.prod.api.reap.global
    description: Singapore production
  - url: https://mx.sandbox.api.reap.global
    description: Mexico sandbox
  - url: https://mx.prod.api.reap.global
    description: Mexico production
  - url: https://sandbox.api.reap.global
    description: Singapore sandbox (alias)
  - url: https://prod.api.reap.global
    description: Singapore production (alias)
security:
  - bearerAuth: []
tags:
  - name: Accounts
  - name: Activities
  - name: Card Designs
  - name: Card Shipments
  - name: Card Transactions
  - name: Cards
  - name: Companies
  - name: Crypto Deposits
  - name: Crypto Withdrawals
  - name: Disputes
  - name: Fees
  - name: Fiat Deposits
  - name: Fraud Alerts
  - name: Policies
  - name: Simulation
  - name: Statements
  - name: Users
  - name: Virtual Asset Postings
  - name: Virtual Assets
  - name: Webhooks
  - name: Agentic
paths:
  /agentic/mandates:
    post:
      tags:
        - Agentic
      summary: Create mandate
      description: >-
        Creates a mandate that sets the terms for charging the card of an
        `ACTIVE` enrollment at one merchant. The response is `REQUIRES_ACTION`
        with a redirect to a Reap-hosted page where the user reviews and
        approves the terms. After approval the user returns to
        `presentation.returnUrl` and the mandate becomes `ACTIVE`. Mandates work
        only for merchants that Reap has approved for your integration.
      operationId: createMandate_agentic
      parameters:
        - name: Reap-Version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2025-02-14'
            description: API version (YYYY-MM-DD)
            example: '2025-02-14'
        - name: Reap-Subproject-Id
          in: header
          required: false
          schema:
            description: >-
              Selects the subproject the request operates on; only accepted with
              a parent project credential.
            type: string
            format: uuid
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
            description: >-
              Unique key for safely retrying this request. Up to 255 characters;
              we recommend a UUIDv4. The first request executes and its response
              is cached; subsequent requests with the same key replay the cached
              response (24h retention).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enrollmentId:
                  type: string
                  format: uuid
                merchantUrl:
                  type: string
                  pattern: ^[Hh][Tt][Tt][Pp][Ss]?:\/\/
                frequency:
                  type: string
                  enum:
                    - ONE_TIME
                    - WEEKLY
                    - MONTHLY
                    - YEARLY
                  example: ONE_TIME
                amount:
                  type: object
                  properties:
                    amount:
                      type: string
                      pattern: ^\d+(\.\d+)?$
                    currency:
                      type: string
                      minLength: 3
                      maxLength: 3
                  required:
                    - amount
                    - currency
                validUntil:
                  type: string
                  format: date-time
                presentation:
                  type: object
                  properties:
                    type:
                      type: string
                      const: REDIRECT
                    returnUrl:
                      type: string
                      format: uri
                      description: HTTPS URL the browser returns to after the hosted flow
                  required:
                    - type
                    - returnUrl
                  description: Redirect config for the hosted mandate approval
              required:
                - enrollmentId
                - merchantUrl
                - frequency
                - amount
                - presentation
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                enrollmentId:
                  type: string
                  format: uuid
                merchantUrl:
                  type: string
                  pattern: ^[Hh][Tt][Tt][Pp][Ss]?:\/\/
                frequency:
                  type: string
                  enum:
                    - ONE_TIME
                    - WEEKLY
                    - MONTHLY
                    - YEARLY
                  example: ONE_TIME
                amount:
                  type: object
                  properties:
                    amount:
                      type: string
                      pattern: ^\d+(\.\d+)?$
                    currency:
                      type: string
                      minLength: 3
                      maxLength: 3
                  required:
                    - amount
                    - currency
                validUntil:
                  type: string
                  format: date-time
                presentation:
                  type: object
                  properties:
                    type:
                      type: string
                      const: REDIRECT
                    returnUrl:
                      type: string
                      format: uri
                      description: HTTPS URL the browser returns to after the hosted flow
                  required:
                    - type
                    - returnUrl
                  description: Redirect config for the hosted mandate approval
              required:
                - enrollmentId
                - merchantUrl
                - frequency
                - amount
                - presentation
          multipart/form-data:
            schema:
              type: object
              properties:
                enrollmentId:
                  type: string
                  format: uuid
                merchantUrl:
                  type: string
                  pattern: ^[Hh][Tt][Tt][Pp][Ss]?:\/\/
                frequency:
                  type: string
                  enum:
                    - ONE_TIME
                    - WEEKLY
                    - MONTHLY
                    - YEARLY
                  example: ONE_TIME
                amount:
                  type: object
                  properties:
                    amount:
                      type: string
                      pattern: ^\d+(\.\d+)?$
                    currency:
                      type: string
                      minLength: 3
                      maxLength: 3
                  required:
                    - amount
                    - currency
                validUntil:
                  type: string
                  format: date-time
                presentation:
                  type: object
                  properties:
                    type:
                      type: string
                      const: REDIRECT
                    returnUrl:
                      type: string
                      format: uri
                      description: HTTPS URL the browser returns to after the hosted flow
                  required:
                    - type
                    - returnUrl
                  description: Redirect config for the hosted mandate approval
              required:
                - enrollmentId
                - merchantUrl
                - frequency
                - amount
                - presentation
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                      - REQUIRES_ACTION
                      - ACTIVE
                      - PAUSED
                      - CONSUMED
                      - EXPIRED
                      - FAILED
                      - CANCELLED
                      - REVOKED
                    example: REQUIRES_ACTION
                  enrollmentId:
                    type: string
                    format: uuid
                  owner:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - REAP_USER
                          - CLIENT_REFERENCE
                        example: REAP_USER
                      id:
                        type: string
                        minLength: 1
                    required:
                      - type
                      - id
                  frequency:
                    type: string
                    enum:
                      - ONE_TIME
                      - WEEKLY
                      - MONTHLY
                      - YEARLY
                    example: ONE_TIME
                  amount:
                    type: object
                    properties:
                      amount:
                        type: number
                      currency:
                        type: string
                        minLength: 3
                        maxLength: 3
                    required:
                      - amount
                      - currency
                  merchant:
                    type: object
                    properties:
                      url:
                        type: string
                      name:
                        type: string
                      domain:
                        type: string
                      country:
                        type: string
                        minLength: 2
                        maxLength: 2
                    required:
                      - url
                      - name
                      - domain
                      - country
                  validUntil:
                    anyOf:
                      - type: string
                        format: date-time
                      - type: 'null'
                  usage:
                    type: object
                    properties:
                      spent:
                        type: number
                      pending:
                        type: number
                      remaining:
                        type:
                          - number
                          - 'null'
                      cycle:
                        anyOf:
                          - type: object
                            properties:
                              renewsAt:
                                type: string
                                format: date-time
                            required:
                              - renewsAt
                          - type: 'null'
                      unresolvedCheckoutId:
                        anyOf:
                          - type: string
                            format: uuid
                          - type: 'null'
                    required:
                      - spent
                      - pending
                      - remaining
                      - cycle
                      - unresolvedCheckoutId
                  nextAction:
                    anyOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - REDIRECT
                            example: REDIRECT
                          url:
                            type: string
                            format: uri
                          expiresAt:
                            type: string
                            format: date-time
                        required:
                          - type
                          - url
                        title: Redirect
                      - type: 'null'
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
                required:
                  - id
                  - status
                  - enrollmentId
                  - owner
                  - frequency
                  - amount
                  - merchant
                  - validUntil
                  - usage
                  - nextAction
                  - createdAt
                  - updatedAt
        '400':
          description: Response for status 400
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: AGENTIC_REQUEST_REJECTED
                          message:
                            type: string
                          detail:
                            type: 'null'
                        required:
                          - code
                          - message
                          - detail
                    required:
                      - error
                    title: AgenticRequestRejectedError
                    description: The request was rejected
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: MERCHANT_URL_INVALID
                          message:
                            type: string
                          detail:
                            type: 'null'
                        required:
                          - code
                          - message
                          - detail
                    required:
                      - error
                    title: MerchantUrlInvalidError
                    description: The merchant URL is not a valid merchant site.
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: MERCHANT_NOT_SUPPORTED
                          message:
                            type: string
                          detail:
                            type: 'null'
                        required:
                          - code
                          - message
                          - detail
                    required:
                      - error
                    title: MerchantNotSupportedError
                    description: Mandates are not available for this merchant.
        '404':
          description: Response for status 404
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: AGENTIC_RESOURCE_NOT_FOUND
                          message:
                            type: string
                          detail:
                            anyOf:
                              - type: object
                                additionalProperties: {}
                              - type: 'null'
                        required:
                          - code
                          - message
                          - detail
                    required:
                      - error
                    title: AgenticResourceNotFoundError
                    description: Resource not found
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: ENROLLMENT_NOT_FOUND
                          message:
                            type: string
                          detail:
                            type: 'null'
                        required:
                          - code
                          - message
                          - detail
                    required:
                      - error
                    title: EnrollmentNotFoundError
                    description: Enrollment not found.
        '409':
          description: Enrollment is not active.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: ENROLLMENT_NOT_ACTIVE
                      message:
                        type: string
                      detail:
                        anyOf:
                          - type: object
                            properties:
                              reason:
                                type: string
                                const: CARD_NOT_CAPTURED
                            required:
                              - reason
                            additionalProperties: false
                          - type: 'null'
                    required:
                      - code
                      - message
                      - detail
                required:
                  - error
                title: EnrollmentNotActiveError
        '503':
          description: Agentic Payments is temporarily unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: AGENTIC_SERVICE_UNAVAILABLE
                      message:
                        type: string
                      detail:
                        anyOf:
                          - type: object
                            additionalProperties: {}
                          - type: 'null'
                    required:
                      - code
                      - message
                      - detail
                required:
                  - error
                title: AgenticServiceUnavailableError
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key as Bearer token

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.