Praxis Wiki logo

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 (AMEX, DinersClub, Discover, Electron, JCB, Maestro, MasterCard, Mir, VISA) 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: