openapi: 3.0.3
info:
  title: Nuvei Payments API
  description: |
    Server-to-server REST API for processing card and APM transactions through Nuvei.
    All endpoints accept JSON POST bodies and respond with JSON. Authentication is performed
    via a SHA-256 checksum over an ordered concatenation of merchantId, merchantSiteId,
    clientRequestId, amount, currency, timeStamp, and merchantSecretKey.
  version: "1.0"
  contact:
    name: Nuvei Developer Support
    url: https://docs.nuvei.com
    email: support@nuvei.com
  license:
    name: Proprietary
servers:
- url: https://secure.safecharge.com/ppp/api/v1
  description: Production
- url: https://ppp-test.nuvei.com/ppp/api/v1
  description: Sandbox
tags:
- name: Payments
  description: End-to-end payment processing.
- name: Financial Operations
  description: Settle, void, and refund operations.
- name: Status
  description: Read-only transaction state.
paths:
  /payment.do:
    post:
      tags:
      - Payments
      summary: Create Payment
      operationId: createPayment
      description: |
        Performs an end-to-end PCI-compliant payment using card data, a UPO id, a temporary token
        from the Web SDK, or an APM payment option. The Nuvei platform handles 3DS2, fraud screening,
        and routing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentRequest"
      responses:
        "200":
          description: Payment result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentResponse"
  /settleTransaction.do:
    post:
      tags:
      - Financial Operations
      summary: Settle Transaction
      operationId: settleTransaction
      description: Captures a previously authorized transaction in full or in part using its
        relatedTransactionId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FinancialOperationRequest"
      responses:
        "200":
          description: Settle result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FinancialOperationResponse"
  /voidTransaction.do:
    post:
      tags:
      - Financial Operations
      summary: Void Transaction
      operationId: voidTransaction
      description: Cancels a sale, credit, or APM transaction before it has been transmitted to the
        acquirer/scheme.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FinancialOperationRequest"
      responses:
        "200":
          description: Void result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FinancialOperationResponse"
  /refundTransaction.do:
    post:
      tags:
      - Financial Operations
      summary: Refund Transaction
      operationId: refundTransaction
      description: Refunds a settled transaction in full or in part. The relatedTransactionId is
        mandatory and must reference the original payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FinancialOperationRequest"
      responses:
        "200":
          description: Refund result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FinancialOperationResponse"
  /getPaymentStatus.do:
    post:
      tags:
      - Status
      summary: Get Payment Status
      operationId: getPaymentStatus
      description: Returns the final state of a payment. Should be called only at the end of payment
        processing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StatusRequest"
      responses:
        "200":
          description: Payment status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentResponse"
components:
  schemas:
    MerchantAuth:
      type: object
      required:
      - merchantId
      - merchantSiteId
      - timeStamp
      - checksum
      properties:
        merchantId:
          type: string
          description: Merchant identifier assigned by Nuvei.
        merchantSiteId:
          type: string
          description: Site identifier for the merchant.
        clientRequestId:
          type: string
          description: Idempotent client-side identifier for the request.
        timeStamp:
          type: string
          description: yyyyMMddHHmmss timestamp used in the checksum.
        checksum:
          type: string
          description: SHA-256 of merchantId|merchantSiteId|clientRequestId|amount|currency|timeStamp|merchantSecretKey.
    Money:
      type: object
      properties:
        amount:
          type: string
          description: Decimal amount as a string (e.g. "10.00").
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
    PaymentRequest:
      allOf:
      - $ref: "#/components/schemas/MerchantAuth"
      - type: object
        required:
        - amount
        - currency
        properties:
          sessionToken:
            type: string
          userTokenId:
            type: string
          clientUniqueId:
            type: string
          amount:
            type: string
          currency:
            type: string
          paymentOption:
            $ref: "#/components/schemas/PaymentOption"
          billingAddress:
            $ref: "#/components/schemas/Address"
          shippingAddress:
            $ref: "#/components/schemas/Address"
          deviceDetails:
            $ref: "#/components/schemas/DeviceDetails"
          items:
            type: array
            items:
              $ref: "#/components/schemas/Item"
          urlDetails:
            $ref: "#/components/schemas/UrlDetails"
          isRebilling:
            type: integer
            enum: [0, 1]
    PaymentOption:
      type: object
      properties:
        card:
          $ref: "#/components/schemas/Card"
        alternativePaymentMethod:
          type: object
          additionalProperties: true
        userPaymentOptionId:
          type: string
    Card:
      type: object
      properties:
        cardNumber:
          type: string
        cardHolderName:
          type: string
        expirationMonth:
          type: string
        expirationYear:
          type: string
        CVV:
          type: string
        threeD:
          type: object
          additionalProperties: true
    Address:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        address:
          type: string
        city:
          type: string
        zip:
          type: string
        country:
          type: string
        email:
          type: string
        phone:
          type: string
    DeviceDetails:
      type: object
      properties:
        ipAddress:
          type: string
        deviceType:
          type: string
        deviceName:
          type: string
        deviceOS:
          type: string
        browser:
          type: string
    Item:
      type: object
      properties:
        name:
          type: string
        price:
          type: string
        quantity:
          type: integer
    UrlDetails:
      type: object
      properties:
        successUrl:
          type: string
        failureUrl:
          type: string
        pendingUrl:
          type: string
        notificationUrl:
          type: string
    PaymentResponse:
      type: object
      properties:
        sessionToken:
          type: string
        orderId:
          type: string
        userTokenId:
          type: string
        paymentOption:
          type: object
        transactionStatus:
          type: string
          enum: [APPROVED, DECLINED, ERROR, REDIRECT, PENDING]
        gwErrorCode:
          type: integer
        gwErrorReason:
          type: string
        gwExtendedErrorCode:
          type: integer
        transactionType:
          type: string
        transactionId:
          type: string
        externalTransactionId:
          type: string
        authCode:
          type: string
        status:
          type: string
          enum: [SUCCESS, ERROR]
        reason:
          type: string
        errCode:
          type: integer
        merchantId:
          type: string
        merchantSiteId:
          type: string
        version:
          type: string
        clientRequestId:
          type: string
        internalRequestId:
          type: integer
        clientUniqueId:
          type: string
    FinancialOperationRequest:
      allOf:
      - $ref: "#/components/schemas/MerchantAuth"
      - type: object
        required:
        - relatedTransactionId
        - amount
        - currency
        properties:
          clientUniqueId:
            type: string
          amount:
            type: string
          currency:
            type: string
          relatedTransactionId:
            type: string
          authCode:
            type: string
          comment:
            type: string
    FinancialOperationResponse:
      type: object
      properties:
        transactionId:
          type: string
        externalTransactionId:
          type: string
        transactionStatus:
          type: string
          enum: [APPROVED, DECLINED, ERROR]
        status:
          type: string
          enum: [SUCCESS, ERROR]
        authCode:
          type: string
        gwErrorCode:
          type: integer
        gwErrorReason:
          type: string
    StatusRequest:
      allOf:
      - $ref: "#/components/schemas/MerchantAuth"
      - type: object
        required:
        - sessionToken
        properties:
          sessionToken:
            type: string