API v1.2 vs API v1.3
- BEFORE YOU MIGRADE
- COMPARISON OF FEATURES SUPPORTED
- SUMMARY OF FEATURES THAT ARE NOT SUPPORTED IN v1.2
- DATA STRUCTURES
- AUTHENTICATION
- TRY IT OUT
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:
- Cashier layout (similar but not the same).
- Admin interface migration from BackOffice to Praxis Atlas.
- 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:
- Attributes that exist on earlier versions of the api, now grouped into additional levels of hierarchy and keep the original attribute name.
- Same as the above, but changing the attribute name or replacing the original (when migration involves the underlying cashier technology).
- 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:
- 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