Paystack
Paystack Payment Requests API

Issue invoice-style payment requests to customers by email, with verification, notification, finalization, and archival flows.
Paystack Payment Requests API is one of 13 APIs that Paystack publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.
Tagged areas include Invoices and Payment Requests. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.1
info:
  title: Paystack Payment Requests API
  description: Create and send invoice-like payment requests to customers via email with verification, notifications, finalize,
    and archive flows.
  version: 1.0.0
  contact:
    name: Paystack Support
    url: https://support.paystack.com
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.paystack.co
  description: Base API endpoint
tags:
- name: Payment Request
paths:
  /paymentrequest:
    post:
      tags:
      - Payment Request
      summary: Create Payment Request
      operationId: paymentRequest_create
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1paymentrequest/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - customer
              properties:
                customer:
                  description: Customer id or code
                  type: string
                amount:
                  description: "Payment request amount. Only useful if line items and tax values are ignored. \nThe endpoint\
                    \ will throw a friendly warning if neither is available."
                  type: integer
                currency:
                  description: Specify the currency of the invoice. Allowed values are NGN, GHS, ZAR and USD. Defaults to
                    NGN
                  type: string
                due_date:
                  description: ISO 8601 representation of request due date
                  type: string
                  format: date-time
                description:
                  description: A short description of the payment request
                  type: string
                line_items:
                  description: Array of line items
                  type: array
                  items:
                    type: object
                tax:
                  description: Array of taxes
                  type: array
                  items:
                    type: object
                send_notification:
                  description: Indicates whether Paystack sends an email notification to customer. Defaults to true
                  type: boolean
                  items:
                    type: object
                draft:
                  description: Indicate if request should be saved as draft. Defaults to false and overrides send_notification
                  type: boolean
                  items:
                    type: object
                has_invoice:
                  description: "Set to true to create a draft invoice (adds an auto incrementing invoice number if none is\
                    \ provided) \neven if there are no line_items or tax passed"
                  type: boolean
                  items:
                    type: object
                invoice_number:
                  description: "Numeric value of invoice. Invoice will start from 1 and auto increment from there. This field\
                    \ is to help \noverride whatever value Paystack decides. Auto increment for subsequent invoices continue\
                    \ from this point."
                  type: integer
                split_code:
                  description: The split code of the transaction split.
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
    get:
      tags:
      - Payment Request
      summary: List Payment Request
      operationId: paymentRequest_list
      parameters:
      - in: query
        name: perPage
        schema:
          type: integer
        description: Number of records to fetch per page
      - in: query
        name: page
        schema:
          type: integer
        description: The section to retrieve
      - in: query
        name: customer
        schema:
          type: string
        description: Customer ID
      - in: query
        name: status
        schema:
          type: string
        description: Invoice status to filter
      - in: query
        name: currency
        schema:
          type: string
        description: If your integration supports more than one currency, choose the one to filter
      - in: query
        name: from
        schema:
          type: string
          format: date-time
        description: The start date
      - in: query
        name: to
        schema:
          type: string
          format: date-time
        description: The end date
      responses:
        '200':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        '404':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /paymentrequest/{id}:
    get:
      tags:
      - Payment Request
      summary: Fetch Payment Request
      operationId: paymentRequest_fetch
      responses:
        '200':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        '404':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
    put:
      tags:
      - Payment Request
      summary: Update Payment Request
      operationId: paymentRequest_update
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1paymentrequest~1%7Bid%7D/put/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              properties:
                customer:
                  description: Customer id or code
                  type: string
                amount:
                  description: "Payment request amount. Only useful if line items and tax values are ignored. \nThe endpoint\
                    \ will throw a friendly warning if neither is available."
                  type: integer
                currency:
                  description: Specify the currency of the invoice. Allowed values are NGN, GHS, ZAR and USD. Defaults to
                    NGN
                  type: string
                due_date:
                  description: ISO 8601 representation of request due date
                  type: string
                  format: date-time
                description:
                  description: A short description of the payment request
                  type: string
                line_items:
                  description: Array of line items
                  type: array
                  items:
                    type: object
                tax:
                  description: Array of taxes
                  type: array
                  items:
                    type: object
                send_notification:
                  description: Indicates whether Paystack sends an email notification to customer. Defaults to true
                  type: boolean
                  items:
                    type: object
                draft:
                  description: Indicate if request should be saved as draft. Defaults to false and overrides send_notification
                  type: boolean
                  items:
                    type: object
                has_invoice:
                  description: "Set to true to create a draft invoice (adds an auto incrementing invoice number if none is\
                    \ provided) \neven if there are no line_items or tax passed"
                  type: boolean
                  items:
                    type: object
                invoice_number:
                  description: "Numeric value of invoice. Invoice will start from 1 and auto increment from there. This field\
                    \ is to help \noverride whatever value Paystack decides. Auto increment for subsequent invoices continue\
                    \ from this point."
                  type: integer
                split_code:
                  description: The split code of the transaction split.
                  type: string
      responses:
        '200':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        '404':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
  /paymentrequest/verify/{id}:
    get:
      tags:
      - Payment Request
      summary: Verify Payment Request
      operationId: paymentRequest_verify
      responses:
        '200':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        '404':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
  /paymentrequest/notify/{id}:
    post:
      tags:
      - Payment Request
      summary: Send Notification
      operationId: paymentRequest_notify
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
  /paymentrequest/totals:
    get:
      tags:
      - Payment Request
      summary: Payment Request Total
      operationId: paymentRequest_totals
      responses:
        '200':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        '404':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /paymentrequest/finalize/{id}:
    post:
      tags:
      - Payment Request
      summary: Finalize Payment Request
      operationId: paymentRequest_finalize
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
  /paymentrequest/archive/{id}:
    post:
      tags:
      - Payment Request
      summary: Archive Payment Request
      operationId: paymentRequest_archive
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Customer:
      allOf:
      - type: object
        required:
        - email
        properties:
          email:
            description: Customer's email address
            type: string
      - type: object
        properties:
          first_name:
            description: Customer's first name
            type: string
          last_name:
            description: Customer's last name
            type: string
          phone:
            description: Customer's phone number
            type: string
          metadata:
            description: Stringified JSON object of custom data
            type: string
      - type: object
        required:
        - authorization_code
        properties:
          authorization_code:
            description: Customer's authorization code to be deactivated
            type: string
      - type: object
        required:
        - customer
        properties:
          customer:
            description: Customer's code, or email address
            type: string
          risk_action:
            description: "One of the possible risk actions [ default, allow, deny ]. allow to whitelist. \ndeny to blacklist.\
              \ Customers start with a default risk action.\n"
            type: string
            enum:
            - default
            - allow
            - deny
      - type: object
        required:
        - type
        - country
        - bvn
        - bank_code
        - account_number
        properties:
          type:
            description: Predefined types of identification.
            type: string
            enum:
            - bvn
            - bank_account
          country:
            description: Two-letter country code of identification issuer
            type: string
          bvn:
            description: Customer's Bank Verification Number
            type: string
          bank_code:
            description: You can get the list of bank codes by calling the List Banks endpoint (https://api.paystack.co/bank).
            type: string
          account_number:
            description: Customer's bank account number.
            type: string
          value:
            description: Customer's identification number. Required if type is bvn
            type: string
    Error:
      type: object
      properties:
        status:
          type: boolean
        message:
          type: string
    Response:
      type: object
      properties:
        status:
          type: boolean
        message:
          type: string
        data:
          type: object
security:
- bearerAuth: []
Paystack Payment Requests API

Documentation

Specifications

Other Resources

OpenAPI Specification
