openapi: 3.0.1
info:
  title: Paystack Transfers API
  description: Send money from your Paystack balance to bank accounts and mobile money wallets across supported African countries.
    Includes transfer recipients, single and bulk transfers, OTP management, and bulk charges.
  version: 1.0.0
  contact:
    name: Paystack Support
    url: https://support.paystack.com
    email: support@paystack.com
  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: Transfer
- name: Transfer Recipient
- name: Bulk Charge
paths:
  /transferrecipient:
    post:
      tags:
      - Transfer Recipient
      summary: Create Transfer Recipient
      operationId: transferrecipient_create
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transferrecipient/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - type
              - name
              - account_number
              - bank_code
              properties:
                type:
                  description: Recipient Type (Only nuban at this time)
                  type: string
                name:
                  description: Recipient's name
                  type: string
                account_number:
                  description: Recipient's bank account number
                  type: string
                bank_code:
                  description: Recipient's bank code. You can get the list of Bank Codes by calling the List Banks endpoint
                  type: string
                description:
                  description: A description for this recipient
                  type: string
                currency:
                  description: Currency for the account receiving the transfer
                  type: string
                authorization_code:
                  description: An authorization code from a previous transaction
                  type: string
                metadata:
                  description: Stringified JSON object of custom data
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
    get:
      tags:
      - Transfer Recipient
      summary: List Transfer Recipients
      operationId: transferrecipient_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: 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
  /transferrecipient/bulk:
    post:
      tags:
      - Transfer Recipient
      summary: Bulk Create Transfer Recipient
      operationId: transferrecipient_bulk
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transferrecipient~1bulk/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - batch
              properties:
                batch:
                  description: "A list of transfer recipient object. Each object should contain type, name, and bank_code.\
                    \ \nAny Create Transfer Recipient param can also be passed."
                  type: array
                  items:
                    $ref: '#/paths/~1transferrecipient/post/requestBody/content/application~1json/schema'
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /transferrecipient/{code}:
    get:
      tags:
      - Transfer Recipient
      summary: Fetch Transfer Recipient
      operationId: transferrecipient_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:
      - Transfer Recipient
      summary: Update Transfer Recipient
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transferrecipient~1%7Bcode%7D/put/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - batch
              properties:
                name:
                  description: Recipient's name
                  type: string
                email:
                  description: Recipient's email address
                  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
    delete:
      tags:
      - Transfer Recipient
      summary: Delete Transfer Recipient
      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: code
      description: Transfer recipient code
      in: path
      required: true
      schema:
        type: string
  /transfer:
    post:
      tags:
      - Transfer
      summary: Initiate Transfer
      operationId: transfer_initiate
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transfer/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - source
              - amount
              - recipient
              properties:
                source:
                  description: Where should we transfer from? Only balance is allowed for now
                  type: string
                amount:
                  description: Amount to transfer in kobo if currency is NGN and pesewas if currency is GHS.
                  type: string
                recipient:
                  description: The transfer recipient's code
                  type: string
                reason:
                  description: The reason or narration for the transfer.
                  type: string
                currency:
                  description: Specify the currency of the transfer. Defaults to NGN.
                  type: string
                reference:
                  description: "If specified, the field should be a unique identifier (in lowercase) for the object. \nOnly\
                    \ -,_ and alphanumeric characters are allowed."
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
    get:
      tags:
      - Transfer
      summary: List Transfers
      operationId: transfer_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: status
        schema:
          type: string
      - 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
  /transfer/finalize_transfer:
    post:
      tags:
      - Transfer
      summary: Finalize Transfer
      operationId: transfer_finalize
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transfer~1finalize_transfer/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - transfer_code
              - otp
              properties:
                transfer_code:
                  description: The transfer code you want to finalize
                  type: string
                otp:
                  description: OTP sent to business phone to verify transfer
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /transfer/bulk:
    post:
      tags:
      - Transfer
      summary: Initiate Bulk Transfer
      operationId: transfer_bulk
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transfer~1bulk/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - batch
              properties:
                source:
                  description: Where should we transfer from? Only balance is allowed for now
                  type: string
                transfers:
                  description: A list of transfer object. Each object should contain amount, recipient, and reference
                  type: array
                  items:
                    $ref: '#/paths/~1transfer/post/requestBody/content/application~1json/schema'
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /transfer/{code}:
    get:
      tags:
      - Transfer
      summary: Fetch Transfer
      operationId: transfer_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
    parameters:
    - name: code
      description: Transfer code
      in: path
      required: true
      schema:
        type: string
  /transfer/verify/{reference}:
    get:
      tags:
      - Transfer
      summary: Verify Transfer
      operationId: transfer_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: reference
      in: path
      required: true
      schema:
        type: string
  /transfer/export:
    get:
      tags:
      - Transfer
      summary: Export Transfers
      operationId: transfer_download
      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: status
        schema:
          type: string
      - 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
  /transfer/resend_otp:
    post:
      tags:
      - Transfer
      summary: Resend OTP for Transfer
      operationId: transfer_resendOtp
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transfer~1resend_otp/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - transfer_code
              - reason
              properties:
                transfer_code:
                  description: The transfer code that requires an OTP validation
                  type: string
                reason:
                  description: Either resend_otp or transfer
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /transfer/disable_otp:
    post:
      tags:
      - Transfer
      summary: Disable OTP Requirement for Transfers
      operationId: transfer_disableOtp
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /transfer/disable_otp_finalize:
    post:
      tags:
      - Transfer
      summary: Finalize Disabling of OTP Requirement for Transfers
      operationId: transfer_disableOtpFinalize
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transfer~1disable_otp_finalize/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - otp
              properties:
                otp:
                  description: OTP sent to business phone to verify disabling OTP requirement
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /transfer/enable_otp:
    post:
      tags:
      - Transfer
      summary: Enable OTP Requirement for Transfers
      operationId: transfer_enableOtp
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /bulkcharge:
    post:
      tags:
      - Bulk Charge
      summary: Initiate Bulk Charge
      operationId: bulkCharge_initiate
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: array
              items:
                type: object
                required:
                - authorization
                - amount
                properties:
                  authorization:
                    description: Customer's card authorization code
                    type: string
                  amount:
                    description: Amount to charge on the authorization
                    type: string
                  reference:
                    description: Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
                    type: string
          application/json:
            schema:
              type: array
              items:
                properties:
                  charges:
                    title: charges
                    type: object
                    items:
                      $ref: '#/paths/~1bulkcharge/post/requestBody/content/application~1x-www-form-urlencoded/schema/items'
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
    get:
      tags:
      - Bulk Charge
      summary: List Bulk Charge Batches
      operationId: bulkCharge_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: 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
  /bulkcharge/{code}:
    get:
      tags:
      - Bulk Charge
      summary: Fetch Bulk Charge Batch
      operationId: bulkCharge_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
    parameters:
    - name: code
      description: Batch code
      in: path
      required: true
      schema:
        type: string
  /bulkcharge/{code}/charges:
    get:
      tags:
      - Bulk Charge
      summary: Fetch Charges in a Batch
      operationId: bulkCharge_charges
      parameters:
      - name: code
        description: Batch code
        in: path
        required: true
        schema:
          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
  /bulkcharge/pause/{code}:
    get:
      tags:
      - Bulk Charge
      summary: Pause Bulk Charge Batch
      operationId: bulkCharge_pause
      parameters:
      - name: code
        description: Batch code
        in: path
        required: true
        schema:
          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
  /bulkcharge/resume/{code}:
    get:
      tags:
      - Bulk Charge
      summary: Resume Bulk Charge Batch
      operationId: bulkCharge_resume
      parameters:
      - name: code
        description: Batch code
        in: path
        required: true
        schema:
          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
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: []