Card payments
Get started
Sign In
Card payments
Accept and manage credit card payments from your customers

Cards are the most popular payment method globally, offering convenience and widespread acceptance. The Solidgate API allows developers to easily integrate card payments and cater to this preference, providing a robust, secure, and flexible solution.

The Solidgate API offers developers secure transactions with 3D Secure, tokenization for easier future payments and seamless recurring transactions.

warning
Please note that only PCI-DSS certified merchants are eligible for full API as the merchant collects sensitive card data and hosts payment form. Merchants without PCI DSS certification can use the Solidgate Guide
Understand how to integrate the payment form into your product.
Payment Form
or Guide
Easily create a safe and simple payment page.
Payment Page
for processing payments.

  • Charge API
    The charge request, a primary operation, allows withdrawing funds from cardholder accounts and utilizing 3D Secure for verification. Successfully completed operations result in funds withdrawal or hold (in case type auth is sent).

  • Recurring API
    The use of a previously obtained token, not cardholder data, marks the difference between recurring payment operations and charges. Some recurring transactions, such as one-click payments, may require 3D Secure verification. To facilitate this verification process, the merchant needs to display a bank page (ACS URL) to the customer. This bank page can be obtained through notifications or the check order status API request from the merchant end.

    Technical recommendations for one-click customer-initiated payment flow are as follows:

    1. Customer action: The customer initiates a one-click payment.
    2. Token payment: Initiate payment using the secure token tied to the customer’s payment information.
    3. Intermediate status: Immediately handle the intermediate status received from Solidgate to prepare for the next step.
    4. Pre-loader display: Show a pre-loader on the interface to indicate that the payment process is ongoing.
    5. Webhook and status polling: Set up a secure webhook to receive the final status of the order. Optionally, implement background polling to periodically check the order status as a backup.
    6. By following these points, the merchant can effectively handle a one-click, customer-initiated payment process.

  • Resign API
    Resign one-click enables token-based transactions (one-click payments) with additional CVV verification, exclusive to PCI-DSS certified merchants. Resign 3D Secure involves a resign request and a 3D Secure verification URL redirect.


  • Void API
    The void request serves to nullify pre-existing auth transactions by revoking the initial authorization. Be advised that the void method can only be executed for auth transactions.

  • Settle API
    The settle method facilitates the settlement of previously auth transactions. Be advised that if the subsequent settle amount is less than the initial auth transaction amount , the difference will be refunded to the cardholder’s account.

  • Refund API
    A refund constitutes a transactional request to Guide
    The refund process involves communication and coordination between the merchant, Solidgate, and the acquirer to ensure the refund is processed successfully.
    revert funds
    to the cardholder’s account, and it can only be executed for successfully completed transactions.
For the void API , settle API , and refund API operations, we recommend implementing automated retry logic for declined operations. Additionally, consider incorporating a strategy to trigger subsequent attempts at hourly intervals, ensuring that the cumulative retry count does not exceed 100 attempts.

  • Check order status API
    The check order status request helps to retrieve the present status of a given order. If a transaction is undergoing 3D Secure verification, the response indicates an order status of 3ds_verify .

  • Get ARN codes API
    The get ARN codes request obtains ARN codes for specific orders, providing essential information about refunds, currencies, and transaction statuses.

Auto-settle

Auto-settle is a feature that automatically settles orders if you provide a settle_interval value in your charge requests with the type auth.

Enabling this feature initiates the automatic sending of transactions for clearing after a specified delay in hours. In the event of an initial unsuccessful settlement transaction, Solidgate makes six additional settle attempts to prevent financial losses. The maximum value:

  • for Visa customer-initiated payments: 240 hours = 10 days
  • for Visa merchant-initiated payments: 120 hours = 5 days
  • for all other card brands: 144 hours = 6 days

Auto-settle is not created if the client sends a settle_interval request with null. In this case, it is necessary to manually initiate the settlement process. Additionally, auto-settle is not performed if there is at least one void transaction within a payment.

warning
The settlement process is automated when the settle_interval is defined in the charge API request. In such cases, the system undertakes the settlement management based on the set interval, eliminating the need for a separate settle API request.

3DS verification

Solidgate provides 3D Secure support for payments, enhancing security measures for both merchants and customers.

To process a payment as a Guide
This process ensures secure, reliable payment processing using 3D Secure authentication to prevent fraud.
3D Secure
payment, pass the force3ds parameter as a boolean with a default value of true.

When implementing 3D Secure payments, be prepared to display the 3D Secure bank page (ACS URL) to the customer after initiating a recurring request with a verify_url. The request process for recurring 3D Secure transactions is identical to the standard recurring methods, ensuring a seamless integration experience.

Furthermore, to handle 3D Secure transactions, make sure to set up success and fail URLs for browser redirects after a 3D Secure payment, either successful or unsuccessful. Provide necessary information for the frictionless flow of 3D Secure 2.0, such as browser details, time zone offset, and user-agent.

warning
The 3D Secure verification can be triggered either from our side or from the processor's side.

Card schemes tokenization

Card schemes offer tokenization services that replace sensitive account details, such as the Primary Account Number (PAN), with a unique digital identifier known as a network token. Visa’s tokenization service is referred to as the Visa Token Service (VTS), while Mastercard provides the Mastercard Digital Enablement Service (MDES).

Currently, Solidgate provides access to VTS/MDES solutions for merchants, and they do not need extra effort to integrate with international payment systems tokenization services. The network token is unique for each customer-merchant pairing, offering the following benefits:

  • Network tokens are managed and updated automatically by card networks, minimizing customer friction and reducing Guide
    Understand why the payment is declined and how you can resolve it.
    declines
    .
  • Network token payment information can be updated quickly and automatically, eliminating the need for a cardholder to do it in the event of expiration, reissue, or compromise.
  • Network token payments have higher authorization rates than those without.
  • Each transaction is fortified with a one-time cryptogram, ensuring better payment security.

Solidgate acquires a card scheme network token during the initial charge processing, securely storing it for subsequent payment attempts. This network token seamlessly replaces card details during authorization within regular payment flows. For Solidgate merchants using VTS/MDES services, subscription and recurring payments are automatically processed with the services tokens through terminals belonging to the same websites and mobile apps where the first charge operations occurred.

When a network token is created or updated, merchants receive a webhook. This allows them to automatically update their systems with accurate and up-to-date information about the network token statuses.

INACTIVE The network token is created but not activated.
ACTIVE The network token is activated and can be used for transaction processing.
SUSPENDED The network token is temporarily halted and cannot be used for transactions.
DEACTIVATED The MDES network token is permanently deactivated and must not be used for transactions.
DELETED The VTS network token is permanently deleted and must not be used for transactions.

The network token status can change depending on the circumstances of the payment card. If a cardholder reports an issue with their payment card or if the issuer suspects fraudulent activity, the network token status may be temporarily changed to SUSPENDED. This status allows for the reactivation of the network token once the issue is resolved. Through notifications, merchants receive updates regarding changes from SUSPENDED to ACTIVE or DELETED status. However, if the cardholder reports a lost payment card or closes their bank account, the network tokens will be updated to a permanent DEACTIVATED or DELETED status. This permanent status prevents further use of the network tokens.

Tokenization of card data and the real-time monitoring of network token status events are crucial components in preserving the integrity and security of payment processing.

Charge without CVV

Processing payments without a CVV simplifies customer interactions, leading to higher conversion rates and satisfaction. Allowing transactions without CVV for specific use cases minimizes declines and improves payment success rates. Merchants offering Guide
Create and maintain a stable and healthy business subscription model.
subscription services
or recurring billing benefit from reduced failed payments, ensuring consistent revenue and enhanced customer retention.

If you store card details and want to transfer payments from another provider to Solidgate, it is possible to perform a charge without CVV. This can be done under conditions when card details (PAN, expiration date) are stored in your database and another provider already processed the first payment made with a card having CVV.

Our payment method API is used to pay without the full card data, such as the card number and expiration date, for various payment types. Please ensure to always provide payment_type for charge payments without CVV. You can find the description of payment types below.

1-click A customer-initiated transaction (CIT) with the previously saved payment details, for example, another purchase on an e-commerce website.
recurring A subscription-based merchant-initiated transaction (MIT), for example, monthly charges for cloud storage services.
retry A reattempt of a merchant-initiated transaction (MIT) following an initial failure, for example, after insufficient funds decline.
installment A merchant-initiated debit method that allows the transaction total amount to be paid in smaller, scheduled portions over a defined period.
rebill An unscheduled withdrawal by a merchant that is triggered when needed, for example, an auto top-up initiated by the merchant under specific conditions.

MOTO transactions

MOTO (Mail Order/Telephone Order) transactions are card-not-present payments where customers provide their order and payment details through regular mail, fax, or telephone. In such transactions, the cardholder authorizes the merchant to process the transaction by sharing their card details.

MOTO transactions are exempt from Strong Customer Authentication (SCA) requirements. In the European Economic Area, payments processed with manually entered card details, such as those in MOTO transactions, are automatically categorized as MOTO by payment processors like Stripe.

The MOTO transactions flow is as follows:

  1. The customer contacts the merchant’s call center via phone or mail and provides card details, excluding CVV and 3D Secure verification.
  2. The merchant, having certified their call center according to PCI DSS standards, receives the card information and then transmits it to their payment provider via API or through a merchant portal interface.

  • Require minimal data for payment processing (only card number).
  • Exempt from SCA/PSD2 regulations.
  • Generally have a moderate payment success rate.
  • Classified as a high-risk transactions, making them more susceptible to chargebacks.

MOTO transactions, traditionally popular in TV sales, remain in use, especially in regions like the USA. They offer a flexible payment solution for merchants, especially in scenarios where physical card access is not possible.

Retrying declined charges

If a card payment transaction (charge transaction) fails, it can be attributed to various reasons, such as insufficient funds. However, if the payment is unsuccessful, it is not always necessary to cancel the order and lose the payment. Instead, a retry payment attempt can be made using a payment token.

A payment token is a unique identifier generated during a charge operation and used to identify data (such as credit card information) for future transactions.

If the payment fails due to a network error or a decline from the issuing bank, a recurring request must be made using the token from the unsuccessful first attempt. This allows for a seamless experience for the customer and can increase the chances of a successful transaction, avoiding the loss of payment.

It is important to note that our product enables merchants to organize retry logic on their part.

Retry logic Retry only card payments: Retry logic should exclude Guide
Improve your checkout conversion by accepting payments via Apple Pay.
Apple Pay
and Guide
Improve your checkout conversion by accepting payments via Google Pay.
Google Pay
transactions (those with the CRYPTOGRAM_3DS data type). A payment token is issued exclusively for successful Apple Pay and Google Pay payments, eliminating the need to retry these payment types.

Limit on the number of retries: Retry logic should be configured with a limit on the number of retries to prevent infinite retries and unnecessary charges to the customer's payment method. That is, the system must stop retrying the payment after a certain number of retries.

The interval between retry attempts: To avoid overloading the issuing bank with too many requests over a short period (which may be perceived as fraud), retry logic should include a back-off time between retries, such as waiting a few minutes before trying again or increasing the time between retries as the number of failed attempts increases.
Decline reasons Retry logic should be able to handle decline reasons for rejection and respond appropriately. For example, repeating attempts when receiving a permissible decline code (incorrect card number) and, at the same time, analyzing/counting and setting limits on identical decline codes.
Customizable rules Retry logic can allow for customizable retry rules, such as retrying only on specific decline codes. For example, if the payment fails after several retries, it is desirable to have a way to cancel or refund the payment to avoid multiple deductions from the customer's payment method.
Declined transactions Retry logic must handle declined transactions in a specific way, such as by prompting the customer to update their payment information or offering alternative payment methods.
Notification On the merchant side, it is necessary to additionally notify the customer of the result of the transaction, successful or unsuccessful.
Retry history tracking This information can be used to analyze transaction patterns and improve retry logic. The merchant should have a system that can track the history of retry attempts for transactions, including the number of retry attempts, the time of each one, and the result.
*It is important to note that retry logic must be implemented with caution to ensure that the customer’s payment details are secure and to avoid any unexpected charges. Retry logic can improve the success rate of transactions and provide a better customer experience. It is always recommended to test and monitor retry logic in production to ensure it is working as expected.

Handling of decline reason

The system can include error handling mechanisms to handle errors during the retry process and ensure that the customer is informed of the issue and provided with an appropriate resolution. Merchants should identify the reason for the payment decline when it occurs. The reasons for payment declines may vary, including insufficient funds, expired cards, or invalid card details.

Here is an example of certain reasons for a declined transaction when there is still a chance of a successful payment:

However, it is important to note that after the first attempt, the probability of a successful payment may decrease by up to three times.

Based on the reviewed statistics, we can recommend not retrying transactions for the following reasons:

If these data have not changed, the payment will still be unsuccessful.

Zero-amount authorization

A merchant may want to initiate a zero-amount authorization for the following reasons:

  • Storing card details for future use: International payment systems strongly recommend sending a zero-amount authorization before storing card credentials for subsequent transactions.
  • Card verification: A merchant may advance a potential customer to the next stage in the sales cycle by requesting their card details. This step confirms the card validity without any charges and also gauges the customer’s intent to finalize a purchase.
  • Card registration: Occasionally, customers must register a card with their account. This action ensures that the card undergoes verification for potential future charges.
    An example would be registering a card at the outset of an evaluation period, ensuring its verification for possible charges when the period ends.
  • Free trial offers: Merchants might offer their subscribers a trial period for their products at no cost or a discounted rate. This involves initiating a zero-amount authorization transaction before starting regular billing cycles.
  • Fraud prevention: Assess the risk associated with a payment card before initiating high-value transactions. This reduces the likelihood of fraudulent activities.
Some issuing banks do not support zero-amount transactions and may decline the request even when the card details are correct.

Furthermore, a successful zero-amount payment does not guarantee subsequent charge requests will receive approval, such as in cases of the Guide
The customer’s card balance has insufficient funds.
3.02 Insufficient funds
payment failure.

Request configuration

To perform a zero-amount payment, configure a charge payment request with the following settings:

  • amount field to 0
  • type field to auth
Note that a value of 0 in the amount field is valid only when used in a charge request API and if the type field is set to auth value.

Otherwise, your request will be declined with the Guide
“Invalid data” code message is used for validation errors, with the reason for the validation triggering specified in the body (object error) of the response. Also, the code message “Order not found” is used as a decline on orders in case of API response to request on non-existent order.
2.01 General reason
error code.

Authorization with 3D Secure

To process a zero-amount Guide
This process is designed to enable secure and reliable payment processing through the use of 3D Secure authentication, which provides an additional layer of security to prevent fraudulent transactions.
authorization as a 3D Secure payment
, pass the force3ds parameter as a boolean with a default value of true . Be aware that 3D Secure may be initiated either by our side or by the payment processor.

Authorization with auto-settle

Guide
Auto-settle is a feature that automatically settles orders if you provide a settle_interval value in your charge requests with the type auth.
Auto-settle feature
is not available for zero-amount payment requests.

Auto-settle will not be created if you send value in settle_interval field. When you initiate a zero-amount charge request API , we recommend sending null as the value for the settle_interval field.

Response outcomes

If the zero-amount payment is successful, the final Guide
Orders can also go through various other states, such as 3ds_verify , approved , declined , refunded , etc.
order status
displays the auth_ok value. Should the payment be unsuccessful due to an Guide
The customer entered an incorrect card number.
invalid
or Guide
Card is expired.
expired
card, the final order status shows the auth_failed value.

Note that if your payment provider does not support this API method, the zero-amount payment will be declined, resulting in the Guide
An error occurred due to the processor not supporting the requested API method.
5.10 Processor does not support requested API method
error code.

For comprehensive specifications and complete examples of requests and responses, please refer to our Solidgate API Reference.

Void and settle

A zero-amount authorization is a specific payment and merchants must not Guide
AThis process involves the merchant obtaining authorization to hold a Customer’s funds, Solidgate communicating with the acquirer to process the transaction, and the merchant settling the transaction.
settle
or Guide
The process involves the merchant obtaining authorization to hold the Customer’s funds and initiating a void operation if needed.
void
such payments.

Should you attempt to settle or void a pre-existing zero-amount transaction, expect to receive the Guide
“Invalid data” code message is used for validation errors, with the reason for the validation triggering specified in the body (object error) of the response. Also, the code message “Order not found” is used as a decline on orders in case of API response to request on non-existent order.
2.01 General reason
error code.