Kora

opencollection: 1.0.0
info:
  name: Kora (Korapay) Merchant API
  version: '1.0'
request:
  auth:
    type: bearer
    token: '{{secretKey}}'
items:
- info:
    name: Charges
    type: folder
  items:
  - info:
      name: Initialize a charge
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/charges/initialize
      auth:
        type: bearer
        token: '{{publicKey}}'
      body:
        type: json
        data: "{\n  \"reference\": \"charge-ref-001\",\n  \"amount\": 1000,\n  \"currency\": \"NGN\",\n  \"redirect_url\"\
          : \"https://merchant-redirect-url.com\",\n  \"customer\": { \"name\": \"John Doe\", \"email\": \"johndoe@korapay.com\"\
          \ }\n}"
    docs: Initializes a checkout charge and returns a hosted checkout URL. Uses the public key.
  - info:
      name: Charge a card
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/charges/card
      body:
        type: json
        data: "{\n  \"charge_data\": \"<AES-256-encrypted-card-payload>\"\n}"
    docs: Charges a card. The card/payment data must be AES-256 encrypted with your encryption key and sent as charge_data.
  - info:
      name: Authorize a card charge (path inferred)
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/charges/card/authorize
      body:
        type: json
        data: "{\n  \"transaction_reference\": \"KPY-...\",\n  \"authorization\": { \"pin\": \"1234\" }\n}"
    docs: 'Completes a processing card charge with PIN/OTP/AVS/phone. NOTE: path inferred by convention; verify against Kora''s
      Postman docs.'
  - info:
      name: Charge mobile money
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/charges/mobile-money
      body:
        type: json
        data: "{\n  \"reference\": \"mm-ref-001\",\n  \"amount\": 1000,\n  \"currency\": \"KES\",\n  \"mobile_money\": { \"\
          number\": \"254700000000\" },\n  \"customer\": { \"name\": \"Jane Doe\", \"email\": \"jane@korapay.com\" }\n}"
    docs: Charges a mobile money wallet (KES, GHS, XAF, XOF, EGP, TZS). Response auth_model indicates the next step.
  - info:
      name: Authorize mobile money charge
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/charges/mobile-money/authorize
      body:
        type: json
        data: "{\n  \"transaction_reference\": \"KPY-PAY-...\",\n  \"authorization\": { \"otp\": \"123456\" }\n}"
    docs: Submits the OTP for a mobile money charge whose auth_model was OTP.
  - info:
      name: Charge with Pay with Bank
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/charge/pay-with-bank
      body:
        type: json
        data: "{\n  \"reference\": \"pwb-ref-001\",\n  \"amount\": 1000,\n  \"currency\": \"ZAR\",\n  \"redirect_url\": \"\
          https://merchant-redirect-url.com\",\n  \"customer\": { \"name\": \"Sam Doe\", \"email\": \"sam@korapay.com\" }\n\
          }"
    docs: Initiates a Pay with Bank (Instant EFT / direct debit) charge and returns a redirect URL.
  - info:
      name: List Pay with Bank banks
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/charge/pay-with-bank/banks
    docs: Lists banks supported for Pay with Bank (Instant EFT).
  - info:
      name: Verify / query a charge
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/charges/:reference
      params:
      - name: reference
        value: ''
        type: path
        description: The payment reference.
    docs: Retrieves the current status and details of a charge by its payment reference.
- info:
    name: Payouts
    type: folder
  items:
  - info:
      name: Request a single payout
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/transactions/disburse
      body:
        type: json
        data: "{\n  \"reference\": \"payout-ref-001\",\n  \"amount\": 5000,\n  \"currency\": \"NGN\",\n  \"destination\":\
          \ {\n    \"type\": \"bank_account\",\n    \"amount\": 5000,\n    \"currency\": \"NGN\",\n    \"bank_account\": {\
          \ \"bank\": \"044\", \"account\": \"0000000000\" },\n    \"customer\": { \"name\": \"John Doe\", \"email\": \"johndoe@korapay.com\"\
          \ }\n  }\n}"
    docs: Disburses funds from your balance to a single bank account or mobile money wallet.
  - info:
      name: Request a bulk payout
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/transactions/disburse/bulk
      body:
        type: json
        data: "{\n  \"batch_reference\": \"batch-001\",\n  \"currency\": \"NGN\",\n  \"merchant_bears_cost\": false,\n  \"\
          payouts\": [ {}, {} ]\n}"
    docs: Disburses to multiple destinations in one batch (minimum 2 payouts).
  - info:
      name: Request a remittance payout
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/transactions/disburse/remittance
      body:
        type: json
        data: "{\n  \"reference\": \"rem-ref-001\",\n  \"amount\": 100,\n  \"currency\": \"USD\",\n  \"destination\": {}\n\
          }"
    docs: Disburses a cross-border remittance payout.
  - info:
      name: Fetch payout history
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/payouts?page=1&limit=20
      params:
      - name: page
        value: '1'
        type: query
      - name: limit
        value: '20'
        type: query
    docs: Retrieves all payout transactions from your account (secret key auth).
  - info:
      name: Check payout availability
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/payouts/availability
    docs: Returns whether payouts are currently available for a destination.
- info:
    name: Virtual Bank Accounts
    type: folder
  items:
  - info:
      name: Create a virtual bank account
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/virtual-bank-account
      body:
        type: json
        data: "{\n  \"account_name\": \"John Doe\",\n  \"account_reference\": \"vba-ref-001\",\n  \"permanent\": true,\n \
          \ \"bank_code\": \"035\",\n  \"customer\": { \"name\": \"John Doe\" },\n  \"kyc\": { \"bvn\": \"00000000000\" }\n\
          }"
    docs: Creates a dedicated NGN or USD virtual bank account tied to a customer.
  - info:
      name: Retrieve a virtual bank account
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/virtual-bank-account/:accountReference
      params:
      - name: accountReference
        value: ''
        type: path
        description: The account_reference used at creation.
    docs: Retrieves a virtual bank account by its account reference.
  - info:
      name: Fetch virtual bank account transactions
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/virtual-bank-account/transactions?account_number=0000000000
      params:
      - name: account_number
        value: '0000000000'
        type: query
        description: The virtual bank account number.
    docs: Retrieves the transactions that funded a virtual bank account.
- info:
    name: Balances
    type: folder
  items:
  - info:
      name: Retrieve balances
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/balances
    docs: Returns available and pending balances across supported currencies (secret key auth).
- info:
    name: Refunds
    type: folder
  items:
  - info:
      name: Initiate a refund
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/refunds/initiate
      body:
        type: json
        data: "{\n  \"reference\": \"refund-ref-001\",\n  \"transaction_reference\": \"KPY-...\",\n  \"reason\": \"Customer\
          \ request\"\n}"
    docs: Initiates a full or partial refund for a completed pay-in transaction.
  - info:
      name: Retrieve a refund
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/refunds/:reference
      params:
      - name: reference
        value: ''
        type: path
        description: The refund reference.
    docs: Retrieves the details of a refund by its reference.
  - info:
      name: List refunds
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/refunds?page=1&limit=20
      params:
      - name: page
        value: '1'
        type: query
      - name: limit
        value: '20'
        type: query
    docs: Lists refunds within a specified time period.
- info:
    name: Currency Conversion
    type: folder
  items:
  - info:
      name: Get exchange rate
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/conversions/rates
      body:
        type: json
        data: "{\n  \"from_currency\": \"USD\",\n  \"to_currency\": \"NGN\",\n  \"amount\": 100\n}"
    docs: Returns the latest exchange rate for a currency pair and amount.
  - info:
      name: Initiate a currency conversion
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/conversions
      body:
        type: json
        data: "{\n  \"reference\": \"conv-ref-001\",\n  \"from_currency\": \"USD\",\n  \"to_currency\": \"NGN\",\n  \"amount\"\
          : 100\n}"
    docs: Converts funds between your multi-currency balances at the quoted rate.
  - info:
      name: Retrieve a conversion
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/conversions/:reference
      params:
      - name: reference
        value: ''
        type: path
        description: The conversion reference.
    docs: Retrieves a currency conversion transaction by its reference.
  - info:
      name: List conversion history
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/conversions?page=1&limit=20
      params:
      - name: page
        value: '1'
        type: query
      - name: limit
        value: '20'
        type: query
    docs: Retrieves currency conversion transactions within a given period.
- info:
    name: Misc
    type: folder
  items:
  - info:
      name: List banks
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/misc/banks?countryCode=NG
      params:
      - name: countryCode
        value: NG
        type: query
        description: ISO country code.
    docs: Lists supported banks and bank codes for a country.
  - info:
      name: Resolve a bank account
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/misc/banks/resolve
      body:
        type: json
        data: "{\n  \"bank\": \"044\",\n  \"account\": \"0000000000\",\n  \"currency\": \"NGN\"\n}"
    docs: Verifies a destination bank account and returns the resolved account holder name.
  - info:
      name: List mobile money operators
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/misc/mobile-money?countryCode=KE
      params:
      - name: countryCode
        value: KE
        type: query
        description: ISO country code.
    docs: Lists supported mobile money operators and slugs for a country.
  - info:
      name: Resolve a mobile money number
      type: http
    http:
      method: POST
      url: https://api.korapay.com/merchant/api/v1/misc/mobile-money/resolve
      body:
        type: json
        data: "{\n  \"mobile_money\": { \"number\": \"254700000000\" },\n  \"currency\": \"KES\"\n}"
    docs: Verifies a mobile money account and returns the resolved holder name.
  - info:
      name: Get payout payment purposes by country
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/misc/payout-payment-purpose-by-country-code/:countryCode
      params:
      - name: countryCode
        value: US
        type: path
        description: ISO country code of the destination.
    docs: Returns accepted payout payment-purpose values for a country.
  - info:
      name: Get supported payout countries by currency
      type: http
    http:
      method: GET
      url: https://api.korapay.com/merchant/api/v1/misc/payout-countries-by-currency-code/:currencyCode
      params:
      - name: currencyCode
        value: USD
        type: path
        description: ISO currency code.
    docs: Returns countries with supported banks under a given currency.
bundled: true