Paystack
Paystack Accept Payments API

Initialize, verify, charge, and manage one-time card, bank, USSD, mobile money, QR, and bank transfer payments. The Transaction and Charge resources are the core of Paystack — a hosted checkout flow (initialize + verify) and a direct charge flow that drives the customer through PIN, OTP, phone, birthday, and address challenges as required.
Paystack Accept Payments 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 and 2 JSON Schema definitions.
Tagged areas include Payments, Transactions, and Charge. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, sample payloads, 1 Naftiko capability spec, and 2 JSON Schemas.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.1
info:
  title: Paystack Accept Payments API
  description: Initialize, verify, charge, and manage one-time card, bank, USSD, mobile money, and QR payments. The core API
    for accepting payments through Paystack across Africa.
  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: Transaction
- name: Charge
paths:
  /transaction/initialize:
    post:
      tags:
      - Transaction
      summary: Initialize Transaction
      operationId: transaction_initialize
      description: Create a new transaction
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transaction~1initialize/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - email
              - amount
              properties:
                email:
                  description: Customer's email address
                  type: string
                amount:
                  description: Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency
                    is ZAR
                  type: integer
                currency:
                  description: The transaction currency
                  type: string
                  enum:
                  - NGN
                  - GHS
                  - ZAR
                  - USD
                reference:
                  description: Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
                  type: string
                callback_url:
                  description: Fully qualified url, e.g. https://example.com/ . Use this to override the callback url provided
                    on the dashboard for this transaction
                  type: string
                plan:
                  description: "If transaction is to create a subscription to a predefined plan, provide plan code here. \n\
                    This would invalidate the value provided in amount"
                  type: string
                invoice_limit:
                  description: Number of times to charge customer during subscription to plan
                  type: integer
                metadata:
                  description: Stringified JSON object of custom data
                  type: string
                channels:
                  description: An array of payment channels to control what channels you want to make available to the user
                    to make a payment with
                  type: array
                  items:
                    type: string
                    enum:
                    - card
                    - bank
                    - ussd
                    - qr
                    - eft
                    - mobile_money
                    - bank_transfer
                split_code:
                  description: The split code of the transaction split
                  type: string
                subaccount:
                  description: The code for the subaccount that owns the payment
                  type: string
                transaction_charge:
                  description: "A flat fee to charge the subaccount for a transaction. \nThis overrides the split percentage\
                    \ set when the subaccount was created"
                  type: string
                bearer:
                  description: The beare of the transaction charge
                  type: string
                  enum:
                  - account
                  - subaccount
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /transaction/verify/{reference}:
    get:
      tags:
      - Transaction
      summary: Verify Transaction
      operationId: transaction_verify
      parameters:
      - name: reference
        in: path
        description: The transaction reference to verify
        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
  /transaction:
    get:
      tags:
      - Transaction
      summary: List Transactions
      operationId: transaction_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
  /transaction/{id}:
    get:
      tags:
      - Transaction
      summary: Fetch Transaction
      operationId: transaction_fetch
      parameters:
      - name: id
        in: path
        description: The ID of the transaction to fetch
        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
  /transaction/timeline/{id_or_reference}:
    get:
      tags:
      - Transaction
      summary: Fetch Transaction Timeline
      operationId: transaction_timeline
      parameters:
      - name: id_or_reference
        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
  /transaction/totals:
    get:
      tags:
      - Transaction
      summary: Transaction Totals
      operationId: transaction_totals
      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
  /transaction/export:
    get:
      tags:
      - Transaction
      summary: Export Transactions
      operationId: transaction_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: 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
  /transaction/charge_authorization:
    post:
      tags:
      - Transaction
      summary: Charge Authorization
      operationId: transaction_chargeAuthorization
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transaction~1charge_authorization/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - email
              - amount
              - authorization_code
              properties:
                email:
                  description: Customer's email address
                  type: string
                amount:
                  description: Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency
                    is ZAR
                  type: integer
                authorization_code:
                  description: Valid authorization code to charge
                  type: string
                reference:
                  description: Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
                  type: string
                currency:
                  description: The transaction currency
                  type: string
                  enum:
                  - NGN
                  - GHS
                  - ZAR
                  - USD
                metadata:
                  description: Stringified JSON object of custom data
                  type: string
                split_code:
                  description: The split code of the transaction split
                  type: string
                subaccount:
                  description: The code for the subaccount that owns the payment
                  type: string
                transaction_charge:
                  description: "A flat fee to charge the subaccount for a transaction. \nThis overrides the split percentage\
                    \ set when the subaccount was created"
                  type: string
                bearer:
                  description: The beare of the transaction charge
                  type: string
                  enum:
                  - account
                  - subaccount
                queue:
                  description: If you are making a scheduled charge call, it is a good idea to queue them so the processing
                    system does not get overloaded causing transaction processing errors.
                  type: boolean
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /transaction/check_authorization:
    post:
      tags:
      - Transaction
      summary: Check Authorization
      operationId: transaction_checkAuthorization
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transaction~1check_authorization/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - email
              - amount
              properties:
                email:
                  description: Customer's email address
                  type: string
                amount:
                  description: Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency
                    is ZAR
                  type: integer
                authorization_code:
                  description: Valid authorization code to charge
                  type: string
                currency:
                  description: The transaction currency
                  type: string
                  enum:
                  - NGN
                  - GHS
                  - ZAR
                  - USD
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /transaction/partial_debit:
    post:
      tags:
      - Transaction
      summary: Partial Debit
      operationId: transaction_partialDebit
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1transaction~1partial_debit/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - email
              - amount
              - authorization_code
              - currency
              properties:
                email:
                  description: Customer's email address
                  type: string
                amount:
                  description: Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency
                    is ZAR
                  type: integer
                authorization_code:
                  description: Valid authorization code to charge
                  type: string
                currency:
                  description: The transaction currency
                  type: string
                  enum:
                  - NGN
                  - GHS
                  - ZAR
                  - USD
                reference:
                  description: Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
                  type: string
                at_least:
                  description: Minimum amount to charge
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /transaction/{id}/event:
    get:
      tags:
      - Transaction
      summary: Get Transaction Event
      operationId: transaction_event
      parameters:
      - name: id
        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
  /transaction/{id}/session:
    get:
      tags:
      - Transaction
      summary: Get Transaction Session
      operationId: transaction_session
      parameters:
      - name: id
        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
  /charge:
    post:
      tags:
      - Charge
      summary: Create Charge
      operationId: charge_create
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1charge/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              allOf:
              - type: object
                required:
                - email
                - amount
                properties:
                  email:
                    description: Customer's email address
                    type: string
                  amount:
                    description: Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency
                      is ZAR
                    type: string
                  authorization_code:
                    description: An authorization code to charge.
                    type: string
                  pin:
                    description: 4-digit PIN (send with a non-reusable authorization code)
                    type: string
                  reference:
                    description: Unique transaction reference. Only -, .`, = and alphanumeric characters allowed.
                    type: string
                  birthday:
                    description: The customer's birthday in the format YYYY-MM-DD e.g 2017-05-16
                    type: string
                    format: date-time
                  device_id:
                    description: "This is the unique identifier of the device a user uses in making payment. \nOnly -, .`,\
                      \ = and alphanumeric characters are allowed."
                    type: string
                  metadata:
                    description: Stringified JSON object of custom data
                    type: string
              - type: object
                properties:
                  bank:
                    type: object
                    properties:
                      code:
                        description: Customer's bank code
                        type: string
                      account_number:
                        description: Customer's account number
                        type: string
              - type: object
                properties:
                  mobile_money:
                    type: object
                    properties:
                      phone:
                        description: Customer's phone number
                        type: string
                      provider:
                        description: "The telco provider of customer's phone number. \nThis can be fetched from the List Bank\
                          \ endpoint\n"
                        type: string
              - type: object
                properties:
                  ussd:
                    type: object
                    properties:
                      type:
                        description: The three-digit USSD code
                        type: string
                        enum:
                        - 737
                        - 919
                        - 822
                        - 966
              - type: object
                properties:
                  eft:
                    type: object
                    properties:
                      provider:
                        description: The EFT provider
                        type: string
                        enum:
                        - ozow
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /charge/submit_pin:
    post:
      tags:
      - Charge
      summary: Submit PIN
      operationId: charge_submitPin
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1charge~1submit_pin/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - pin
              - reference
              properties:
                pin:
                  description: Customer's PIN
                  type: string
                reference:
                  description: Transaction reference that requires the PIN
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /charge/submit_otp:
    post:
      tags:
      - Charge
      summary: Submit OTP
      operationId: charge_submitOtp
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1charge~1submit_otp/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - otp
              - reference
              properties:
                otp:
                  description: Customer's OTP
                  type: string
                reference:
                  description: The reference of the ongoing transaction
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /charge/submit_phone:
    post:
      tags:
      - Charge
      summary: Submit Phone
      operationId: charge_submitPhone
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1charge~1submit_phone/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - phone
              - reference
              properties:
                phone:
                  description: Customer's mobile number
                  type: string
                reference:
                  description: The reference of the ongoing transaction
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /charge/submit_birthday:
    post:
      tags:
      - Charge
      summary: Submit Birthday
      operationId: charge_submitBirthday
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1charge~1submit_birthday/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - birthday
              - reference
              properties:
                birthday:
                  description: Customer's birthday in the format YYYY-MM-DD e.g 2016-09-21
                  type: string
                reference:
                  description: The reference of the ongoing transaction
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /charge/submit_address:
    post:
      tags:
      - Charge
      summary: Submit Address
      operationId: charge_submitAddress
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/paths/~1charge~1submit_address/post/requestBody/content/application~1json/schema'
          application/json:
            schema:
              type: object
              required:
              - address
              - reference
              - city
              - state
              - zipcode
              properties:
                address:
                  description: Customer's address
                  type: string
                city:
                  description: Customer's city
                  type: string
                state:
                  description: Customer's state
                  type: string
                zipcode:
                  description: Customer's zipcode
                  type: string
                reference:
                  description: The reference of the ongoing transaction
                  type: string
      responses:
        '201':
          $ref: '#/paths/~1plan/get/responses/200'
        '401':
          $ref: '#/paths/~1plan/get/responses/401'
        default:
          description: Server error
  /charge/{reference}:
    get:
      tags:
      - Charge
      summary: Check Pending Charge
      operationId: charge_check
      parameters:
      - name: reference
        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: []
Paystack Accept Payments API

Documentation

Specifications

Examples

Schemas & Data

Other Resources

OpenAPI Specification
