API v1.1 vs API v1.3

• BEFORE YOU MIGRADE
• COMPARISON OF FEATURES SUPPORTED
• SUMMARY OF FEATURES THAT ARE NOT SUPPORTED IN v1.1
• DATA STRUCTURES
• AUTHENTICATION
• TRY IT OUT

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.

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:

• Download the file
• Indicate the correct environment (sandbox, live)
• Use the credentials (merchant id, merchant secret, application key)

• Send the init cashier request

  Php 5.5+
  Download PHP example

  Python 2.7+
  Download Python example

  Nodejs 8.10+
  Download Nodejs example

  .net 5.0 c#
  Download .net 5.0 c# example

  Java 1.8+
  Download Java 1.8+ example