Payment Request

Payment request model. Wraps card reader data in a structured sub-object and supports the enhanced breakdown with surcharge.

  • amount
    Type: integer · Amount
    required

    Transaction amount in cents.

  • card_reader_data
    Type: object · Card Read Data
    required

    Card reader interaction data from the SDK.

    • generalCardData
      Type: string · Generalcarddata
      required

      Encrypted general card data (TLV-encoded).

    • id
      Type: string · Id
      required

      Unique transaction identifier generated by the client SDK.

    • outcome
      Type: integer · Outcome
      required

      Card read outcome code from the NFC/EMV kernel.

    • paymentCardData
      Type: string · Paymentcarddata
      required

      Encrypted payment card data (TLV-encoded).

    • isPINFallback
      Type: boolean · Ispinfallback

      Whether the transaction fell back to PIN entry.

    • pinBypassed
      Type: boolean · Pinbypassed

      Whether PIN entry was bypassed.

  • breakdown
    Type: object · Breakdown (with Surcharge)nullable

    Optional payment breakdown with surcharge support.

    Enhanced payment amount breakdown with surcharge support. Rates can be sent as integers (old SDK format, e.g., 875 = 8.75%) or floats (new SDK format, e.g., 8.75). Values >= 100 are auto-converted from basis points.

    • subtotal
      Type: integer · Subtotal
      required

      Subtotal amount in cents before tax, tip, and surcharge.

    • surcharge
      Type: object · Surchargenullable

      Surcharge configuration. When provided, surcharge is calculated and applied to the transaction total.

      Surcharge configuration for a transaction. Only one of amount or percentage may be set. When bypass is true, neither amount nor percentage should be provided.

    • taxAmount
      Type: integer | null · Taxamount

      Tax amount in cents.

    • taxRate
      Type: number | null · Taxrate

      Tax rate as a float (e.g., 8.75 for 8.75%). Integer values >= 100 are auto-divided by 100 for backward compatibility.

    • tipAmount
      Type: integer | null · Tipamount

      Tip amount in cents.

    • tipRate
      Type: number | null · Tiprate

      Tip rate as a float (e.g., 15.0 for 15%). Integer values >= 100 are auto-divided by 100 for backward compatibility.

    • tipType
      Type: string | null · Tiptype

      Tip calculation method. One of: fixed, percentage.

  • event_id
    Type: string | null · Event Id

    Idempotency key. Auto-generated if omitted.

  • type
    Type: string | null · Type

    Transaction type. One of: sale, auth.