openapi: 3.0.3
info:
  title: Peach Authentication Payments API
  description: Payment orchestration APIs for Peach Payments, a pan-African payment gateway (South Africa, Kenya, Mauritius). Covers OAuth authentication, Checkout (Hosted / Embedded / Embedded Express), the Payments API for server-to-server debits and refunds, Payment Links, Payouts, and Reconciliation. Card processing is PCI DSS Level 1 certified. Auth is OAuth 2.0 client-credentials (clientId + clientSecret + merchantId -> Bearer access_token) for Checkout / Payouts / Reconciliation, and an inline authentication object (userId + password + entityId) for the server-to-server Payments API.
  version: '1.0'
  contact:
    name: Peach Payments Developer Support
    url: https://developer.peachpayments.com
  termsOfService: https://www.peachpayments.com/terms-and-conditions
servers:
- url: https://sandbox-dashboard.peachpayments.com
  description: Sandbox authentication host (OAuth token)
- url: https://dashboard.peachpayments.com
  description: Live authentication host (OAuth token)
tags:
- name: Payments
  description: Server-to-server debit and refund transactions.
paths:
  /payments:
    servers:
    - url: https://testapi-v2.peachpayments.com
      description: Sandbox Payments API host
    - url: https://api-v2.peachpayments.com
      description: Live Payments API host
    post:
      operationId: createPayment
      tags:
      - Payments
      summary: Initiate a debit transaction.
      description: Initiate a server-to-server debit (paymentType DB) or refund (paymentType RF). Certain parameters are required per payment brand. Local brands include PayShap (bank-to-bank instant EFT), Capitec Pay, 1Voucher (voucher PIN), Mobicred (revolving credit), RCS (store card), M-PESA (Kenya mobile money, integer amounts only), blink by Emtel and MCB Juice (Mauritius wallets), Nedbank Direct EFT, Peach EFT, Payflex, ZeroPay, Float, Happy Pay, Scan to Pay, MoneyBadger, and MauCAS. Authentication is an inline object (userId, password, entityId).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Transaction processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Bad request.
        '401':
          description: Unauthorised.
        '500':
          description: Server error.
  /payments/{uniqueId}:
    servers:
    - url: https://testapi-v2.peachpayments.com
    - url: https://api-v2.peachpayments.com
    get:
      operationId: getPaymentStatus
      tags:
      - Payments
      summary: Query transaction status.
      description: Retrieve the status and result of a previously initiated transaction.
      parameters:
      - name: uniqueId
        in: path
        required: true
        schema:
          type: string
      - name: entityId
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Transaction status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '404':
          description: Transaction not found.
components:
  schemas:
    PaymentRequest:
      type: object
      required:
      - authentication
      - merchantTransactionId
      - amount
      - currency
      - paymentBrand
      - paymentType
      properties:
        authentication:
          type: object
          required:
          - userId
          - password
          - entityId
          properties:
            userId:
              type: string
            password:
              type: string
            entityId:
              type: string
        merchantTransactionId:
          type: string
          description: 8-16 alphanumeric characters.
        amount:
          type: string
          example: '100.00'
        currency:
          type: string
          description: ISO-4217 three-letter code.
          example: ZAR
        paymentBrand:
          type: string
          description: Payment method. Includes local African brands such as PAYSHAP, CAPITECPAY, MOBICRED, ONEVOUCHER (1Voucher), RCS, MPESA (M-PESA), NEDBANKDIRECTEFT, PEACHEFT, PAYFLEX, SCANTOPAY, MAUCAS, and international brands like VISA, MASTER, PAYPAL, APPLEPAY, GOOGLEPAY.
          example: PAYSHAP
        paymentType:
          type: string
          enum:
          - DB
          - RF
          description: DB = debit, RF = refund/reversal.
        shopperResultUrl:
          type: string
          format: uri
        virtualAccount:
          type: object
          description: Method-specific account details (e.g. PayShap bank + cellphone, Capitec Pay ID number, 1Voucher PIN, Mobicred credentials).
          properties:
            bank:
              type: string
            type:
              type: string
            accountId:
              type: string
            password:
              type: string
        customer:
          type: object
        billing:
          type: object
        shipping:
          type: object
        cart:
          type: object
    PaymentResponse:
      type: object
      properties:
        id:
          type: string
        merchantTransactionId:
          type: string
        amount:
          type: string
        currency:
          type: string
        paymentBrand:
          type: string
        paymentType:
          type: string
        result:
          $ref: '#/components/schemas/Result'
    Result:
      type: object
      properties:
        code:
          type: string
          description: Peach/OPPWA result code (e.g. 000.000.000 = success).
        description:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OAuth 2.0 access_token obtained from POST /api/oauth/token, sent as Authorization: Bearer {access_token}.'