Praxis Wiki logo
Praxis Wiki
Version:
latest (API 1.3)
  • 3.3 (API 1.1)
  • 3.4 (API 1.2)
  • latest (API 1.3)

    • API v1.1 vs API v1.3

    API v1.1

    Before you migrate from API v1.1 it is worth checking:

    • Environment: Test (sandbox) or Production (live) along with endpoints.
    • Credentials (please note, we provide different credentials for different environments).
    • Test data (to check the services and methods provided, refer to test cases).

    Note: Additional changes that may be implied by this migration:
    In some cases, the migration from an older API version also means a change in the underlying cashier technology. In those cases you may also have to plan for the following changes:

    1. Cashier layout (similar but not the same).
    2. Admin interface migration from BackOffice to Praxis Atlas.

    3. PSP configuration (additional capabilities will be added). 

      Comparison of Features Supported

      The following table indicates the support for API capabilities compared between the API versions 1.1 and 1.3.

      Feature 1.1 1.3
      Cashier - Payment init-pay-in, init-checkout, init-invoice cashier
      Cashier - Authorization ✕ cashier
      Cashier - Withdrawal Request init-pay-out cashier
      Credit Card Tokenization ✕ ✓
      CC S2S Gateway - Sale sale card, apm, card-token, wallet-token
      CC S2S Gateway - Payout payout card, apm, card-token, wallet-token
      CC S2S Gateway - Refund refund refund
      APM Wallet Tokenization ✕ ✓
      APM Gateway - Sale ✕ card, apm, card-token, wallet-token
      APM Gateway - Payout ✕ card, apm, card-token, wallet-token
      APM Gateway - Refund ✕ refund
      Merchant - Manage Authorization deposit-capture, deposit-cancel manage-transaction
      Merchant - Manage Withdrawal payout-complete, payout-cancel, payout-split manage-withdrawal-request
      Merchant - Manage Payout for Withdrawal ✕ card, apm, card-token, wallet-token
      Merchant - Manage Refund for Withdrawal ✕ refund
      Merchant - Transaction Lookup find-transaction find-transaction
      Merchant - Order Lookup find-order find-order
      Merchant - Gateways Query ✕ get-gateway-options
      Misc - Validation validation validation
      Misc - Notification notification notification
      Misc - Return URL return-url return
      Misc - Authentication authentication authentication
      Misc - Virtual Terminal ✕ virtual-terminal
      Misc - Customer Sync customer-sync customer-sync


    Summary of features that are not supported in v1.1

    • Cashier authorization
    • Credit card and APM wallet tokenization - Ability to use an API function called 'Virtual Terminal'
    • Additional attributes included in Data Structure

    Data Structures

    In terms of data structure, in API v1.1 all the data structures were flat. In comparison, API v1.3 has the data structures organized under their relevant object categories.

    The following table compares API v1.3 and API v1.1. The differences can be split into three types:

    1. Attributes that exist on earlier versions of the api, now grouped into additional levels of hierarchy and keep the original attribute name.
    2. Same as the above, but changing the attribute name or replacing the original (when migration involves the underlying cashier technology).

    3. Completely new data types or data attributes in API v1.3.

      Attribute 1.1 1.3
      Transaction type. Allowed values are: authorization (auth and capture) sale (deposit) withdrawal (payout) refund return deposit funds) transaction_type transaction.transaction_type
      Transaction status will change along with processing. Details can be found in the transaction flow transaction_status transaction.transaction_status
      PSP transaction identifier transaction_id transaction.transaction_id
      Cashier (or Direct API gateway) transaction identifier trace_id transaction.tid
      Transaction identifier in your system order_id session.order_id
      Identifier of your application (website) frontend application_key
      Unique customer id in your system pin session.cid
      Transaction amount in cents amount transaction.amount
      Amount in cents to be processed within the session, null if left for the customer to decide within the Cashier ✕ session.amount
      Transaction currency currency transaction.currency
      Session currency ✕ session.currency
      Amount (in actual processing currency) in cents. Applies to successful transactions charge_amount transaction.processed_amount
      Amount (in actual processing currency) in cents. ✕ session.processed_amount
      Actual currency processed. Applies to successful transactions charge_currency transaction.processed_currency
      Actual currency processed ✕ session.processed_currency
      Payment method payment_method transaction.payment_method
      Payment processor payment_processor transaction.payment_processor
      HASH value of gateway that should processed transaction gateway transaction.gateway
      Customer card number (4444 44 ** 1233) card_number transaction.card.card_number
      Customer card type card_type transaction.card.card_type
      Customer card exp (10/2023) card_exp transaction.card.card_exp
      Customer account ID at PSP (e-wallet login or bank account) account_identifier transaction.wallet.account_identifier
      Transaction retry number (in case of soft decline or network/application error during communication with PSP) cascade_level transaction.cascade_level
      Whether a transaction is processed with first attempt (0) or upon cascade (1) is_cascade transaction.is_cascade
      Processing status code (including processing and error codes) error_code transaction.status_code
      Verbal description of the processing status error_details transaction.status_details
      In case of refund, this value specifies the ID of transaction to be refunded reference_id transaction.reference_id
      Original transaction identifier from . Use the tid of withdrawal request as withdrawal_request_id within the payout or refund if you want the payout amount to be deducted from withdrawal request as processed reference_id transaction.withdrawal_request_id
      Merchant's custom field to tag the transaction with some necessary information variable1 variable2 variable3 session.variable1 session.variable2 session.variable3
      EWallet or bank account details of the payer - may be optionally sent back by PSP ✕ transaction.wallet.data

    Authentication

    The signature algorithm is similar through all the versions, however API v1.3 has some differences in the signature construction and placement.

    Characteristic 1.1 1.3
    Reference Online document Online document
    Placement “signature” property in request and response “Gt-Authentication” HTTP header in request and response
    Input string Values of all request or response parameters, ordered by keys in alphabetical order Each API callback defines the list of properties in specific 
    Merchant secret Appended to input string before hashing Appended to input string before hashing
    Hashing algorithm SHA-384 SHA-384

    Try it out

    Here are some code examples you can use to try out Cashier payment, to give you some idea on how to implement the new API.

    In order to try it:

    2022 © PRAXIS CASHIER