openapi: 3.0.3
info:
  title: OPay Cashier Payments API
  version: '1.0'
  description: 'The OPay Cashier API is the merchant payment API behind OPay Checkout. It

    exposes a hosted Express Checkout endpoint plus server-to-server endpoints

    for 3DS bank card, bank transfer, bank USSD, bank account, POS, OPay

    wallet QR, and reference-code payments, with status query, cancel,

    refund, and refund-status operations.


    Authentication uses an `Authorization: Bearer <token>` header plus a

    `MerchantId` header. For `cashier/create` the bearer token is the

    merchant''s public key. For all other endpoints the bearer token is an

    HMAC-SHA512 signature computed over the JSON request body using the

    merchant''s private key.

    '
  contact:
    name: OPay Merchant Support
    url: https://support.opaycheckout.com/support/ticket
  license:
    name: OPay Merchant Terms
    url: https://www.opayweb.com/terms-and-conditions
servers:
- url: https://liveapi.opaycheckout.com/api/v1/international
  description: Production
- url: https://testapi.opaycheckout.com/api/v1/international
  description: Sandbox
tags:
- name: Payments
  description: Server-to-server payment creation across payment methods.
paths:
  /payment/create:
    post:
      tags:
      - Payments
      summary: Create Server Payment
      description: 'Server-to-server payment creation. The `payMethod` field selects the

        payment method — `BankCard` (3DS), `BankTransfer`, `BankUSSD`,

        `BankAccount`, `POS`, `OPay`, or `ReferenceCode`. The response

        contains a `nextAction` describing what the merchant must do next

        (redirect for 3DS, display a virtual transfer account, display a

        USSD code, etc.). Authenticate with an HMAC-SHA512 signature of the

        JSON body as the bearer token.

        '
      operationId: createPayment
      security:
      - SignatureAuth: []
      parameters:
      - $ref: '#/components/parameters/MerchantIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCreateRequest'
      responses:
        '200':
          description: Payment created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentCreateResponse'
components:
  schemas:
    Amount:
      type: object
      required:
      - total
      - currency
      properties:
        total:
          type: integer
          format: int64
          description: Amount in the smallest currency unit (e.g. kobo / cent).
        currency:
          type: string
          description: ISO-4217 currency code.
          example: NGN
    ApiEnvelope:
      type: object
      properties:
        code:
          type: string
          example: '00000'
        message:
          type: string
          example: SUCCESSFUL
    PayMethod:
      type: string
      enum:
      - BankCard
      - BankTransfer
      - BankUSSD
      - BankAccount
      - POS
      - OPay
      - ReferenceCode
    BankCard:
      type: object
      properties:
        cardHolderName:
          type: string
        cardNumber:
          type: string
        cvv:
          type: string
        expiryMonth:
          type: string
        expiryYear:
          type: string
        enable3DS:
          type: boolean
    NextAction:
      type: object
      description: Instructions for the next step required to complete the payment.
      properties:
        actionType:
          type: string
          enum:
          - REDIRECT_3DS
          - TRANSFER_ACCOUNT
          - USSD
          - QR_CODE
          - REFERENCE_CODE
        redirectUrl:
          type: string
        transferAccountNumber:
          type: string
        transferBankName:
          type: string
        expiredTimestamp:
          type: integer
          format: int64
    PaymentCreateResponse:
      allOf:
      - $ref: '#/components/schemas/ApiEnvelope'
      - type: object
        properties:
          data:
            type: object
            properties:
              reference:
                type: string
              orderNo:
                type: string
              status:
                $ref: '#/components/schemas/PaymentStatus'
              amount:
                $ref: '#/components/schemas/Amount'
              nextAction:
                $ref: '#/components/schemas/NextAction'
    Product:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    PaymentCreateRequest:
      type: object
      required:
      - reference
      - country
      - amount
      - payMethod
      - product
      properties:
        reference:
          type: string
        country:
          type: string
          example: NG
        amount:
          $ref: '#/components/schemas/Amount'
        payMethod:
          $ref: '#/components/schemas/PayMethod'
        product:
          $ref: '#/components/schemas/Product'
        callbackUrl:
          type: string
        returnUrl:
          type: string
        customerName:
          type: string
        userInfo:
          $ref: '#/components/schemas/UserInfo'
        userPhone:
          type: string
        bankcard:
          $ref: '#/components/schemas/BankCard'
    PaymentStatus:
      type: string
      enum:
      - INITIAL
      - PENDING
      - SUCCESS
      - FAIL
      - CLOSE
    UserInfo:
      type: object
      properties:
        userId:
          type: string
        userName:
          type: string
        userEmail:
          type: string
        userMobile:
          type: string
  parameters:
    MerchantIdHeader:
      name: MerchantId
      in: header
      required: true
      schema:
        type: string
      description: The merchant identifier issued by OPay (e.g. 256612345678901).
  securitySchemes:
    PublicKeyAuth:
      type: http
      scheme: bearer
      description: Bearer token = merchant public key (used for cashier/create).
    SignatureAuth:
      type: http
      scheme: bearer
      description: Bearer token = HMAC-SHA512 of the JSON request body signed with the merchant private key.