Interswitch Checkout API

openapi: 3.2.0
info:
  title: Interswitch Web Checkout API
  description: 'Interswitch Web Checkout (formerly Webpay) is the company''s hosted payment

    gateway. Two integration modes are supported: an inline JavaScript popup

    loaded from `inline-checkout.js`, and a Web Redirect form POST to

    `/collections/w/pay`. After payment, merchants must perform a server-side

    requery against `/collections/api/v1/gettransaction.json` and verify both

    the response code (`00`) and the returned amount before delivering value.

    '
  version: '2024-01-01'
  contact:
    name: Interswitch Developer Support
    url: https://www.interswitchgroup.com/support
servers:
- url: https://sandbox.interswitchng.com
  description: Sandbox
- url: https://newwebpay.interswitchng.com
  description: Production
security:
- InterswitchAuth: []
tags:
- name: Checkout
  description: Hosted checkout payment initiation
paths:
  /collections/w/pay:
    post:
      tags:
      - Checkout
      summary: Initiate Web Redirect Payment
      description: 'POST an HTML form (`application/x-www-form-urlencoded`) to redirect the

        customer to the Interswitch hosted payment page. After payment, the

        browser is redirected back to `site_redirect_url` with `txnref` in the

        query string. Always confirm the transaction server-side via

        `/collections/api/v1/gettransaction.json` before delivering value.

        '
      operationId: initiateWebRedirectPayment
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
      responses:
        '302':
          description: Redirect to hosted payment page.
        '400':
          description: Validation error in the submitted form.
components:
  schemas:
    CheckoutRequest:
      type: object
      required:
      - merchant_code
      - pay_item_id
      - txn_ref
      - amount
      - currency
      - cust_email
      - site_redirect_url
      properties:
        merchant_code:
          type: string
          description: Merchant identifier from Quickteller Business.
        pay_item_id:
          type: string
          description: Pay item identifier configured on the merchant account.
        txn_ref:
          type: string
          description: Unique merchant transaction reference.
        amount:
          type: integer
          description: Amount in minor currency units (e.g. kobo for NGN).
        currency:
          type: string
          description: ISO 4217 numeric currency code (e.g. 566 for NGN).
        cust_email:
          type: string
          format: email
        site_redirect_url:
          type: string
          format: uri
  securitySchemes:
    InterswitchAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Either `InterswitchAuth {base64(client_id)}` with companion `Timestamp`,

        `Nonce`, `Signature`, and `SignatureMethod` headers (legacy), or

        `Bearer {access_token}` obtained from the Passport OAuth token endpoint.

        '