Payment Scenarios

General Payment Flow

The general flow for issuing an order and charging your customers is as follows:

  1. Set up webhooks (see the Webhooks section) for order.paid and order.failed events, so you can easily track successful and failed orders;
  2. To issue an order, send a POST request to /orders/. Such details as the items sold, their price and the currency used are sent over this request. Note the success_redirect and failure_redirect fields in the response - these fields specify where to redirect the client in the case of order success or failure. Invalid request data will result in a code 400 error (see API errors section for more details).

The minimal request data to issue an order is the following:

{
     "client": {
        "email": test@test.com
},
      "products": [
       {
           "title": "test",
           "price": 0.3
       }
   ]
}
  1. The full_page_checkout and iframe_checkout fields in the response specify where to redirect the customer for the checkout procedures, while the api_do_url provides a Direct API URL for making a http POST request with the previously collected card data. For more information on the available checkout options, see the Checkout section;
  2. After the payment, the customer is redirected back to the URL specified in either success_redirect or failure_redirect fields appropriately;
  3. Your system receives either an order.payment_success or order.payment_failure event via webhooks.

One-Step Payments

One-step payments are suited for your loyal customers to pay for goods or services within seconds. Making a fast and clean checkout experience is crucial for increasing conversions and customer retention. You can simplify payments and integrate a Pay Now button into your website or mobile app, making online shopping as simple and smooth as possible.

Fund Reservation (Hold)

When performing a two-step payment, you can first authorize the charge and capture it later. When the charge is authorized, the funds are guaranteed by the card issuer and the amount is held on the customer's card for up to seven days (depending on the issuer settings). If the charge is not captured within the time limit, the authorization is canceled and funds released.

To reserve funds on a card without immediately executing the payment, set the skip_capture property in the order issue request to true. An order created in this way can be either charged or cancelled at a later time.

Capture

You can only execute this request for orders on hold; namely, those that were created with the skip_capture parameter set to true and with the cardholder having authorized the payment by entering their card data in the payment form. Funds can be kept reserved for no more than 28 days, although the issuer banks may impose a different, often shorter, timeout.

Capture request initiates asynchronous payment processing. You have to set up webhook callbacks to be able to properly determine whether the payment was completed successfully or not, since you won’t get these details immediately in the response.

It is possible to capture less than the initial authorization amount by passing the total parameter. Partially capturing a payment automatically releases the remaining amount. However, this option is not available for all terminals.

Cancel/Void

You can cancel an order and release the hold on the reserved funds, if the order was on the hold status. Customers won't be able to pay for a cancelled order. You cannot cancel a draft or an already paid order.


Strong Customer Authentication

Strong customer authentication (SCA) is a requirement of the EU Revised Directive on Payment Services (PSD2) on payment service providers within the European Economic Area. The requirement ensures that electronic payments are performed with multi-factor authentication, to increase the security of electronic payments.

Card Data Saving

Saving card data is necessary for the Card on File (CoF) payments. A CoF payment is a transaction where the cardholder has authorized the merchant to store their card details, so the merchant can repeatedly bill the cardholder’s account.

CoF payments are suitable for the following scenarios:

  1. One-click Cardholder Initiated Transactions (CIT): on-session payments where the cardholder approves the payment;
  2. Automatic Merchant Initiated Transactions (MIT): off-session payments where the merchant charges the cardholder irregularly and for different amounts and the cardholder does not have to approve the payment;
  3. Recurring MIT: off-session payments where the merchant charges the cardholder for a specific period and for the same amount, and the cardholder does not have to approve the payment.

All CoF payments consist of two steps:

  1. Initial payment: the first payment during which the card is saved and one of the COF scenarios assigned;
  2. Subsequent payment: all following payments that use the details (including the COF scenario assigned) of the initial payment.

You can save the card data either on the Gate side or your own (merchant’s) side.

Initial Card on File Payment

If you are willing to save the card data on the Gate side, the flow for the initial payment is as follows:

  1. Create a client object for the customer if it does not exist yet. In return, you will receive an ID for the created customer.
The minimal request data to create a client is the following:
{
    "email": "test@test.com",
    "phone": ""
}
  1. Issue the initial order as described in the General payment flow, and add the following additional information:
  • the client ID of a previously created client in the parameter original_client to whom the card will be assigned;
  • the desired setup_future_use value (possible values are one_click, automatic, recurring) to state which CoF scenario should be used;
  • force_save_method value true, if you want to save the card data without asking the cardholder for the permission (approval from your manager is necessary to use this functionality). A successful call to /orders/ will return a link to payment execution according to your account permissions: full_page_checkout, iframe_checkout, direct_post or api_do_url (see the Checkout section).

The minimal request data to issue an order for the initial CoF payment is the following:

{
     "client": {
        "original_client": "527caa07-efa2-48c1-afab-7be06c000000",
        "email": test@test.com
},
      "products": [
       {
           "title": "test",
           "price": 0.3
       }
   ],
"setup_future_use": "automatic"
}
  1. Finish the payment process, according to the desired checkout option;
  2. If needed, retrieve the saved card data with a by sending a GET request to /clients/.

If you are willing to save the card data on your (merchant’s) side and you have the appropriate permissions for it, the flow for the initial payment is as follows:

  1. Issue the initial Order as described in the General payment flow and add the desired setup_future_use value (possible values are one_click, automatic, recurring) to state which CoF scenario should be used.

The minimal request data to issue an order for the initial CoF payment is the following:

{
     "client": {
        "email": test@test.com
},
      "products": [
       {
           "title": "test",
           "price": 0.3
       }
   ],
"setup_future_use": "automatic"
}
  1. Collect the card data on your side and then create an HTTP POST request to api_do_url you got from the previous response, and send the card data with a saved_by_merchant: true flag to perform the first authorization and register the Card on File payment series.

The minimal request data to perform the initial CoF payment with card data saved on your side using api_do_url is the following:

{
      "cardholder_name": “TEST TEST”, 
      "card_number": “123456******7890"
      "exp_month": “03"
      "exp_year": “21"
      "csc": “123"
      "saved_by_merchant": “true"
}
  1. Make sure you collect the trace_id returned for the subsequent payments.

Merchant-Controlled Recurring Flow

Once you have successfully saved the card data, you can now execute subsequent Card on File payments. If you have stored the card data on the Gate side, the flow for the subsequent payments is as follows:

  1. Issue the subsequent order as described in the General payment flow and add the client ID of a previously created client in the parameter original_client who has a saved card assigned to them.

The minimal request data to issue an order for the subsequent CoF payment is the following:

{
     "client": {
        "original_client": "527caa07-efa2-48c1-afab-7be06c000000",
        "email": test@test.com
},
      "products": [
       {
           "title": "test",
           "price": 0.3
       }
   ] 
}
  1. To pay for the order, you should redirect your client to full_page_checkout or iframe_checkout for a on-session one-click checkout process or send a POST request with the payment ID to/charge/ for an off-session payment. If the card has been saved for the one-click CoF scenario, a charge request may return the order body with a threed_check_url, if the card is issued in the EEA, in which case the customer should be redirected to this URL in order to finalize the authorization;
  2. If either the subsequent payment fails with a payment-related error or you receive the order.payment_failed callback through the webhooks, deliver the full_page_checkout or iframe_checkout link to your customer, so they can perform the payment.

If you have stored the card data on your (merchant’s) side, the flow for the subsequent payments is as follows:

  1. Issue the subsequent order as described in the General payment flow; in return, you will receive the api_do_url;
  2. Execute the payment by creating an HTTP POST request to api_do_url and provide in the request body the previously collected card data and the scenario parameter (NB: it should match the setup_future_use value; i.e., one_click, automatic, or recurring) and the cof_trace_id parameter with its value being the initial payment’s ID (provided by the card scheme and returned by Gateway during the initial payment). If the one-click scenario is provided, an api_do_url may return a threed_check_url, if card is issued in the EEA, in which case the client should be redirected to this URL in order to finalize the authorization.

The minimal request data to POST a request to api_do_url for the subsequent CoF payment is the following:

{
      "cardholder_name": “TEST TEST”, 
      "card_number": “123456******7890"
      "exp_month": “03"
      "exp_year": “21"
      "scenario": “automatic"
      "cof_trace_id": “0100000000000000"
}

Billing

Invoices

Invoices provide an itemized list of goods and services purchased, including the cost, quantity, and taxes. Once the customer receives an invoice to their email, they can overview the purchase information (costs, quantity, discounts, taxes, etc) and either pay or refuse the payment. Depending on the skip_capture, funds will be transferred to your bank account immediately after payment or reserved from the customer's account​.

Order Templates and Bulk Order

The /order_templates/* APIs can be used for issuing the same order to multiple clients in bulk.

  1. Create an order template. This can be done either by directly supplying the new template information or generating a template from an existing order or an existing product;
  2. Add clients to the template. On execution, each client will receive the selected products in their order;
  3. Add products to your template. These will be issued to all clients added to the template;
  4. Execute the bulk order.

Subscriptions

Subscription method is suited for businesses that provide a continuous delivery of services to their customers. When creating a subscription, you specify the cost and quantity of goods and the time limit, during which the invoice must be paid. Convenient subscription settings allow you to add new subscribers to the previously created subscription list. You can also specify when the invoice has to be sent out: instantly, once a new subscriber is added, or at the end of the billing cycle. You can also pause the subscription. Customers receive the invoice to their email.

The /subscriptions/* API can be used for automated periodic subscription orders.

Subscription flow:

  1. Create a subscription;
  2. Add clients to your subscription. On execution, each client will receive the selected products in their order;
  3. Add products to your subscription;
  4. Send orders to all subscribed clients.

Card Verification

Card verification is a strong first-line defense against potentially fraudulent cards. It ensures that the card number provided is associated with a valid, open account and can be stored in the Vault and charged successfully. If card verification is enabled, the gateway will verify that the card is valid before it is stored in the Vault. Cards that are not valid will not be stored in the Vault. We will send a 4 digits code. Customers should provide this verification code to the merchant, and the merchant then should compare if it matches.

Visa and MasterCard payment cards have the main method of protection against unauthorized access - this is the digital code CVV2, CVC2, which is indicated on the back of the card. Many systems consider this method of protection not sufficient. To improve the security of payments online, a card verification functionality is used.

Card verification (confirmation) is a procedure in which a payment system blocks a certain amount of money on a card account. This money is not withdrawn from the account, but only blocked for a certain period of time. In order to confirm ownership of the card, the cardholder will need to:

  • Enter the card data (card number, name and surname of the cardholder, expiration date CVV2/CVC2 code);
  • Check the verification code, that was generated and sent by us, in the bank statement;
  • Enter the verification code in the payment system window (on the merchant's side). For subsequent payments, the cardholder won't have to repeat this process.

Card Verification Flow

  1. The merchant creates an order with original_client_id and verify_card=true fields. After that, the cardholder is redirected to the payment form;
  2. When the cardholder enters card data and clicks on the Pay button, we generate an additional code (4 digit number) and make a request to processing, using the Dynamic descriptor field. If payment is successful, wee save this code in the database;
  3. In the next 14 days, the cardholder enters the code on the merchant's side. After three failed attempts, the transaction is blocked (cardholder must then initiate a new transaction). After this, the merchant makes a request to the Gate verify_card endpoint and passes a special code (4 digit number) and original_client_id. We will check it, check the payment status and mark the payment card as verified for the specified original_client_id.
  4. Held money will automatically be reversed to cardholder’s account right after:
  • 14 days: if card is not verified;
  • 3 failed attempts to enter code;
  • successful verification.
  1. When the merchant makes orders for that specific original_client_id and passes use_verified_card=true keys, we will process the payment, using only the verified card. Upon payment, the cardholder enters all card data (card number, cardholder's name, expiration date, CVV2/CVC2 code). The system verifies the entered data with the data of the verified card and, if it matches, carries out the transaction.

There can be several verified cards for the same customer (number of cards not limited).


Jump to
  • General Payment Flow
  • Strong Customer Authentication
  • Card Data Saving
  • Merchant-Controlled Recurring Flow
  • Billing
  • Card Verification