Praxis Wiki logo

API v1.2 vs API v1.3


API v1.2

Before you migrate from API v1.2 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.2 and 1.3.

Feature 1.2 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 sale card, apm, card-token, wallet-token
APM Gateway - Payout payout card, apm, card-token, wallet-token
APM Gateway - Refund 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 vt-pay-in, vt-checkout, vt-pay-out, vt-pay-out-order virtual-terminal
Misc - Customer Sync customer-sync customer-sync

Summary of features that are not supported in v1.2

  • Cashier authorization
  • Credit card and APM wallet tokenization
  • Additional attributes are included in Data Structure

Data Structures

In terms of data structure, the API v1.2 can be compared to API v1.3 as plain data to structures. In comparison, API v1.3 has the data structures organized under their relevant object categories. The following table compares between API v1.3 and previous versions. 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.2 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 withddrawal_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 psp_additional_details 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: