Cashier API virtual-terminal
virtual-terminal is the API function that allow you to open the checkout session on behalf of the customer.
Agent will be led through the process of paying an exact amount, in case of failure the manager will be helped to try with another payment option.
When executing the request, you receive json response that contains redirect_url parameter.
The redirect_url parameter is a link that will automatically do the customer login to Cashier.
This link should be embedded into iframe's src attribute
{danger.fa-exclamation-triangle} IMPORTANT #1: The validation callback will be triggered only if the
validation_urlis provided within the Cashier session request.
{danger.fa-exclamation-triangle} IMPORTANT #2: You will need to implement the customer_sync callback and provide your callback URL in order to use Virtual Terminal feature within Atlas. However, the Customer Sync is not required if Virtual Terminal is initiated over API.
Endpoints
| Name | URL |
|---|---|
| Sandbox | https://gateway.cashier-test.com/cashier/virtual-terminal |
| Live | https://gw.praxisgate.com/cashier/virtual-terminal |
Request Parameters
✓ - required value
? - optional, value or null
✕ - always appears as null
| Variable | Type | Description | |
|---|---|---|---|
| merchant_id | varchar(50) | ✓ | Merchant API client account identifier |
| application_key | varchar(32) | ✓ | Identifier of your application (website) |
| agent_name | varchar(32) | ✓ | Name of the agent performing the VT login on behalf of the customer |
| intent | varchar(32) | ✓ | Action to be taken within the cashier. Allowed values are: - authorization for authorization (hold) for the following capture - payment for payment transaction - withdrawal for withdrawal request |
| currency | varchar(10) | ✓ | Intended transaction currency |
| amount | int(20) | ? | Intended transaction amount in cents (send null to let the customer decide). Please note: for certain currencies (see full list here) there is a fraction other than 100 cents per unit, this is important if you multiply by 100 to send the amount in cents |
| balance | int(20) | ? | Customer's withdrawable balance in cents. Can be used for automatic amount validation during the withdrawal request submission (send null to bypass the validation). Please note: for certain currencies (see full list here) there is a fraction other than 100 cents per unit, this is important if you multiply by 100 to send the amount in cents |
| cid | varchar(50) | ✓ | Unique customer id in your system |
| locale | varchar(5) | ✓ | User locale. See locales reference for the full list of supported locales |
| customer_data | <Object> | ? | Customer object |
| payment_method | varchar(50) | ? | Payment method. The gateway will override this value if provided (gateway parameter is not applicable for Credit Card method for payouts). |
| gateway | varchar(32) | ? | Credit card gateway doing the processing |
| validation_url | varchar(256) | ? | URL to which the pre-deposit validation will be sent |
| notification_url | varchar(256) | ✓ | URL to which the deposit status notification will be sent |
| return_url | varchar(256) | ✓ | User will be redirected to a specified URL (relevant for cashier login, virtual terminal, 3D Secure and E-Wallet login redirect) |
| order_id | varchar(50) | ✓ | Transaction identifier in your system |
| variable1 | varchar(256) | ? | Your custom field to tag the transaction with some necessary information |
| variable2 | varchar(256) | ? | Your custom field to tag the transaction with some necessary information |
| variable3 | varchar(256) | ? | Your custom field to tag the transaction with some necessary information. E.g. profile value for the customer which is sent from CRM to us. |
| version | varchar(3) | ✓ | API version |
| timestamp | int(11) | ✓ | Request time (unix timestamp, seconds) |
Response Parameters
| Variable | Type | Description | |
|---|---|---|---|
| status | int | ✓ | API communication status - for transaction processing status please refer to transaction.transaction.status - 0 if the request was successful - Negative integer if internal server/network error occurs - Positive integer if application/logical error occurs |
| description | varchar(256) | ✓ | Accurate description of the result. Return the actual error for any exception as it helps to diagnose issues in production |
| customer | <Object> | ✓ | Customer object |
| session | <Object> | ✓ | Session object |
| version | varchar(3) | ✓ | API version |
| timestamp | int(11) | ✓ | Response time (unix timestamp, seconds) |
| redirect_url | varchar(256) | ✓ | Cashier Autologin URL. When redirected to this URL, the customer will be navigated further to the Cashier deposit page |
Signature
The full signature generation algorithm can be found in the Authentication section.
Request signature parameters
merchant_idapplication_keytimestampintentcidorder_idagent_name
Response signature parameters
statustimestampredirect_urlcustomer.customer_token
Example
Request
{
"merchant_id": "Test-Integration-Merchant",
"application_key": "Sandbox",
"agent_name": "Sales - Andrew Swift",
"intent": "sale",
"currency": "USD",
"amount": 100,
"cid": "1",
"locale": "en-GB",
"customer": {
"cid": "1",
"country": "GB",
"first_name": "John",
"last_name": "Johnson",
"dob": "12\/31\/1980",
"email": "[email protected]",
"phone": "44201112222",
"zip": "WC2N 5DU",
"state": "JS",
"city": "London",
"address": "Random st., 12\/3"
},
"payment_method": null,
"gateway": null,
"validation_url": null,
"notification_url": "https:\/\/api.merchant.com\/v1\/deposits\/tx-1560610955",
"return_url": "https:\/\/merchant.com\/payment_result\/tx-1560610955",
"order_id": "test-1560610955",
"variable1": "your variable",
"variable2": "if that is not enough, you can pass even one more variable",
"variable3": null,
"version": "1.3",
"timestamp": 1590611635
}Response (Success)
{
"status": 0,
"description": "Ok",
"customer": {
"customer_token": "87cfb23a8f1e68e162c276b754d9c061",
"country": "GB",
"first_name": "John",
"last_name": "Johnson",
"avs_alert": 0,
"verification_alert": 0
},
"session": {
"auth_token": "8a7sd87a8sd778ac961062c6bedddb8",
"intent": "payment",
"session_status": "created",
"order_id": "test-1560610955",
"currency": "EUR",
"amount": 100,
"conversion_rate": 1.000000,
"processed_currency": "EUR",
"processed_amount": 100,
"payment_method": "WireOnline",
"gateway": null,
"cid": "1",
"variable1": "your variable",
"variable2": "if that is not enough, you can pass even one more variable",
"variable3": null
},
"version": "1.3",
"timestamp": 1590611635,
"redirect_url" : "https://compute.praxispay.com/login/8F95LAal8VEsCs7Zm8lqebqGn9Grstyvva6y666hhjVUlIwsjvL3w0NWYNj95vmjzJsvnRjP90ww%2BaAxMtN2Uh0KX%2FCyEtEXNFqQS%2FvCTQ%3D"
}