Skip to main content

Test scenarios

General information​

We recommend running the test cases before processing real payments. This section provides detailed scenarios that allow you to:

  • verify the correctness and stability of your integration
  • simulate various payment situations to ensure the system is ready to handle real transactions and to prevent potential operational issues

For a quick start, use our Postman-collection. Fork it into your private workspace, add your credentials, and run sample requests in minutes.

Requirements:​

  1. You have a merchant portal account and an existing test project with API keys.
  2. The test project configured by Tranzzo technical support.
  3. Integration completed.

Direct integration​

Prerequisites for starting the test:

  1. You have a direct integration configured.
  2. A test project with API keys is created and active.
  3. Webhook handling and status‑code processing are set up.
Test caseAction
One-step payments (purchase)

One‑stage payment - a payment flow where the full amount is captured from the payer in a single transaction at the time of purchase.
Features:

  1. Charging can be performed using card data (cc_number, exp_month, exp_year, card_cvv), a Tranzzo token (cc_token), or A/GPay.

  2. 3DS verification control.

  3. Refunds available after purchase.

  4. Ability to obtain a receipt.

  5. Payment fiscalization.

info

If PCI DSS certification is in place, card data may be submitted in requests.
If PCI DSS certification is not in place, payments must use Tranzzo tokens obtained via the Tokenization widget.

  • Payment by Visa and Mastercard

  1. Create a payment request including cc_number, exp_month, exp_year, card_cvv.

  2. Use test card numbers according to the card brand.
    For example:
    Visa: 4242 4242 4242 4242
    Mastercard: 5454 5454 5454 5454
    The payment may immediately receive a final status of Success, or it may require 3DS/OTP verification. If the response contains "status_description": "3DS verification is required", open the URL in user_action_url and complete the ACS verification by clicking CONFIRM.

  3. Receive the webhook on your server — it will contain the payment status.

  • Payment via A/GPay wallets

  1. Create a payment request using cc_token.

    info

    cc_token can be obtained via the tokenization widget or from a previous hosted payment response or callback.


    In this case 3DS verification will not occur - the operation will immediately receive a final status.

  2. Receive the webhook on your server — it will contain the payment status.

  • Payment with 3DS/non‑3DS
  1. Create a payment request with card data and include the order_3ds_bypass parameter.
    Use:
    For 3DS: order_3ds_bypass=always - test card 4242 4242 4242 4242
    Without 3DS: order_3ds_bypass=never - test card 5555 5555 5555 4444
  2. Receive the webhook on your server — it will contain the payment status.
  • Payment with products (for fiscalisation)
  1. Create a payment request including product data.
    products - an array of items to be fiscalized. There can be multiple products, but the total sum price*qty must equal the payment amount (amount).
  2. Receive the webhook on your server — it will contain the payment status.
Refund

Refund - returning funds from the merchant (or payment service) to the payer after a payment has been processed.
A refund can be issued only for a payment with status “success”.
It can be a full refund or a partial refund. Multiple partial refunds are allowed up to the original transaction amount.

  • Successful full refund

After a successful payment (Purchase):

  1. Perform a full refund for the entire amount - 10 XTS.
    Use the order_id of the transaction being refunded (this is the order_id of the successful Purchase).
  2. Receive the refund webhook on your server — it will contain the refund status.
  • Successful partial refund

After a successful payment (Purchase):

  1. Perform a partial refund for an amount less than 10 XTS (e.g., 5 XTS or 8 XTS).
    Use the order_id of the transaction being refunded (this is the order_id of the successful Purchase).
  2. Receive the refund webhook on your server — it will contain the refund status.
  • Successful full refund for a fiscalised payment.

After a successful payment (Purchase):

  1. Perform a full refund for the entire amount - 10 XTS.
    The refund request must also include details about the product being refunded.
  2. Receive the refund webhook on your server — it will contain the refund status.
Get receipt

A receipt is a document for your customer that confirms a successful payment/transaction. It can be in two formats: PDF or raw HTML.
To obtain a receipt, use the following request.

Full‑cycle test of One‑step payment (purchase):
Payment (card, A/GPay) with full or partial refund.

  1. Initiate a payment request for 10 XTS using a cc_token or card data.

    Example request with cc_token:

    $ curl "https://cpay.tranzzo.com/api/v1/payment"
      -H "Content-Type: application/json"
      -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"
      -H "X-API-KEY: ${ENDPOINTS_KEY}"
      -X POST -d '{
        "pos_id":           "${POS_ID}",
        "mode":             "direct",
        "method":           "purchase",
        "amount":           10,
        "currency":         "XTS",
        "description":      "Order description",
        "order_id":         "123",
        "order_3ds_bypass": "always",
        "cc_token":         "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
        "server_url":       "https://callback.blackhole.com/callback",
        "result_url":       "https://example.com/result",
        "payload":          "sale=true",
        "customer_referrer": "https://example.com",
        "browser_fingerprint": {
            "browserColorDepth":       "24",
            "browserScreenHeight":     "860",
            "browserScreenWidth":      "1600",
            "browserJavaEnabled":      "false",
            "browserLanguage":         "uk-UA",
            "browserTimeZone":         "Europe/Kiev",
            "browserTimeZoneOffset":   "-120",
            "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
            "browserIpAddress":        "127.0.0.1",
            "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
        }
      }'

  2. Receive the response and ensure the payment status is Success.
    Example:

    {
    "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
    "order_id":             "123",
    "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
    "billing_order_id":     "11231231231",
    "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
    "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
    "mode":                 "direct",
    "method":               "purchase",
    "amount":               10,
    "currency":             "XTS",
    "description":          "Order description",
    "status":               "pending",
    "status_code":          "2122",
    "status_description":   "3DS verification is required to finish the transaction.",
    "user_action_required": true,
    "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
    "eci":                  "7",
    "mcc":                  "4900",
    "options_3ds":          "supported",
    "cc_mask":              "424242******4242",
    "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
    "cc_token_expiration":  "2020-10-10T10:10:22",
    "customer_id":          "123",
    "customer_ip":          "194.183.171.239",
    "customer_fname":       "Tom",
    "customer_lname":       "Hanks",
    "customer_email":       "[email protected]",
    "customer_phone":       "+380999999999",
    "customer_country":     "UA",
    "result_url":           "https://example.com/result",
    "created_at":           "2018-10-10T10:10:22.100",
    "processed_at":         "2018-10-10T10:10:23.300",
    "fee": {
      "amount": 0,
      "currency": "XTS"
    },
    "percent_fee": {
      "amount": 0,
      "currency": "XTS"
    },
    "fixed_fee": {
      "amount": 0,
      "currency": "XTS"
    },
    "payload":              "sale=true",
    "bank_short_name":      "Bank name",
    "receipt_url":          "https://cpay.tranzzo.com/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
    }

  3. Process the webhook and ensure all required parameters needed for further payment handling are received (for example: status, amount, order_id,fee).

  4. Send a 200 OK response from your server confirming successful receipt of the webhook.

  5. Create a request for a full or partial refund.

    Example:

    $ curl "https://cpay.tranzzo.com/api/v1/refund"
    -H "Content-Type: application/json"
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"
    -H "X-API-KEY: ${ENDPOINTS_KEY}"
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "XTS",
      "refund_amount":  8,
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/"
    }'
  6. Check that the refund status is Success.
Expected result: Funds are returned to the customer's account.

Hosted integration​

Prerequisites for starting the test:

  1. You have a Hosted integration configured.
  2. A test project with API keys has been created and is active.
  3. Webhook handling and status‑code processing are set up.
Test caseAction
One-step payments (purchase)

  1. Create a payment request for 10 XTS.
    A successful request returns an HTTP 303 with a Location header to which the client should be redirected to continue payment.
    Example:

    HTTP/2 303
    # .. other headers
    location: https://cpay.tranzzo.com/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form

  2. Follow the checkout link, fill in all required fields and click “Pay”.
    Checkout view:

  3. The payment may immediately receive a final status of Success, or it may require 3DS/OTP verification. If the response contains "status_description": "3DS verification is required", open the URL in user_action_url and complete the ACS verification by clicking CONFIRM.

  4. Receive the webhook on your server — it will contain the payment status.

  • Payment by Visa and Mastercard

  1. Create a payment request.

  2. Use test card numbers according to the card brand.
    For example:
    Visa: 4242 4242 4242 4242
    Mastercard: 5454 5454 5454 5454

  3. Receive the webhook on your server — it will contain the payment status.

  • Payment via A/GPay wallets

  1. Create a payment request.

  2. Follow the returned link — the checkout should open.

  3. Select one of the A/GPay methods to pay.

  4. Receive the webhook on your server — it will contain the payment status.

  • Payment with 3DS/non‑3DS
  1. Create a payment request with card data and include the order_3ds_bypass parameter.
    Use:
    For 3DS: order_3ds_bypass=always - test card 4242 4242 4242 4242
    Without 3DS: order_3ds_bypass=never - test card 5555 5555 5555 4444
    Details on using the 3DS protocol
  2. Receive the webhook on your server — it will contain the payment status.
  • Payment with products (for fiscalisation)

  1. Create a payment request including product data.

    products - an array of items to be fiscalized. There can be multiple products, but the total sum price*qty must equal the payment amount (amount).

    Example:

    {
    "amount": 6,
    "products": [
      {
        "name": "Apple",
        "amount": 2,
        "currency": "UAH",
        "qty": 3,
        "id": "1",
        "unit": "kg"
      }
    ]
    }
  2. Receive the webhook on your server — it will contain the payment status.
Refund

Refund - returning funds from the merchant (or payment service) to the payer after a payment has been processed.
A refund can be issued only for a payment with status “success”.
It can be a full refund or a partial refund. Multiple partial refunds are allowed up to the original transaction amount.

  • Successful full refund

After a successful payment (Purchase):

  1. Perform a full refund for the entire amount - 10 XTS.
    Use the order_id of the transaction being refunded (this is the order_id of the successful Purchase).
  2. Receive the refund webhook on your server — it will contain the refund status.
  • Successful partial refund

After a successful payment (Purchase):

  1. Perform a partial refund for an amount less than 10 XTS (e.g., 5 XTS or 8 XTS).
    Use the order_id of the transaction being refunded (this is the order_id of the successful Purchase).
  2. Receive the refund webhook on your server — it will contain the refund status.
  • Successful full refund for a fiscalised payment.

After a successful payment (Purchase):

  1. Perform a full refund for the entire amount - 10 XTS.
    The refund request must also include details about the product being refunded.
  2. Receive the refund webhook on your server — it will contain the refund status.
Get receipt

A receipt is a document for your customer that confirms a successful payment/transaction.
It can be in two formats: PDF or raw HTML.
Ways to obtain a receipt:

  1. After payment on the payment page: download PDF or send via email.
  2. API request
  3. In the Merchant Portal (customer account)

Full‑cycle test of One‑step payment (purchase):
Payment (card, A/GPay) with full or partial refund.

  1. Initiate a payment request for 10 XTS using the test card 4242 4242 4242 4242

    Example:

    $ curl -i "https://cpay.tranzzo.com/api/v1/payment"
    -H "Content-Type: application/json"
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"
    -H "X-API-KEY: ${ENDPOINTS_KEY}"
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "hosted",
      "method":           "purchase",
      "amount":           1,
      "currency":         "XTS",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'

  2. Follow the checkout link, fill in all required fields and click “Pay”.
    Checkout view:

  3. Receive the response and ensure the payment status is Success.
    Checkout view:

  4. Create a request for a full or partial refund.

    Example:

    $ curl "https://cpay.tranzzo.com/api/v1/refund"
    -H "Content-Type: application/json"
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"
    -H "X-API-KEY: ${ENDPOINTS_KEY}"
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "XTS",
      "refund_amount":  8,
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/"
    }'
  5. Check that the refund status is Success.
  6. Receive the refund webhook on your server. Verify the refund status is Success.
Expected result: Funds are returned to the customer's account.