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

Overview
anchor

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. Using the Guide
Understand how to integrate the payment form into your product. payment form or Guide
Easily build a safe and simple payment page with our straightforward, step-by-step guide. payment page , the merchant without PCI DSS certification can process payments.

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

  • Recurring API
    Recurring payment operations differ from charges as they use a previously obtained token instead of cardholder data. 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 user. This bank page can be obtained through notifications or check order status API from the merchant side.

    Technical recommendations for 1-click customer-initiated payment flow

    1. User action: The user initiates a 1-click payment.
    2. Token payment: The merchant initiates payment using the secure token tied to the user’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 user 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.
    By following these points, the merchant can effectively handle a 1-click, customer-initiated payment process.

  • Resign API
    Resign 1-click enables token-based transactions (1-click payments) with additional CVV verification, exclusive to PCI-DSS certified merchants. Resign 3DS 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 revert funds to the cardholder’s account, and it can only be executed for successfully completed transactions.
For Void API , Settle API , and Refund API , we recommend implementing automated retry logic for declined operations and incorporating an additional strategy: triggering 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 retrieves the present status of a given order. If a transaction is undergoing 3DS verification, the response will indicate 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
anchor

Auto-settle is a feature that automatically settles orders if you provide a settle_interval value in your charge requests with the type auth. If you enable this feature, we will automatically send transactions for clearing after a specified delay in hours. In the event that the first settlement transaction is unsuccessful, we will attempt to settle six more times to prevent financial losses.

Auto-settle will not be 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 won’t be performed if there’s at least one void transaction within a payment.

warning
settle_interval parameter has a limit of 7 days, which is equivalent to 168 hours.

3DS verification
anchor

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

To Guide
This process ensures secure, reliable payment processing using 3D Secure authentication to prevent fraud. process a payment as a 3D Secure payment , pass the force3ds parameter as a boolean with a default value of true. Be aware that 3DS may be triggered by either our side or the processor’s side.

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

Additionally, to handle 3DS 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 3DS may be triggered either from our side or from the processor's side.

Charge without CVV
anchor

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, performing a сharge without CVV is possible. This can be done under the following conditions when card details (PAN, expiration date) are stored in your database and the first payment with a CVV-card was processed by another provider.

Our payment method is used to pay with not the full card data (card number and expiration date) for different payment types (please always provide payment_type for charge payments without CVV):

  • 1-click
    Customer-initiated payment.
  • recurring
    Merchant-initiated subscription payment.
  • rebill
    Retry of the merchant-initiated payment.
  • installment
    Merchant-initiated debit for credit/installment (financial institutions).
  • retry
    Not regular cash withdrawals (depending on the trigger, the frequency, and amount of write-offs, in this case, is determined by the point of sale itself).
API Reference

Retrying declined charges
anchor

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.
  • Handling of 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 retry rules: Retry logic can allow for customizable retry rules, such as retrying only on specific decline codes.
    • Cancellation or refund: 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.
  • Handling of 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 user experience. It is always recommended to test and monitor retry logic in production to ensure it is working as expected.

Handling of decline reason
anchor

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. You should identify the reason for the payment decline when it occurs. There could be several reasons, such as 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.

Related articles FAQ

How do I switch to the asynchronous mode with Refund, VOID and Settle transactions?
How to avoid using the status_url?
Tracking the refund using ARN
Card tokenization from card schemes (VTS/MDES)
I can’t make a refund
Why the refund is being processed so long?
Why refunds get declined?