Solidgate logo
API docs by Redocly

Solidgate API Reference

Download OpenAPI specification:Download

Solidgate API, which also includes US API Reference, is a payment gateway API that enables merchants to securely process and manage transactions, including card payments and alternative payment methods.

Solidgate SDK
PHP Golang Kotlin Python Node.js Vue.js Angular React

Enhance your understanding with our detailed payment guide.

Support: support@solidgate.com

Get started

Solidgate offers a suite of APIs for processing and managing payments, supporting both direct use of HTTP/REST libraries and the use of Solidgate libraries, with JSON as the data exchange format.

Environment Base URL
Card payments https://pay.solidgate.com/api/v1/
Alternative payment methods https://gate.solidgate.com/api/v1/
Payment page https://payment-page.solidgate.com/api/v1/
Payment link https://payment-page.solidgate.com/api/v1/link/
Subscriptions https://subscriptions.solidgate.com/api/v1/
Reports https://reports.solidgate.com/api/v1/

Get started quickly by:

▶ Solidgate Postman Collection

This collection offers example API requests to assist in understanding the effective use of our services.

For mass operations, it is advised to use requests with a reasonable rate limiter established (10-15 rps).


Event handling in Webhooks

When managing webhooks in Solidgate, addressing duplicate and non-ordered events is crucial. For that:

  • Implement idempotent processing to mitigate issues from duplicate events, using a unique event identifier for each action to ensure effective tracking.
  • Handle non-ordered events by temporarily storing webhooks before processing, using Solidgate API for additional data in case of event collisions, and processing events asynchronously to avoid timeout issues.

These strategies ensure accurate and reliable event handling in your system.


Authentication

API managing authentication in Solidgate is a method of verifying that access requests are coming from authorized sources through the use of a merchant and signature

When you sign up for an account in the HUB, you are given a public and secret API key pair. You authenticate with our API by providing the appropriate key in the request Authorization header. Please never share your secret keys and keep them guarded and secure.

To start accepting payments even in the sandbox environment, you’ll need credentials. Those credentials are 2 pairs of public publicKey and secret secretKey keys which should be applied for direct API calls and receiving webhook notifications accordingly.

Public and Secret Key shall be applied to calculate the signature. The signature allows verifying both the source and the integrity of the request details transmitted between the merchant and gateway.

The combination of a merchant in the header and a signature is a secure method of authenticating API requests, as it ensures that only parties in possession of the corresponding private key will be able to make requests.

To access the detailed information mentioned above, it is necessary to navigate to payment guide.

Card payments

Solidgate API for card payments allows merchants to securely integrate with a payment gateway to process and manage card transactions.

Order status Webhook

Webhooks allow merchants to securely receive real-time notifications in card order status changes, for example, from processing to declined, and automatically trigger actions or updates in their own systems based on those events.

To prevent duplicated events, make your event processing idempotent. Log the event ID after processing, and skip any events already logged.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Error object.

Returned only in cases of auth_failed, declined statuses at the order, and fail status at transaction.

object

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

object

Map of transactions where the keys are transaction identifiers.

object

Information related to the processing of the payment.

object

Payment routing information, directing transactions to optimal gateways based on parameters manually configured by our support team.

The availability of this object depends on payment processing.

object

Verification results for Address Verification Service (AVS) and Card Verification Value (CVV), providing match status.

object

Map of chargebacks where the keys are chargeback identifiers.

object

Information about the device used.

verify_url
string

URL where the customer should be redirected to complete 3DS authentication.

Only after opening the URL and authenticating the order status change to 3ds_verify.

redirect_url
string

URL where customer should be redirected after finishing 3D Secure or redirect payment method.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Provides recommendations on which payment type to offer for future orders based on the card used.

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "error": {
    },
  • "transaction": {
    },
  • "transactions": {
    },
  • "three_ds": {
    },
  • "routing": {
    },
  • "verification_result": {
    },
  • "chargebacks": {
    },
  • "device_info": {
    },
  • "verify_url": "http://merchant.example/verify",
  • "redirect_url": "http://merchant.example/redirect",
  • "order_metadata": {
    }
}

Network token created Webhook

Webhooks provide merchants with real-time notifications, indicating that the network token associated with a payment card has been issued by Visa or Mastercard. Merchants can then automatically update their systems based on these notifications.

It is possible to receive the same event more than once. This might occur during notification retries or when you ask for certain events to be resent. To guard against processing duplicated events, we recommend making your event processing idempotent. A practical approach is to log the event IDs you have processed and avoid processing those that have already been logged.

The event ID is provided in the request header parameters, as detailed below.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
card_id
string <uuid>

Unique identifier of the card provided by merchant in payment request.

tokenization_type
string
Enum: "vts" "mdes" "scof"

Type of tokenization associated with the card, a process that replaces the card's primary account number (PAN) with a unique digital token to ensure secure transactions.

status
string
Enum: "INACTIVE" "ACTIVE" "SUSPENDED" "DEACTIVATED" "DELETED"

Network token status.

created_at
string <date-time>

Network token creation date.

updated_at
string <date-time>

Date of network token status update.

Responses

Request samples

Content type
application/json
{
  • "card_id": "123e4567-e89b-12d3-a456-426614174000",
  • "tokenization_type": "vts",
  • "status": "INACTIVE",
  • "created_at": "2024-08-17 11:45:30",
  • "updated_at": "2024-08-17 11:45:30"
}

Network token updated Webhook

Webhooks provide merchants with real-time notifications when the network token associated with a payment card is updated by Visa or Mastercard. These notifications allow merchants to automatically update their systems based on the events.

It is possible to receive the same event more than once, which might occur during notification retries or when you request the resending of certain events. To prevent processing duplicate events, we recommend ensuring your event processing is idempotent. One approach is to log the event IDs you have processed and to avoid processing those that have already been logged.

The event ID is included in the request header parameters, as detailed below.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
card_id
string <uuid>

Unique identifier of the card provided by merchant in payment request.

tokenization_type
string
Enum: "vts" "mdes" "scof"

Type of tokenization associated with the card, a process that replaces the card's primary account number (PAN) with a unique digital token to ensure secure transactions.

status
string
Enum: "INACTIVE" "ACTIVE" "SUSPENDED" "DEACTIVATED" "DELETED"

Network token status.

created_at
string <date-time>

Network token creation date.

updated_at
string <date-time>

Date of network token status update.

Responses

Request samples

Content type
application/json
{
  • "card_id": "123e4567-e89b-12d3-a456-426614174000",
  • "tokenization_type": "vts",
  • "status": "INACTIVE",
  • "created_at": "2024-08-17 11:45:30",
  • "updated_at": "2024-08-17 11:45:30"
}

Chargeback Webhook

Webhooks for chargebacks allow merchants to securely receive real-time notifications of chargeback events and automatically trigger actions or updates in their own systems based on those events.

To prevent duplicated events, make your event processing idempotent. Log the event ID after processing, and skip any events already logged.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Map of chargebacks where the keys are chargeback identifiers.

Array of objects

Map of chargeback flows where the keys are chargeback flow identifiers.

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "chargeback": {
    },
  • "chargeback_flow": [
    ]
}

Prevent alert Webhook

Webhooks enable to preemptively identify and resolve potential issues, thereby preventing the generation of alert.

To prevent duplicated events, make your event processing idempotent. Log the event ID after processing, and skip any events already logged.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Information about chargeback alerts, including identifiers, amounts, currency, provider details, alert types, and outcomes.

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "alert": {
    }
}

Fraud alert Webhook

Webhooks for fraud alerts allow merchants to securely receive real-time notifications of fraud reported by card schemes.

To prevent duplicated events, make your event processing idempotent. Log the event ID after processing, and skip any events already logged.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
id
integer <= 100 characters

Unique identifier associated with a fraud alert.

order_id
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

fraud_amount
integer

Fraud amount in its smallest currency unit (cents for euros).

For instance, 1020 means 10 EUR and 20 cents.

fraud_currency
string

Three-letter ISO-4217 currency code.

fraud_amount_usd
integer

Amount converted to USD, used for standardized reporting and analysis across different currencies.

fraud_report_day
string

Date on which the fraud was reported.

fraud_type
string

Type of fraud detected, categorizing the nature of the fraudulent activity.

card_scheme
string

Card scheme associated with the transaction (e.g., Visa, Mastercard), providing context on the payment network involved.

reason_code_description
string

A detailed explanation of the reason code associated with the fraud alert, offering insights into why the fraud was flagged.

Responses

Request samples

Content type
application/json
{
  • "id": 9148812,
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "fraud_amount": 2575,
  • "fraud_currency": "USD",
  • "fraud_amount_usd": 12367,
  • "fraud_type": "6",
  • "fraud_report_day": "2020-03-24 14:22:18",
  • "card_scheme": "VISA",
  • "reason_code_description": "Fraudulent use of account number"
}

Charge

Basic operation withdraws funds from the cardholder’s account, with optional 3D Secure verification, and tokenizes the cardholder's data for future payments.

Transactions are processed using a two-step payment flow.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
One of
order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

amount
required
integer >= 0

Order amount in its smallest currency unit (cents for euros).

For instance, 1020 means 10 EUR and 20 cents.

The value 0 is valid only for zero-amount flow. If set to null, the default fallback value 0 will be used.

currency
required
string = 3 characters

Three-letter ISO-4217 currency code.

order_description
required
string <= 255 characters

Brief description of the order.

To improve the clarity of payment processing, it is advised to keep the description brief, ideally not exceeding 100 characters.

order_items
string

List and description of the items included in the order.

order_date
string <date-time> <= 50 characters

Date of order creation defined by the merchant.

order_number
integer

Index number of order per customer.

type
required
string
Value: "auth"

Payment processing flow using auth for a two-step payment.

Should be provided together with settle_interval parameter.

settle_interval
integer [ 0 .. 240 ]

Delay applied before transaction settlement indicates the hours to wait before settling.

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

The type of transaction initiator is determined by the payment_type field.

Should be provided together with type:auth.

When this field is sent, it eliminates the need for a separate settle request, as the process becomes automated.

payment_type
required
string
Enum: "1-click" "recurring" "retry" "installment" "rebill" … 1 more

Payment type that defines if the transaction is customer-initiated (CIT) or merchant-initiated (MIT) and helps to define if a cardholder authentication can be provided.

Required if card_cvv is not provided.

Payment will be declined if:

  • neither card_cvv nor payment_type is specified
  • card_cvv is specified alongside the payment_type: moto
scheme_transaction_id
string

Card scheme specific transaction identifier required for payments using stored card details, such as recurring payments.

  • Mastercard: Alphanumeric (max length 16)
    • Positions 1-3: Financial Network Code
    • Positions 4-9: Banknet Reference Number
    • Positions 10-12: Space filled
    • Positions 13-16: Banknet Settlement Date
  • Visa: Numeric (15)
  • Amex: Alphanumeric (15)
  • Discover: Alphanumeric (16)

Should not be provided with payment_type: moto.

Highly recommended to specify this parameter with payment_type: recurring, retry, installment, or rebill.

retry_attempt
integer >= 0

Number of retry attempts for the subscription payments.

Use it for analytics and conversion tuning purposes.

force3ds
boolean
Default: false

Indicates whether to force 3D Secure (3DS) authentication.

Highly recommended to set true and send it with the external_mpi_data object, as it helps optimize payment success rates.

object

Required information to process a payment that has been 3DS authenticated using a third-party merchant plug-in (MPI).

Highly recommended to provide this data, as it reduces the risk of transaction failures.

customer_account_id
string <= 100 characters

Customer's identifier defined by the merchant.

customer_date_of_birth
string <date-time> <= 10 characters

Customer's date of birth.

customer_email
required
string <= 100 characters

Customer's email address.

customer_first_name
string <= 100 characters

Customer's first name.

customer_last_name
string <= 100 characters

Customer's last name.

customer_phone
string <= 18 characters

Customer's phone number, including the country code.

card_number
required
string [ 12 .. 19 ] characters 4067429974719265

Primary account number (PAN) of the card.

The field must be transmitted in its unmasked format, containing the full Primary Account Number (PAN) without any masked digits.

card_holder
string [ 4 .. 50 ] characters ^[a-zA-Z]+ [a-zA-Z]+(?: [a-zA-Z]+)*$

Cardholder name as it appears on the card, which is essential for transaction processing.

Name must include at least one space, separating the first and last names, to ensure accurate cardholder information.

This practice is recommended to increase conversions and provide accurate cardholder details.

card_exp_month
required
string = 2 characters

Expiry month of the card.

card_exp_year
required
integer

Expiry year of the card.

card_cvv
string ^[0-9]{3,4}$

Card verification value/code (CVV) for card sources, 3 digits for most cards and 4 digits for American Express cards.

card_pin
string <= 10 characters

Personal identification number (PIN) associated with the card.

Required only for VERVE card brand.

ip_address
required
string <= 50 characters

Public IP address of the cardholder, both IPv4 and IPv6 are supported.

Required for antifraud checks. For recurring payments, use the last session or registration IP.

Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error.

traffic_source
string <= 255 characters

Indicates the origin of the traffic that led to the transaction.

transaction_source
string <= 255 characters

Provide additional context about the source of the transaction for better segmentation and analysis.

purchase_country
string <iso_code_a3> = 3 characters

Country where the goods are purchased or where the seller is based is identified using the ISO-3166 alpha-3 country code.

Required to specify if you are registered as a marketplace with international payment systems.

Being a marketplace means you operate a platform where multiple sellers offer goods or services.

geo_country
string <iso_code_a3> = 3 characters
Default: "GBR"

Customer's registration country.

geo_city
string <= 100 characters

Customer's registration city.

zip_code
string <= 10 characters

Postal code of the cardholder's billing address.

state
string <= 10 characters

ISO 3166-2 address state code of the billing address.

city
string <= 100 characters

Billing address city.

address
string <= 100 characters

First and second line of the billing address.

object

Address to ship.

If this field is passed by the merchant - the customer cannot change this address.

language
string = 2 characters
Default: "en"
Enum: "en" "fr" "es" "pt" "ja" … 5 more

Customer language settings.

website
string

Website from which payment is originated.

device
string <= 50 characters

Name and model of the device.

platform
required
string = 3 characters
Default: "WEB"
Enum: "APP" "WEB" "MOB"

Device platform used by the customer at the time of payment.

APP for application, WEB for desktop web, MOB for mobile web.

header_accept
string

Actual content of the accept HTTP header as sent by the client browser.

Required for the 3D Secure 2.0 force3ds: true.

header_accept_language
string

String indicating the language of the browser, obtained via the navigator.language property of the client browser.

Required for the 3D Secure 2.0 force3ds: true.

For format consistency, it is recommended to adhere to the IETF BCP 47 language tag standards.

browser_color_depth
integer

Color depth of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_screen_height
integer

Screen height of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_screen_width
integer

Screen width of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_java_enabled
boolean

Boolean that represents the browser capacity to execute Java. The value is the one returned by the navigator.javaEnabled() function, it can be true or false.

Required for the 3D Secure 2.0 force3ds: true.

time_zone_offset
integer

Time difference, in minutes, between UTC time and the local time of the cardholder's browser. Its value is 120 for a user in the UTC+2 time zone and -570 for the UTC-09:30 time zone.

Required for the 3D Secure 2.0 force3ds: true.

user_agent
string [ 1 .. 1000 ] characters

Device user-agent.

Required for the 3D Secure 2.0 force3ds: true.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

payment_type_data
object

Object with additional customer data to process payments in specific locations.

success_url
string <= 255 characters

URL for browser redirect after a successful payment.

fail_url
string <= 255 characters

URL for browser redirect after a failed payment.

fraudulent
boolean
Deprecated
Default: false

Whether the customer is detected by the merchant system to be suspicious one.

Responses

Response Schema: application/json
Any of
required
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

required
object

Map of transactions where the keys are transaction identifiers.

object

Information related to the processing of the payment.

object

Payment routing information, directing transactions to optimal gateways based on parameters manually configured by our support team.

The availability of this object depends on payment processing.

object

Map of chargebacks where the keys are chargeback identifiers.

object

Information about the device used.

verify_url
string

URL where the customer should be redirected to complete 3DS authentication.

Only after opening the URL and authenticating the order status change to 3ds_verify.

redirect_url
string

URL where customer should be redirected after finishing 3D Secure or redirect payment method.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Represents a payment form, including deprecated properties related to the form URL and token.

object
Deprecated

Provides recommendations on which payment type to offer for future orders based on the card used.

Request samples

Content type
application/json
Example
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "amount": 1020,
  • "currency": "EUR",
  • "order_description": "Premium package",
  • "order_items": "item 1 x 10, item 2 x 30",
  • "order_date": "2015-12-21 11:21:30",
  • "order_number": 9,
  • "type": "auth",
  • "settle_interval": 0,
  • "payment_type": "1-click",
  • "scheme_transaction_id": "MDSCAJVIJ1201",
  • "retry_attempt": 3,
  • "force3ds": false,
  • "external_mpi_data": {
    },
  • "customer_account_id": "4245d7b0-a84c-4623-91ff-e9de0254735b",
  • "customer_date_of_birth": "1988-11-21",
  • "customer_email": "example@example.com",
  • "customer_first_name": "Nikola",
  • "customer_last_name": "Tesla",
  • "customer_phone": "12025550123",
  • "card_number": "4067429974719265",
  • "card_holder": "John Snow",
  • "card_exp_month": "12",
  • "card_exp_year": 25,
  • "card_cvv": "123",
  • "card_pin": "4492",
  • "ip_address": "8.8.8.8",
  • "traffic_source": "facebook",
  • "transaction_source": "main_menu",
  • "purchase_country": "USA",
  • "geo_country": "USA",
  • "geo_city": "New Castle",
  • "zip_code": "90210",
  • "state": "WA",
  • "city": "Baltimore",
  • "address": "Apt. 123, 321 Main Street",
  • "shipping_address": {
    },
  • "language": "en",
  • "website": "merchant.example",
  • "device": "iPhone 8 iOS 12.0",
  • "platform": "WEB",
  • "header_accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng",
  • "header_accept_language": "en-US,en;q=0.9,en-US;q=0.8",
  • "browser_color_depth": 32,
  • "browser_screen_height": 1920,
  • "browser_screen_width": 1280,
  • "browser_java_enabled": true,
  • "time_zone_offset": -120,
  • "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  • "order_metadata": {
    },
  • "payment_type_data": {
    },
  • "success_url": "http://merchant.example/success",
  • "fail_url": "http://merchant.example/fail"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transaction": {
    },
  • "transactions": {
    },
  • "three_ds": {
    },
  • "routing": {
    },
  • "chargebacks": {
    },
  • "device_info": {
    },
  • "verify_url": "http://merchant.example/verify",
  • "redirect_url": "http://merchant.example/redirect",
  • "order_metadata": {
    }
}

Google Pay

An API request for Google Pay allows a merchant to initiate a Google Pay transaction, by sending a request to the Google Pay API with the required parameters such as amount, currency, and order identifier, which will be processed, and the response will be sent back with the transaction details.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
One of
is_decrypted
boolean
Default: false

Indicates whether the payload received from Google Pay was previously decrypted.

order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

amount
required
integer >= 0

Order amount in its smallest currency unit (cents for euros).

For instance, 1020 means 10 EUR and 20 cents.

The value 0 is valid only for zero-amount flow. If set to null, the default fallback value 0 will be used.

currency
required
string = 3 characters

Three-letter ISO-4217 currency code.

order_description
required
string <= 255 characters

Brief description of the order.

To improve the clarity of payment processing, it is advised to keep the description brief, ideally not exceeding 100 characters.

order_items
string

List and description of the items included in the order.

order_date
string <date-time> <= 50 characters

Date of order creation defined by the merchant.

order_number
integer

Index number of order per customer.

type
required
string
Value: "auth"

Specifies the payment processing flow using auth for a two-step payment.

Should be provided together with settle_interval parameter.

settle_interval
integer [ 0 .. 240 ]

Delay applied before transaction settlement indicates the hours to wait before settling.

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

Should be provided together with type:auth.

When this field is sent, it eliminates the need for a separate settle request, as the process becomes automated.

retry_attempt
integer >= 0

Number of retry attempts for the subscription payments.

Use it for analytics and conversion tuning purposes.

force3ds
boolean
Default: false

Indicates whether to force 3D Secure (3DS) authentication.

customer_account_id
string <= 100 characters

Customer's identifier defined by the merchant.

customer_date_of_birth
string <date-time> <= 10 characters

Customer's date of birth.

customer_email
required
string <= 100 characters

Customer's email address.

customer_first_name
string <= 100 characters

Customer's first name.

customer_last_name
string <= 100 characters

Customer's last name.

customer_phone
string <= 18 characters

Customer's phone number, including the country code.

card_holder
string [ 3 .. 50 ] characters ^[a-zA-Z]+ [a-zA-Z]+(?: [a-zA-Z]+)*$

Cardholder name as it appears on the card, which is essential for transaction processing.

Name must include at least one space, separating the first and last names, to ensure accurate cardholder information.

This practice is recommended to increase conversions and provide accurate cardholder details.

ip_address
required
string <= 50 characters

Public IP address of the cardholder, both IPv4 and IPv6 are supported.

Required for antifraud checks. For recurring payments, use the last session or registration IP.

Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error.

traffic_source
string <= 255 characters

Indicates the origin of the traffic that led to the transaction.

transaction_source
string <= 255 characters

Provide additional context about the source of the transaction for better segmentation and analysis.

purchase_country
string <iso_code_a3> = 3 characters

Country where the goods are purchased or where the seller is based is identified using the ISO-3166 alpha-3 country code.

Required to specify if you are registered as a marketplace with international payment systems.

Being a marketplace means you operate a platform where multiple sellers offer goods or services.

geo_country
string <iso_code_a3> = 3 characters
Default: "GBR"

Customer's registration country.

geo_city
string <= 100 characters

Customer's registration city.

zip_code
string <= 10 characters

Postal code of the cardholder's billing address.

state
string <= 10 characters

ISO 3166-2 address state code of the billing address.

city
string <= 100 characters

Billing address city.

address
string <= 100 characters

First and second line of the billing address.

object

Address to ship.

If this field is passed by the merchant - the customer cannot change this address.

language
string = 2 characters
Default: "en"
Enum: "en" "fr" "es" "pt" "ja" … 5 more

Customer language settings.

website
string

Website from which payment is originated.

device
string <= 50 characters

Name and model of the device.

platform
required
string = 3 characters
Default: "WEB"
Enum: "APP" "WEB" "MOB"

Device platform used by the customer at the time of payment.

APP for application, WEB for desktop web, MOB for mobile web.

header_accept
string

Actual content of the accept HTTP header as sent by the client browser.

Required for the 3D Secure 2.0 force3ds: true.

header_accept_language
string

String indicating the language of the browser, obtained via the navigator.language property of the client browser.

Required for the 3D Secure 2.0 force3ds: true.

For format consistency, it is recommended to adhere to the IETF BCP 47 language tag standards.

browser_color_depth
integer

Color depth of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_screen_height
integer

Screen height of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_screen_width
integer

Screen width of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_java_enabled
boolean

Boolean that represents the browser capacity to execute Java. The value is the one returned by the navigator.javaEnabled() function, it can be true or false.

Required for the 3D Secure 2.0 force3ds: true.

time_zone_offset
integer

Time difference, in minutes, between UTC time and the local time of the cardholder's browser. Its value is 120 for a user in the UTC+2 time zone and -570 for the UTC-09:30 time zone.

Required for the 3D Secure 2.0 force3ds: true.

user_agent
string [ 1 .. 1000 ] characters

Device user-agent.

Required for the 3D Secure 2.0 force3ds: true.

signature
required
string

Verifies that the message came from Google, base64-encoded and created using ECDSA by the intermediate signing key.

This field is taken from Google's response.

signedMessage
required
string

JSON object serialized as an HTML-safe string that contains the encryptedMessage, ephemeralPublicKey, and tag. It is serialized to simplify the signature verification process.

This field is taken from Google's response.

protocolVersion
required
string

Identifies the encryption or signing scheme under which the message is created. It allows the protocol to evolve over time if needed. If it is not set, assume ECv0.

This field is taken from Google's response.

network
string

Network (card brand) through which the payment is processed.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

payment_type_data
object

Object with additional customer data to process payments in specific locations.

success_url
string <= 255 characters

URL for browser redirect after a successful payment.

fail_url
string <= 255 characters

URL for browser redirect after a failed payment.

fraudulent
boolean
Deprecated
Default: false

Whether the customer is detected by the merchant system to be suspicious one.

Responses

Response Schema: application/json
Any of
required
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

required
object

Map of transactions where the keys are transaction identifiers.

object

Information related to the processing of the payment.

object

Payment routing information, directing transactions to optimal gateways based on parameters manually configured by our support team.

The availability of this object depends on payment processing.

object

Map of chargebacks where the keys are chargeback identifiers.

object

Information about the device used.

verify_url
string

URL where the customer should be redirected to complete 3DS authentication.

Only after opening the URL and authenticating the order status change to 3ds_verify.

redirect_url
string

URL where customer should be redirected after finishing 3D Secure or redirect payment method.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Represents a payment form, including deprecated properties related to the form URL and token.

object
Deprecated

Provides recommendations on which payment type to offer for future orders based on the card used.

Request samples

Content type
application/json
Example
{
  • "is_decrypted": false,
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "amount": 1020,
  • "currency": "EUR",
  • "order_description": "Premium package",
  • "order_items": "item 1 x 10, item 2 x 30",
  • "order_date": "2015-12-21 11:21:30",
  • "order_number": 9,
  • "type": "auth",
  • "settle_interval": 0,
  • "retry_attempt": 3,
  • "force3ds": false,
  • "customer_account_id": "4245d7b0-a84c-4623-91ff-e9de0254735b",
  • "customer_date_of_birth": "1988-11-21",
  • "customer_email": "example@example.com",
  • "customer_first_name": "Nikola",
  • "customer_last_name": "Tesla",
  • "customer_phone": "12025550123",
  • "card_holder": "John Snow",
  • "ip_address": "8.8.8.8",
  • "traffic_source": "facebook",
  • "transaction_source": "main_menu",
  • "purchase_country": "USA",
  • "geo_country": "USA",
  • "geo_city": "New Castle",
  • "zip_code": "90210",
  • "state": "WA",
  • "city": "Baltimore",
  • "address": "Apt. 123, 321 Main Street",
  • "shipping_address": {
    },
  • "language": "en",
  • "website": "merchant.example",
  • "device": "iPhone 8 iOS 12.0",
  • "platform": "WEB",
  • "header_accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng",
  • "header_accept_language": "en-US,en;q=0.9,en-US;q=0.8",
  • "browser_color_depth": 32,
  • "browser_screen_height": 1920,
  • "browser_screen_width": 1280,
  • "browser_java_enabled": true,
  • "time_zone_offset": -120,
  • "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  • "signature": "MEQCIGJGG....0ZpM4YzvUA==",
  • "signedMessage": "{\"\"\"\"encryptedMessage\"\"\"\":\"\"J......t1+Eu003d\"\"}",
  • "protocolVersion": "ECv1",
  • "network": "VISA",
  • "order_metadata": {
    },
  • "payment_type_data": {
    },
  • "success_url": "http://merchant.example/success",
  • "fail_url": "http://merchant.example/fail"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transaction": {
    },
  • "transactions": {
    },
  • "three_ds": {
    },
  • "routing": {
    },
  • "chargebacks": {
    },
  • "device_info": {
    },
  • "verify_url": "http://merchant.example/verify",
  • "redirect_url": "http://merchant.example/redirect",
  • "order_metadata": {
    }
}

Apple Pay

An API request for Apple Pay allows a merchant to initiate an Apple Pay transaction, by sending a request to the Apple Pay API with the required parameters such as amount, currency, and order identifier, which will be processed, and the response will be sent back with the transaction details.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
One of
is_decrypted
boolean
Default: false

Indicates whether the payload received from Apple Pay was previously decrypted.

order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

amount
required
integer >= 0

Order amount in its smallest currency unit (cents for euros).

For instance, 1020 means 10 EUR and 20 cents.

The value 0 is valid only for zero-amount flow. If set to null, the default fallback value 0 will be used.

currency
required
string = 3 characters

Three-letter ISO-4217 currency code.

order_description
required
string <= 255 characters

Brief description of the order.

To improve the clarity of payment processing, it is advised to keep the description brief, ideally not exceeding 100 characters.

order_items
string

List and description of the items included in the order.

order_date
string <date-time> <= 50 characters

Date of order creation defined by the merchant.

order_number
integer

Index number of order per customer.

type
required
string
Value: "auth"

Payment processing flow using auth for a two-step payment.

Should be provided together with settle_interval parameter.

settle_interval
integer [ 0 .. 240 ]

Delay applied before transaction settlement indicates the hours to wait before settling.

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

Should be provided together with type:auth.

When this field is sent, it eliminates the need for a separate settle request, as the process becomes automated.

retry_attempt
integer >= 0

Number of retry attempts for the subscription payments.

Use it for analytics and conversion tuning purposes.

customer_account_id
string <= 100 characters

Customer's identifier defined by the merchant.

customer_date_of_birth
string <date-time> <= 10 characters

Customer's date of birth.

customer_email
required
string <= 100 characters

Customer's email address.

customer_first_name
string <= 100 characters

Customer's first name.

customer_last_name
string <= 100 characters

Customer's last name.

customer_phone
string <= 18 characters

Customer's phone number, including the country code.

ip_address
required
string <= 50 characters

Public IP address of the cardholder, both IPv4 and IPv6 are supported.

Required for antifraud checks. For recurring payments, use the last session or registration IP.

Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error.

traffic_source
string <= 255 characters

Indicates the origin of the traffic that led to the transaction.

purchase_country
string <iso_code_a3> = 3 characters

Country where the goods are purchased or where the seller is based is identified using the ISO-3166 alpha-3 country code.

Required to specify if you are registered as a marketplace with international payment systems.

Being a marketplace means you operate a platform where multiple sellers offer goods or services.

geo_country
string <iso_code_a3> = 3 characters
Default: "GBR"

Customer's registration country.

geo_city
string <= 100 characters

Customer's registration city.

zip_code
string <= 10 characters

Postal code of the cardholder's billing address.

state
string <= 10 characters

ISO 3166-2 address state code of the billing address.

city
string <= 100 characters

Billing address city.

address
string <= 100 characters

First and second line of the billing address.

object

Address to ship.

If this field is passed by the merchant - the customer cannot change this address.

language
string = 2 characters
Default: "en"
Enum: "en" "fr" "es" "pt" "ja" … 5 more

Customer language settings.

website
string

Website from which payment is originated.

device
string <= 50 characters

Name and model of the device.

platform
required
string = 3 characters
Default: "WEB"
Enum: "APP" "WEB" "MOB"

Device platform used by the customer at the time of payment.

APP for application, WEB for desktop web, MOB for mobile web.

header_accept
string

Actual content of the accept HTTP header as sent by the client browser.

header_accept_language
string

String indicating the language of the browser, obtained via the navigator.language property of the client browser.

browser_color_depth
integer

Color depth of the customer browser during the payment.

browser_screen_height
integer

Screen height of the customer browser during the payment.

browser_screen_width
integer

Screen width of the customer browser during the payment.

browser_java_enabled
boolean

Boolean that represents the browser capacity to execute Java. The value is the one returned by the navigator.javaEnabled() function, it can be true or false.

time_zone_offset
integer

Time difference, in minutes, between UTC time and the local time of the cardholder's browser. Its value is 120 for a user in the UTC+2 time zone and -570 for the UTC-09:30 time zone.

user_agent
string [ 1 .. 1000 ] characters

Device user-agent.

data
required
string

Encrypted payment data, Base64 encoded as a string.

signature
required
string

Signature of the payment and header data.

The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.

version
required
string

Version information about the payment token.

Token uses EC_v1 for ECC-encrypted data and RSA_v1 for RSA-encrypted data.

network
string

Network (card brand) through which the payment is processed.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

required
object

Additional version-dependent information used to decrypt and verify the payment.

payment_type_data
object

Object with additional customer data to process payments in specific locations.

success_url
string <= 255 characters

URL for browser redirect after a successful payment.

fail_url
string <= 255 characters

URL for browser redirect after a failed payment.

fraudulent
boolean
Deprecated
Default: false

Whether the customer is detected by the merchant system to be suspicious one.

Responses

Response Schema: application/json
Any of
required
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

required
object

Map of transactions where the keys are transaction identifiers.

object

Information related to the processing of the payment.

object

Payment routing information, directing transactions to optimal gateways based on parameters manually configured by our support team.

The availability of this object depends on payment processing.

object

Map of chargebacks where the keys are chargeback identifiers.

object

Information about the device used.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Represents a payment form, including deprecated properties related to the form URL and token.

object
Deprecated

Provides recommendations on which payment type to offer for future orders based on the card used.

Request samples

Content type
application/json
Example
{
  • "is_decrypted": false,
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "amount": 1020,
  • "currency": "EUR",
  • "order_description": "Premium package",
  • "order_items": "item 1 x 10, item 2 x 30",
  • "order_date": "2024-12-21 11:21:30",
  • "order_number": 9,
  • "type": "auth",
  • "settle_interval": 0,
  • "retry_attempt": 3,
  • "customer_account_id": "4245d7b0-a84c-4623-91ff-e9de0254735b",
  • "customer_date_of_birth": "1988-11-21",
  • "customer_email": "example@example.com",
  • "customer_first_name": "Nikola",
  • "customer_last_name": "Tesla",
  • "customer_phone": "12025550123",
  • "ip_address": "8.8.8.8",
  • "traffic_source": "facebook",
  • "purchase_country": "USA",
  • "geo_country": "USA",
  • "geo_city": "New Castle",
  • "zip_code": "90210",
  • "state": "WA",
  • "city": "Baltimore",
  • "address": "Apt. 123, 321 Main Street",
  • "shipping_address": {
    },
  • "language": "en",
  • "website": "merchant.example",
  • "device": "iPhone 8 iOS 12.0",
  • "platform": "WEB",
  • "header_accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng",
  • "header_accept_language": "en-US,en;q=0.9,en-US;q=0.8",
  • "browser_color_depth": 32,
  • "browser_screen_height": 1920,
  • "browser_screen_width": 1280,
  • "browser_java_enabled": true,
  • "time_zone_offset": -120,
  • "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  • "data": "qIEHeSmLKw3C5...ZIuf2oPeLhQ1DCaQj",
  • "signature": "1UdDwEB/wQEAwIHgDAPBgkqh...92ICIAR2",
  • "version": "EC_v1",
  • "network": "VISA",
  • "order_metadata": {
    },
  • "header": {
    },
  • "payment_type_data": {
    },
  • "success_url": "http://merchant.example/success",
  • "fail_url": "http://merchant.example/fail"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transaction": {
    },
  • "transactions": {
    },
  • "three_ds": {
    },
  • "routing": {
    },
  • "chargebacks": {
    },
  • "device_info": {
    },
  • "order_metadata": {
    }
}

Recurring

Method that allows you to initiate tokenized payments. In contrast to charge request, token previously received has to be sent in the request instead of cardholder data.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
One of
order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

amount
required
integer >= 0

Order amount in its smallest currency unit (cents for euros).

For instance, 1020 means 10 EUR and 20 cents.

The value 0 is valid only for zero-amount flow. If set to null, the default fallback value 0 will be used.

currency
required
string = 3 characters

Three-letter ISO-4217 currency code.

order_description
required
string <= 255 characters

Brief description of the order.

To improve the clarity of payment processing, it is advised to keep the description brief, ideally not exceeding 100 characters.

order_items
string

List and description of the items included in the order.

order_date
string <date-time> <= 50 characters

Date of order creation defined by the merchant.

order_number
integer

Index number of order per customer.

type
required
string
Value: "auth"

Payment processing flow using auth for a two-step payment.

Should be provided together with settle_interval parameter.

settle_interval
integer [ 0 .. 240 ]

Delay applied before transaction settlement indicates the hours to wait before settling.

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

Should be provided together with type:auth.

When this field is sent, it eliminates the need for a separate settle request, as the process becomes automated.

payment_type
required
string
Enum: "1-click" "recurring" "retry" "installment" "rebill"

Payment type that defines if the transaction is customer-initiated (CIT) or merchant-initiated (MIT) and helps to define if a cardholder authentication can be provided.

Should not be provided 1-click for Apple Pay/Google Pay tokens.

recurring_token
required
string

Token associated with a card method that could be used for the subsequent payments.

retry_attempt
integer >= 0

Number of retry attempts for the subscription payments.

Use it for analytics and conversion tuning purposes.

force3ds
boolean

Indicates whether to force 3D Secure (3DS) authentication.

Highly recommended to set true and send it with the external_mpi_data object, as it helps optimize payment success rates.

object

Required information to process a payment that has been 3DS authenticated using a third-party merchant plug-in (MPI).

Highly recommended to provide this data, as it reduces the risk of transaction failures.

customer_account_id
string <= 100 characters

Customer's identifier defined by the merchant.

customer_date_of_birth
string <date-time> <= 10 characters

Customer's date of birth.

customer_email
required
string <= 100 characters

Customer's email address.

customer_first_name
string <= 100 characters

Customer's first name.

customer_last_name
string <= 100 characters

Customer's last name.

customer_phone
string <= 18 characters

Customer's phone number, including the country code.

ip_address
required
string <= 50 characters

Public IP address of the cardholder, both IPv4 and IPv6 are supported.

Required for antifraud checks. For recurring payments, use the last session or registration IP.

Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error.

traffic_source
string <= 255 characters

Indicates the origin of the traffic that led to the transaction.

transaction_source
string <= 255 characters

Provide additional context about the source of the transaction for better segmentation and analysis.

purchase_country
string <iso_code_a3> = 3 characters

Country where the goods are purchased or where the seller is based is identified using the ISO-3166 alpha-3 country code.

Required to specify if you are registered as a marketplace with international payment systems.

Being a marketplace means you operate a platform where multiple sellers offer goods or services.

geo_country
string <iso_code_a3> = 3 characters
Default: "GBR"

Customer's registration country.

geo_city
string <= 100 characters

Customer's registration city.

zip_code
string <= 10 characters

Postal code of the cardholder's billing address.

state
string <= 10 characters

ISO 3166-2 address state code of the billing address.

city
string <= 100 characters

Billing address city.

address
string <= 100 characters

First and second line of the billing address.

language
string = 2 characters
Default: "en"
Enum: "en" "fr" "es" "pt" "ja" … 5 more

Customer language settings.

website
string

Website from which payment is originated.

device
string <= 50 characters

Name and model of the device.

platform
required
string = 3 characters
Default: "WEB"
Enum: "APP" "WEB" "MOB"

Device platform used by the customer at the time of payment.

APP for application, WEB for desktop web, MOB for mobile web.

header_accept
string

Actual content of the accept HTTP header as sent by the client browser.

Required for the 3D Secure 2.0 force3ds: true.

header_accept_language
string

String indicating the language of the browser, obtained via the navigator.language property of the client browser.

Required for the 3D Secure 2.0 force3ds: true.

For format consistency, it is recommended to adhere to the IETF BCP 47 language tag standards.

browser_color_depth
integer

Color depth of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_screen_height
integer

Screen height of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_screen_width
integer

Screen width of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_java_enabled
boolean

Boolean that represents the browser capacity to execute Java. The value is the one returned by the navigator.javaEnabled() function, it can be true or false.

Required for the 3D Secure 2.0 force3ds: true.

time_zone_offset
integer

Time difference, in minutes, between UTC time and the local time of the cardholder's browser. Its value is 120 for a user in the UTC+2 time zone and -570 for the UTC-09:30 time zone.

Required for the 3D Secure 2.0 force3ds: true.

user_agent
string [ 1 .. 1000 ] characters

Device user-agent.

Required for the 3D Secure 2.0 force3ds: true.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

success_url
string <= 255 characters

URL for browser redirect after a successful payment.

fail_url
string <= 255 characters

URL for browser redirect after a failed payment.

fraudulent
boolean
Deprecated
Default: false

Whether the customer is detected by the merchant system to be suspicious one.

Responses

Response Schema: application/json
Any of
required
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

required
object

Map of transactions where the keys are transaction identifiers.

object

Information related to the processing of the payment.

object

Map of chargebacks where the keys are chargeback identifiers.

object

Information about the device used.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Represents a payment form, including deprecated properties related to the form URL and token.

object
Deprecated

Provides recommendations on which payment type to offer for future orders based on the card used.

Request samples

Content type
application/json
Example
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "amount": 1020,
  • "currency": "EUR",
  • "order_description": "Premium package",
  • "order_items": "item 1 x 10, item 2 x 30",
  • "order_date": "2015-12-21 11:21:30",
  • "order_number": 9,
  • "type": "auth",
  • "settle_interval": 0,
  • "payment_type": "1-click",
  • "recurring_token": "7ats8da7sd8-a66dfa7-a9s9das89t",
  • "retry_attempt": 3,
  • "force3ds": false,
  • "external_mpi_data": {
    },
  • "customer_account_id": "4245d7b0-a84c-4623-91ff-e9de0254735b",
  • "customer_date_of_birth": "1988-11-21",
  • "customer_email": "example@example.com",
  • "customer_first_name": "Nikola",
  • "customer_last_name": "Tesla",
  • "customer_phone": "12025550123",
  • "ip_address": "8.8.8.8",
  • "traffic_source": "facebook",
  • "transaction_source": "main_menu",
  • "purchase_country": "USA",
  • "geo_country": "USA",
  • "geo_city": "New Castle",
  • "zip_code": "90210",
  • "state": "WA",
  • "city": "Baltimore",
  • "address": "Apt. 123, 321 Main Street",
  • "language": "en",
  • "website": "merchant.example",
  • "device": "iPhone 8 iOS 12.0",
  • "platform": "WEB",
  • "header_accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng",
  • "header_accept_language": "en-US,en;q=0.9,en-US;q=0.8",
  • "browser_color_depth": 32,
  • "browser_screen_height": 1920,
  • "browser_screen_width": 1280,
  • "browser_java_enabled": true,
  • "time_zone_offset": -120,
  • "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  • "order_metadata": {
    },
  • "success_url": "http://merchant.example/success",
  • "fail_url": "http://merchant.example/fail"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transaction": {
    },
  • "transactions": {
    },
  • "three_ds": {
    },
  • "chargebacks": {
    },
  • "device_info": {
    },
  • "order_metadata": {
    }
}

Resign

Resign one-click enables token-based transactions (1-click payments) with additional CVV verification, exclusive to PCI-DSS certified merchants.

Implementing automated retry logic for declined operations is advisable, along with an additional strategy of triggering subsequent attempts at hourly intervals. It is important to ensure that the cumulative retry count remains under 120 attempts.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
One of
order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

amount
required
integer >= 0

Order amount in its smallest currency unit (cents for euros).

For instance, 1020 means 10 EUR and 20 cents.

The value 0 is valid only for zero-amount flow. If set to null, the default fallback value 0 will be used.

currency
required
string = 3 characters

Three-letter ISO-4217 currency code.

order_description
required
string <= 255 characters

Brief description of the order.

To improve the clarity of payment processing, it is advised to keep the description brief, ideally not exceeding 100 characters.

order_items
string

List and description of the items included in the order.

order_date
string <date-time> <= 50 characters

Date of order creation defined by the merchant.

order_number
integer

Index number of order per customer.

type
required
string
Value: "auth"

Payment processing flow using auth for a two-step payment.

Should be provided together with settle_interval parameter.

settle_interval
integer [ 0 .. 240 ]

Delay applied before transaction settlement indicates the hours to wait before settling.

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

Should be provided together with type:auth.

When this field is sent, it eliminates the need for a separate settle request, as the process becomes automated.

recurring_token
required
string

Token associated with a card method that could be used for the subsequent payments.

retry_attempt
integer >= 0

Number of retry attempts for the subscription payments.

Use it for analytics and conversion tuning purposes.

force3ds
boolean

Indicates whether to force 3D Secure (3DS) authentication.

Highly recommended to set true and send it with the external_mpi_data object, as it helps optimize payment success rates.

object

Required information to process a payment that has been 3DS authenticated using a third-party merchant plug-in (MPI).

Highly recommended to provide this data, as it reduces the risk of transaction failures.

customer_account_id
string <= 100 characters

Customer's identifier defined by the merchant.

customer_date_of_birth
string <date-time> <= 10 characters

Customer's date of birth.

customer_email
required
string <= 100 characters

Customer's email address.

customer_first_name
string <= 100 characters

Customer's first name.

customer_last_name
string <= 100 characters

Customer's last name.

customer_phone
string <= 18 characters

Customer's phone number, including the country code.

card_cvv
string ^[0-9]{3,4}$

Card verification value/code (CVV) for card sources, 3 digits for most cards and 4 digits for American Express cards.

ip_address
required
string <= 50 characters

Public IP address of the cardholder, both IPv4 and IPv6 are supported.

Required for antifraud checks. For recurring payments, use the last session or registration IP.

Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error.

traffic_source
string <= 255 characters

Indicates the origin of the traffic that led to the transaction.

transaction_source
string <= 255 characters

Provide additional context about the source of the transaction for better segmentation and analysis.

purchase_country
string <iso_code_a3> = 3 characters

Country where the goods are purchased or where the seller is based is identified using the ISO-3166 alpha-3 country code.

Required to specify if you are registered as a marketplace with international payment systems.

Being a marketplace means you operate a platform where multiple sellers offer goods or services.

geo_country
string <iso_code_a3> = 3 characters
Default: "GBR"

Customer's registration country.

geo_city
string <= 100 characters

Customer's registration city.

zip_code
string <= 10 characters

Postal code of the cardholder's billing address.

state
string <= 10 characters

ISO 3166-2 address state code of the billing address.

city
string <= 100 characters

Billing address city.

address
string <= 100 characters

First and second line of the billing address.

language
string = 2 characters
Default: "en"
Enum: "en" "fr" "es" "pt" "ja" … 5 more

Customer language settings.

website
string

Website from which payment is originated.

device
string <= 50 characters

Name and model of the device.

platform
required
string = 3 characters
Default: "WEB"
Enum: "APP" "WEB" "MOB"

Device platform used by the customer at the time of payment.

APP for application, WEB for desktop web, MOB for mobile web.

header_accept
string

Actual content of the accept HTTP header as sent by the client browser.

Required for the 3D Secure 2.0 force3ds: true.

header_accept_language
string

String indicating the language of the browser, obtained via the navigator.language property of the client browser.

Required for the 3D Secure 2.0 force3ds: true.

For format consistency, it is recommended to adhere to the IETF BCP 47 language tag standards.

browser_color_depth
integer

Color depth of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_screen_height
integer

Screen height of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_screen_width
integer

Screen width of the customer browser during the payment.

Required for the 3D Secure 2.0 force3ds: true.

browser_java_enabled
boolean

Boolean that represents the browser capacity to execute Java. The value is the one returned by the navigator.javaEnabled() function, it can be true or false.

Required for the 3D Secure 2.0 force3ds: true.

time_zone_offset
integer

Time difference, in minutes, between UTC time and the local time of the cardholder's browser. Its value is 120 for a user in the UTC+2 time zone and -570 for the UTC-09:30 time zone.

Required for the 3D Secure 2.0 force3ds: true.

user_agent
string [ 1 .. 1000 ] characters

Device user-agent.

Required for the 3D Secure 2.0 force3ds: true.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

payment_type_data
object

Object with additional customer data to process payments in specific locations.

success_url
string <= 255 characters

URL for browser redirect after a successful payment.

fail_url
string <= 255 characters

URL for browser redirect after a failed payment.

fraudulent
boolean
Deprecated
Default: false

Whether the customer is detected by the merchant system to be suspicious one.

Responses

Response Schema: application/json
Any of
required
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

required
object

Map of transactions where the keys are transaction identifiers.

object

Information related to the processing of the payment.

object

Payment routing information, directing transactions to optimal gateways based on parameters manually configured by our support team.

The availability of this object depends on payment processing.

object

Map of chargebacks where the keys are chargeback identifiers.

object

Information about the device used.

verify_url
string

URL where the customer should be redirected to complete 3DS authentication.

Only after opening the URL and authenticating the order status change to 3ds_verify.

redirect_url
string

URL where customer should be redirected after finishing 3D Secure or redirect payment method.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Represents a payment form, including deprecated properties related to the form URL and token.

object
Deprecated

Provides recommendations on which payment type to offer for future orders based on the card used.

Request samples

Content type
application/json
Example
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "amount": 1020,
  • "currency": "EUR",
  • "order_description": "Premium package",
  • "order_items": "item 1 x 10, item 2 x 30",
  • "order_date": "2015-12-21 11:21:30",
  • "order_number": 9,
  • "type": "auth",
  • "settle_interval": 0,
  • "recurring_token": "7ats8da7sd8-a66dfa7-a9s9das89t",
  • "retry_attempt": 3,
  • "force3ds": false,
  • "external_mpi_data": {
    },
  • "customer_account_id": "4245d7b0-a84c-4623-91ff-e9de0254735b",
  • "customer_date_of_birth": "1988-11-21",
  • "customer_email": "example@example.com",
  • "customer_first_name": "Nikola",
  • "customer_last_name": "Tesla",
  • "customer_phone": "12025550123",
  • "card_cvv": "123",
  • "ip_address": "8.8.8.8",
  • "traffic_source": "facebook",
  • "transaction_source": "main_menu",
  • "purchase_country": "USA",
  • "geo_country": "USA",
  • "geo_city": "New Castle",
  • "zip_code": "90210",
  • "state": "WA",
  • "city": "Baltimore",
  • "address": "Apt. 123, 321 Main Street",
  • "language": "en",
  • "website": "merchant.example",
  • "device": "iPhone 8 iOS 12.0",
  • "platform": "WEB",
  • "header_accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng",
  • "header_accept_language": "en-US,en;q=0.9,en-US;q=0.8",
  • "browser_color_depth": 32,
  • "browser_screen_height": 1920,
  • "browser_screen_width": 1280,
  • "browser_java_enabled": true,
  • "time_zone_offset": -120,
  • "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  • "order_metadata": {
    },
  • "payment_type_data": {
    },
  • "success_url": "http://merchant.example/success",
  • "fail_url": "http://merchant.example/fail"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transaction": {
    },
  • "transactions": {
    },
  • "three_ds": {
    },
  • "routing": {
    },
  • "chargebacks": {
    },
  • "device_info": {
    },
  • "verify_url": "http://merchant.example/verify",
  • "redirect_url": "http://merchant.example/redirect",
  • "order_metadata": {
    }
}

Refund

Request for transferring funds back to the cardholder.

Implementing automated retry logic for declined operations is advisable, along with an additional strategy of triggering subsequent attempts at hourly intervals. It is important to ensure that the cumulative retry count remains under 120 attempts.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

amount
required
integer > 0

Order amount in its smallest currency unit (cents for euros).

For instance, 1020 means 10 EUR and 20 cents.

refund_reason_code
string = 4 characters

Code representing the reason for the refund.

This code is used to identify the reason for both void and refund transactions operation

Responses

Response Schema: application/json
Any of
required
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

required
object

Map of transactions where the keys are transaction identifiers.

object

Information related to the processing of the payment.

object

Payment routing information, directing transactions to optimal gateways based on parameters manually configured by our support team.

The availability of this object depends on payment processing.

object

Map of chargebacks where the keys are chargeback identifiers.

object

Information about the device used.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Represents a payment form, including deprecated properties related to the form URL and token.

object
Deprecated

Provides recommendations on which payment type to offer for future orders based on the card used.

Request samples

Content type
application/json
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "amount": 1020,
  • "refund_reason_code": "0022"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transaction": {
    },
  • "transactions": {
    },
  • "three_ds": {
    },
  • "routing": {
    },
  • "chargebacks": {
    },
  • "device_info": {
    },
  • "order_metadata": {
    }
}

Void

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.

Implementing automated retry logic for declined operations is advisable, along with an additional strategy of triggering subsequent attempts at hourly intervals. It is important to ensure that the cumulative retry count remains under 120 attempts.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

Responses

Response Schema: application/json
Any of
required
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

required
object

Map of transactions where the keys are transaction identifiers.

object

Information related to the processing of the payment.

object

Payment routing information, directing transactions to optimal gateways based on parameters manually configured by our support team.

The availability of this object depends on payment processing.

object

Map of chargebacks where the keys are chargeback identifiers.

object

Information about the device used.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Represents a payment form, including deprecated properties related to the form URL and token.

object
Deprecated

Provides recommendations on which payment type to offer for future orders based on the card used.

Request samples

Content type
application/json
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transaction": {
    },
  • "transactions": {
    },
  • "three_ds": {
    },
  • "routing": {
    },
  • "chargebacks": {
    },
  • "device_info": {
    },
  • "order_metadata": {
    }
}

Settle

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.

Implementing automated retry logic for declined operations is advisable, along with an additional strategy of triggering subsequent attempts at hourly intervals. It is important to ensure that the cumulative retry count remains under 120 attempts.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

amount
required
integer > 0

Order amount in its smallest currency unit (cents for euros).

For instance, 1020 means 10 EUR and 20 cents.

Responses

Response Schema: application/json
Any of
required
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

required
object

Map of transactions where the keys are transaction identifiers.

object

Information related to the processing of the payment.

object

Payment routing information, directing transactions to optimal gateways based on parameters manually configured by our support team.

The availability of this object depends on payment processing.

object

Map of chargebacks where the keys are chargeback identifiers.

object

Information about the device used.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Represents a payment form, including deprecated properties related to the form URL and token.

object
Deprecated

Provides recommendations on which payment type to offer for future orders based on the card used.

Request samples

Content type
application/json
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "amount": 1020
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transaction": {
    },
  • "transactions": {
    },
  • "three_ds": {
    },
  • "routing": {
    },
  • "chargebacks": {
    },
  • "device_info": {
    },
  • "order_metadata": {
    }
}

Check order status

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.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

Responses

Response Schema: application/json
Any of
required
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Error object.

Returned only in cases of auth_failed, declined statuses at the order, and fail status at transaction.

object

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

required
object

Map of transactions where the keys are transaction identifiers.

object

Information related to the processing of the payment.

object

Payment routing information, directing transactions to optimal gateways based on parameters manually configured by our support team.

The availability of this object depends on payment processing.

object

Verification results for Address Verification Service (AVS) and Card Verification Value (CVV), providing match status.

object

Map of chargebacks where the keys are chargeback identifiers.

object

Information about the device used.

verify_url
string

URL where the customer should be redirected to complete 3DS authentication.

Only after opening the URL and authenticating the order status change to 3ds_verify.

redirect_url
string

URL where customer should be redirected after finishing 3D Secure or redirect payment method.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Represents a payment form, including deprecated properties related to the form URL and token.

object
Deprecated

Provides recommendations on which payment type to offer for future orders based on the card used.

Request samples

Content type
application/json
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "error": {
    },
  • "transaction": {
    },
  • "transactions": {
    },
  • "three_ds": {
    },
  • "routing": {
    },
  • "verification_result": {
    },
  • "chargebacks": {
    },
  • "device_info": {
    },
  • "verify_url": "http://merchant.example/verify",
  • "redirect_url": "http://merchant.example/redirect",
  • "order_metadata": {
    }
}

Get ARN codes

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

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

Responses

Response Schema: application/json
Any of
Array of objects

Array data with information about ARN codes corresponding to the order requested.

Request samples

Content type
application/json
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55"
}

Response samples

Content type
application/json
Example
{
  • "arn_codes": [
    ]
}

Alternative payment methods

Solidgate API for alternative payment methods allows merchants to securely integrate with a payment gateway to process and manage APM transactions such as PayPal, Open banking, etc.

Order status Webhook

Webhooks for alternative payment method status enable merchants to securely receive real-time notifications of changes in the status of alternative payment methods, such as processing or declined, and automatically initiate actions or updates in their own systems based on those events.

To prevent duplicated events, make your event processing idempotent. Log the event ID after processing, and skip any events already logged.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Error object.

Returned only in cases of declined statuses at the order, and fail status at transaction.

Array of objects

Details of transactions, including identifiers, amounts, currencies, statuses, and types.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

object
Deprecated

Payment form data.

Including fields necessary for processing the payment.

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "error": {
    },
  • "transactions": [
    ],
  • "order_metadata": {
    }
}

PayPal dispute Webhook

Webhooks delivers critical insights into each PayPal dispute and its lifecycle, enabling businesses to manage disputes effectively and enhance customer satisfaction.

To prevent duplicated events, make your event processing idempotent. Log the event ID after processing, and skip any events already logged.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
dispute_id
string

Unique identifier associated with a dispute.

order_id
string <= 255 characters

Order identifier defined by the merchant.

subscription_product_id
string <uuid> = 36 characters

Unique product identifier of the customer’s subscription.

It corresponds to the product_id parameter in subscriptions.

subscription_service_id
string <uuid> = 36 characters

Unique identifier associated with a specific subscription.

It corresponds to the subscription_id parameter in subscriptions.

created_at
string <date-time>

Datetime on which the dispute was created.

updated_at
string <date-time>

Datetime on which the dispute was updated.

seller_response_due_date
string

Deadline by which to respond to the dispute.

dispute_amount
integer

Dispute amount.

dispute_currency
string = 3 characters

Three-letter ISO-4217 currency code of the dispute.

dispute_life_cycle_stage
string
Enum: "INQUIRY" "CHARGEBACK" "PRE_ARBITRATION" "ARBITRATION"

Stage in the dispute lifecycle.

dispute_channel
string
Enum: "INTERNAL" "EXTERNAL" "ALERT"

Indicates the channel by which PayPal dispute has been received.

dispute_create_time
string

Datetime on which the dispute was created.

dispute_update_time
string

Datetime on which the dispute was updated.

dispute_outcome
string
Enum: "RESOLVED_BUYER_FAVOUR" "RESOLVED_SELLER_FAVOUR" "RESOLVED_WITH_PAYOUT" "CANCELED_BY_BUYER" "NONE"

Outcome of the dispute.

reason
string
Enum: "MERCHANDISE_OR_SERVICE_NOT_RECEIVED" "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED" "UNAUTHORISED" "CREDIT_NOT_PROCESSED" "DUPLICATE_TRANSACTION" … 5 more

Reason for the received dispute.

status
string
Enum: "OPEN" "WAITING_FOR_BUYER_RESPONSE" "WAITING_FOR_SELLER_RESPONSE" "UNDER_REVIEW" "RESOLVED" … 1 more

Status of the PayPal dispute.

customer_account_id
string <= 100 characters

Customer identifier defined by the merchant.

customer_email
string

Customer's email address.

Responses

Request samples

Content type
application/json
{
  • "dispute_id": "PP-D-85112454",
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "subscription_product_id": "ac43b415-5522-4373-b026-a365462f9657",
  • "subscription_service_id": "fb603790-xxxx-1111-xxxx-ae4d59d5d378",
  • "created_at": "2024-08-23 12:05:28",
  • "updated_at": "2024-08-23 12:05:28",
  • "seller_response_due_date": "2024-09-14 16:29:12",
  • "dispute_amount": 100,
  • "dispute_currency": "USD",
  • "dispute_life_cycle_stage": "INQUIRY",
  • "dispute_channel": "INTERNAL",
  • "dispute_create_time": "2024-07-02 23:39:06",
  • "dispute_update_time": "2024-07-08 1:40:44",
  • "dispute_outcome": "RESOLVED_WITH_PAYOUT",
  • "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
  • "status": "WAITING_FOR_BUYER_RESPONSE",
  • "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
  • "customer_email": "example@example.com"
}

Prevent alert Webhook

Webhooks enable to preemptively identify and resolve potential issues, thereby preventing the generation of alert, specifically for the PayPal method.

To prevent duplicated events, make your event processing idempotent. Log the event ID after processing, and skip any events already logged.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Information about chargeback alerts, including identifiers, amounts, currency, provider details, alert types, and outcomes.

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "alert": {
    }
}

Init payment

Operation for the initiation of a payment using an APMs, performs order creation and prepares the transaction for payment, allowing the customer to proceed with the payment process.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
One of
payment_method
required
string

Payment method name.

order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

amount
required
integer >= 0

Order amount in the smallest currency unit supported by the alternative payment method.

For COP, CRC, HUF, LAK, RSD, and TWD, should pass the integer value of the amount with two zeros at the end (for example, XXXX00, which will be transferred as XXXX.00). The value 0 is valid only for obtaining a billing agreement token (recurring-token).

currency
required
string = 3 characters

Three-letter ISO-4217 currency code.

order_description
required
string <= 100 characters

Brief description of the order.

For the init-payment subscription and one-time payments, the field value is displayed on the user's PayPal statement.

For recurring subscription payments, the field is configured in the product settings - Public Product Description (HUB → Subscriptions → Products → Select product → Edit details).

order_date
string <date-time> <= 50 characters

Date of order creation defined by the merchant.

customer_account_id
string <= 100 characters

Unique identifier for the customer as specified by the merchant.

customer_email
required
string <= 100 characters

Customer's email address.

customer_first_name
string <= 100 characters

Customer's first name.

customer_last_name
string <= 100 characters

Customer's last name.

customer_date_of_birth
string <date-time> <= 10 characters

Customer's date of birth.

customer_phone
string <= 50 characters

Customer's phone number.

Required for UGA, KEN, TZA, GHA locations.

item_category
string
Enum: "physical_goods" "digital_goods"

Type of goods.

Highly recommended to provide the shipping_address details for digital_goods.

object

Billing address details.

object

Address to ship.

If this field is passed by the merchant - the customer cannot change this address.

ip_address
required
string <= 50 characters

Public IP address of the cardholder, both IPv4 and IPv6 are supported.

Required for antifraud checks. For recurring payments, use the last session or registration IP.

Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error.

platform
required
string = 3 characters
Default: "WEB"
Enum: "APP" "WEB" "MOB"

Device platform used by the customer at the time of payment.

APP for application, WEB for desktop web, MOB for mobile web.

user_agent
string [ 1 .. 1000 ] characters

User-agent string of the device used by the customer.

The user-agent string offers comprehensive details about the web browser, its version, and the device's operating system, aiding in device identification for enhanced user experiences, analytics, and security.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

success_url
string <= 255 characters

URL for browser redirect after a successful payment.

fail_url
string <= 255 characters

URL for browser redirect after a failed payment.

return_url
string <= 255 characters

URL for browser redirect after a payment process.

Responses

Response Schema: application/json
One of
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

Order's structure may vary depending on the alternative payment method method used.

Array of objects

Details of transactions, including payment method, identifiers, amounts, currencies, statuses, and types.

Transaction's structure may vary depending on the alternative payment method method used.

object

Payment form data.

Including fields necessary for processing the payment.

object

Additional data that is required to make payments with the specific alternative payment methods.

This object is specifically for boleto payment.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

Request samples

Content type
application/json
Example
{
  • "payment_method": "paypal-vault",
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "amount": 1020,
  • "currency": "USD",
  • "order_description": "Premium package",
  • "order_date": "2015-12-21 11:21:30",
  • "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
  • "customer_email": "example@example.com",
  • "customer_first_name": "Nikola",
  • "customer_last_name": "Tesla",
  • "customer_date_of_birth": "1988-11-21",
  • "customer_phone": "+10111111111",
  • "item_category": "digital_goods",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "ip_address": "8.8.8.8",
  • "platform": "WEB",
  • "user_agent": "Mozilla/5.0",
  • "order_metadata": {
    },
  • "success_url": "http://merchant.example/success",
  • "fail_url": "http://merchant.example/fail",
  • "return_url": "http://merchant.example/success"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transactions": [
    ],
  • "pay_form": {},
  • "order_metadata": {
    }
}

Recurring

For alternative payment methods, a token-based recurring payment refers to an automatic billing applied to a customer's payment method at predetermined intervals.

This process involves securely storing a token representing the customer's payment details and using it for subsequent transactions without requiring input each time.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
One of
payment_method
required
string

Payment method name.

token
required
string

A secure payment token representing sensitive card or payment method information.

order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

amount
required
integer > 0

Order amount in the smallest currency unit supported by the alternative payment method.

For COP, CRC, HUF, LAK, RSD, and TWD, should pass the integer value of the amount with two zeros at the end (for example, XXXX00, which will be transferred as XXXX.00).

currency
required
string = 3 characters

Three-letter ISO-4217 currency code.

order_description
required
string <= 100 characters

Brief description of the order.

order_date
string <date-time> <= 50 characters

Date of order creation defined by the merchant.

customer_account_id
string <= 100 characters

Unique identifier for the customer as specified by the merchant.

customer_email
required
string <= 100 characters

Customer's email address.

customer_date_of_birth
string <date-time> <= 10 characters

Customer's date of birth.

ip_address
required
string <= 50 characters

Public IP address of the cardholder, both IPv4 and IPv6 are supported.

Required for antifraud checks. For recurring payments, use the last session or registration IP.

Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error.

platform
required
string = 3 characters
Default: "WEB"
Enum: "APP" "WEB" "MOB"

Device platform used by the customer at the time of payment.

APP for application, WEB for desktop web, MOB for mobile web.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

fail_url
string <= 255 characters
Deprecated

URL for browser redirect after a failed payment.

Responses

Response Schema: application/json
Any of
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

Array of objects

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

object

Payment form data.

Including fields necessary for processing the payment.

object

Additional data that is required to make payments with the specific alternative payment methods.

This object is specifically for boleto payment.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

Request samples

Content type
application/json
Example
{
  • "payment_method": "paypal-vault",
  • "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "amount": 1020,
  • "currency": "EUR",
  • "order_description": "Premium package",
  • "order_date": "2015-12-21 11:21:30",
  • "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
  • "customer_email": "example@example.com",
  • "customer_date_of_birth": "1988-11-21",
  • "ip_address": "8.8.8.8",
  • "platform": "WEB",
  • "order_metadata": {
    }
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transactions": [
    ],
  • "pay_form": {},
  • "payment_type_data": {},
  • "order_metadata": {
    }
}

Refund

Initiate a refund request to return funds for successfully processed orders.

It is important to note that, for instance, refunds might not be accessible or could be restricted when using alternative cash-based payment methods.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

amount
required
integer > 0

Order amount in the smallest currency unit supported by the alternative payment method.

refund_reason_code
string = 4 characters

Refund reason code.

This field is actively validated against the current list of reason codes. Deprecated codes will not be accepted.

Responses

Response Schema: application/json
Any of
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

Array of objects

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

object

Payment form data.

Including fields necessary for processing the payment.

object

Additional data that is required to make payments with the specific alternative payment methods.

This object is specifically for boleto payment.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

Request samples

Content type
application/json
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "amount": 1020,
  • "refund_reason_code": "0022"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "transactions": [
    ],
  • "pay_form": {},
  • "payment_type_data": {},
  • "order_metadata": {
    }
}

Check order status

Request for receiving current order status. The key benefit is that it enables merchants to efficiently monitor and manage their payments by providing comprehensive information about the order's status, payment method, transaction details, and customer information.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
order_id
required
string <= 255 characters

Order identifier defined by the merchant, which can be used later to find this payment.

Responses

Response Schema: application/json
Any of
object

Information about the order, including identifiers, timestamps, amounts, status, and customer details.

object

Error object.

Returned only in cases of declined statuses at the order, and fail status at transaction.

Array of objects

Information about a financial transaction made using a card, including unique identifiers, timestamps, amounts, currency, operation type, status, and other relevant details.

object

Payment form data.

Including fields necessary for processing the payment.

object

Additional data that is required to make payments with the specific alternative payment methods.

This object is specifically for boleto payment.

object <= 10 properties

Metadata is useful for storing additional, structured information about an object.

Request samples

Content type
application/json
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55"
}

Response samples

Content type
application/json
Example
{
  • "order": {
    },
  • "error": {
    },
  • "transactions": [
    ],
  • "pay_form": {},
  • "payment_type_data": {},
  • "order_metadata": {
    }
}

Products and prices

Solidgate API for billing management allows merchants to create and update products and pricing effectively, ensuring businesses can adapt to diverse customer needs and preferences.

Create a product

This method allows merchants to create new products by providing the required details.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
One of
name
required
string [ 1 .. 500 ] characters

Product name.

type
string
Default: "recurring"
Value: "one-time"

Specifies whether the product is a one-time purchase or a subscription product.

Once a product is created, its type cannot be changed.

description
required
string [ 1 .. 500 ] characters

Product description.

public_description
string [ 1 .. 100 ] characters

Product description for customers.

status
required
string
Enum: "disabled" "active"

Product status.

payment_action
required
string
Value: "auth_settle"

Payment processing flow applied to the transaction.

settle_interval
integer [ 0 .. 144 ]

Used in the auth_settle payment flow. The interval value for the payment action auth_settle is taken from this field.

profile_id (object) or category_id (object)

Contains product tax details.

Required to include either a tax profile_id or a tax category_id in the tax object.

If you pass a tax category_id in the tax object, profile_id and is_included do not affect tax calculation in the US.

Responses

Response Schema: application/json
One of
id
required
string <uuid> = 36 characters

Unique product identifier.

name
required
string [ 1 .. 500 ] characters

Product name.

type
required
string
Value: "one-time"

Specifies whether the product is a one-time purchase or a subscription product.

description
required
string [ 1 .. 500 ] characters

Product description.

public_description
string [ 1 .. 100 ] characters

Product description for customers.

status
required
string
Enum: "disabled" "active"

Product status.

Cannot be changed if a subscription exists for the product.

created_at
required
string <date-time>

Datetime of the product creation.

updated_at
required
string <date-time>

Datetime of the product update.

payment_action
required
string
Value: "auth_settle"

Payment processing flow applied to the transaction.

settle_interval
integer [ 0 .. 144 ]

Used in the auth_settle payment flow.

  • If the product has a trial, this field does not affect the first payments but influences recurring ones processed with auth_settle.
  • If there is no trial and the payment action is auth_settle, the interval value for the first payment is taken from this field.
profile_id (object) or category_id (object)

Contains product tax details.

Required to include either a tax profile_id or a tax category_id in the tax object.

If you pass a tax category_id in the tax object, profile_id and is_included do not affect tax calculation in the US.

Request samples

Content type
application/json
Example
{
  • "name": "Luxury product",
  • "type": "one-time",
  • "description": "This product is the best product all over the world",
  • "public_description": "That cool product which you have bought",
  • "status": "active",
  • "payment_action": "auth_settle",
  • "settle_interval": "48 - payment_action",
  • "tax": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "ac43b415-5522-4373-b026-a365462f9657",
  • "name": "Luxury product",
  • "type": "one-time",
  • "description": "This product is the best product all over the world",
  • "public_description": "That cool product that you have bought",
  • "status": "active",
  • "created_at": "2024-05-31 12:53:12",
  • "updated_at": "2024-05-31 12:53:13",
  • "payment_action": "auth_settle",
  • "settle_interval": 48,
  • "tax": {
    }
}

Get products list

By using this method, merchants can find products and retrieve their details by applying filters such as product identifier, status, trial availability, and sorting criteria, with pagination support.

query Parameters
filter[id]
string <= 100 characters
Example: filter[id]=ac43b415-5522-4373-b026-a365462f9657,xx33b415-5522-4373-b026-a365462f9657

Specify the comma-separated ids of products.

filter[status]
string
Enum: "active" "disabled"

Specify the desired status of products to be returned. Use active to retrieve active products and disabled to retrieve disabled products.

filter[has_trial]
boolean

Specify whether the products should have a trial available. Use true to retrieve products with a trial option.

pagination[limit]
integer [ 1 .. 100 ]
Default: 10
Example: pagination[limit]=10

Specify the number of items to return.

pagination[offset]
integer >= 0
Default: 0
Example: pagination[offset]=10

Specify the number of items to skip before starting to collect the result set.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Responses

Response Schema: application/json
One of
Array of objects

Contains an array of product data, each representing a specific price configuration.

object

Contains information about the pagination of the results.

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "pagination": {
    }
}

Update a product

This method allows merchants to update the existing product with specified details and retrieve the updated product information.

Note that for products with an active subscription, only a limited set of fields can be updated, while products without a subscription can have their information fully updated.

path Parameters
product_id
required
string <uuid> = 36 characters
Example: ac43b415-5522-4373-b026-a365462f9657

Unique product identifier.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
One of
name
string [ 1 .. 500 ] characters

Product name.

description
string [ 1 .. 500 ] characters

Product description.

public_description
string [ 1 .. 100 ] characters

Product description for customers.

To remove the public product description, set null.

status
string
Enum: "disabled" "active"

Product status.

payment_action
string
Value: "auth_settle"

Payment processing flow applied to the transaction.

settle_interval
integer [ 0 .. 144 ]

Used in the auth_settle payment flow. The interval value for the payment action auth_settle is taken from this field.

profile_id (object) or category_id (object)

Contains product tax details.

Required to include either a tax profile_id or a tax category_id in the tax object.

If you pass a tax category_id in the tax object, profile_id and is_included do not affect tax calculation in the US.

Responses

Response Schema: application/json
One of
id
required
string <uuid> = 36 characters

Unique product identifier.

name
required
string [ 1 .. 500 ] characters

Product name.

type
required
string
Value: "one-time"

Specifies whether the product is a one-time purchase or a subscription product.

description
required
string [ 1 .. 500 ] characters

Product description.

public_description
string [ 1 .. 100 ] characters

Product description for customers.

status
required
string
Enum: "disabled" "active"

Product status.

Cannot be changed if a subscription exists for the product.

created_at
required
string <date-time>

Datetime of the product creation.

updated_at
required
string <date-time>

Datetime of the product update.

payment_action
required
string
Value: "auth_settle"

Payment processing flow applied to the transaction.

settle_interval
integer [ 0 .. 144 ]

Used in the auth_settle payment flow.

  • If the product has a trial, this field does not affect the first payments but influences recurring ones processed with auth_settle.
  • If there is no trial and the payment action is auth_settle, the interval value for the first payment is taken from this field.
profile_id (object) or category_id (object)

Contains product tax details.

Required to include either a tax profile_id or a tax category_id in the tax object.

If you pass a tax category_id in the tax object, profile_id and is_included do not affect tax calculation in the US.

Request samples

Content type
application/json
Example
{
  • "name": "Luxury product",
  • "description": "This product is the best product all over the world",
  • "public_description": "That cool product which you have bought",
  • "status": "active",
  • "payment_action": "auth_settle",
  • "settle_interval": 48,
  • "tax": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "ac43b415-5522-4373-b026-a365462f9657",
  • "name": "Luxury product",
  • "type": "one-time",
  • "description": "This product is the best product all over the world",
  • "public_description": "That cool product that you have bought",
  • "status": "active",
  • "created_at": "2024-05-31 12:53:12",
  • "updated_at": "2024-05-31 12:53:13",
  • "payment_action": "auth_settle",
  • "settle_interval": 48,
  • "tax": {
    }
}

Get product by ID

This method allows merchants to obtain the existing product by its identifier.

path Parameters
product_id
required
string <uuid> = 36 characters
Example: ac43b415-5522-4373-b026-a365462f9657

Unique product identifier.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Responses

Response Schema: application/json
One of
id
required
string <uuid> = 36 characters

Unique product identifier.

name
required
string [ 1 .. 500 ] characters

Product name.

type
required
string
Value: "one-time"

Specifies whether the product is a one-time purchase or a subscription product.

description
required
string [ 1 .. 500 ] characters

Product description.

public_description
string [ 1 .. 100 ] characters

Product description for customers.

status
required
string
Enum: "disabled" "active"

Product status.

Cannot be changed if a subscription exists for the product.

created_at
required
string <date-time>

Datetime of the product creation.

updated_at
required
string <date-time>

Datetime of the product update.

payment_action
required
string
Value: "auth_settle"

Payment processing flow applied to the transaction.

settle_interval
integer [ 0 .. 144 ]

Used in the auth_settle payment flow.

  • If the product has a trial, this field does not affect the first payments but influences recurring ones processed with auth_settle.
  • If there is no trial and the payment action is auth_settle, the interval value for the first payment is taken from this field.
profile_id (object) or category_id (object)

Contains product tax details.

Required to include either a tax profile_id or a tax category_id in the tax object.

If you pass a tax category_id in the tax object, profile_id and is_included do not affect tax calculation in the US.

Response samples

Content type
application/json
Example
{
  • "id": "ac43b415-5522-4373-b026-a365462f9657",
  • "name": "Luxury product",
  • "type": "one-time",
  • "description": "This product is the best product all over the world",
  • "public_description": "That cool product that you have bought",
  • "status": "active",
  • "created_at": "2024-05-31 12:53:12",
  • "updated_at": "2024-05-31 12:53:13",
  • "payment_action": "auth_settle",
  • "settle_interval": 48,
  • "tax": {
    }
}

Create product price

By using this method, merchants can create a new product price with specified details and retrieve the created product price information.

path Parameters
product_id
required
string <uuid> = 36 characters
Example: ac43b415-5522-4373-b026-a365462f9657

Unique product identifier.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
default
required
boolean

Sets the specified price settings as the default.

status
required
string
Enum: "disabled" "active"

Product price status.

product_price
required
integer [ 1 .. 999999999 ]

Product price.

trial_price
integer [ 1 .. 999999999 ]

Trial price.

currency
required
string = 3 characters

Three-letter ISO-4217 currency code of the product price currency.

country
string <iso_code_a3> = 3 characters

Country code.

It is not available for the default price.

Responses

Response Schema: application/json
id
required
string <uuid>

Unique product price identifier.

default
required
boolean

Sets the specified price settings as the default.

status
required
string
Enum: "disabled" "active"

Product price status.

created_at
required
string <date-time>

Datetime of the product price creation.

updated_at
required
string <date-time>

Datetime of the product price update.

product_price
required
integer [ 1 .. 999999999 ]

Product price.

trial_price
integer [ 1 .. 999999999 ]

Trial price.

currency
required
string = 3 characters

Three-letter ISO-4217 currency code of the product price currency.

country
string <iso_code_a3> = 3 characters

Country code.

It is not available for the default price.

Request samples

Content type
application/json
{
  • "default": false,
  • "status": "active",
  • "product_price": 1000,
  • "trial_price": 500,
  • "currency": "USD",
  • "country": "USA"
}

Response samples

Content type
application/json
{
  • "id": "cb43b415-5522-4373-b026-a365462f9114",
  • "default": false,
  • "status": "active",
  • "created_at": "2024-05-31 12:53:12",
  • "updated_at": "2024-05-31 12:53:13",
  • "product_price": 1000,
  • "trial_price": 500,
  • "currency": "USD",
  • "country": "USA"
}

Get product prices

This method allows merchants to retrieve product prices based on the specified filter criteria and pagination settings, returning the results along with pagination information.

path Parameters
product_id
required
string <uuid> = 36 characters
Example: ac43b415-5522-4373-b026-a365462f9657

Unique product identifier.

query Parameters
filter[currency]
string
Example: filter[currency]=EUR, USD

Specify the comma-separated currencies.

filter[country]
string <iso_code_a3> = 3 characters
Example: filter[country]=USA

Specify the country code.

pagination[limit]
integer [ 1 .. 100 ]
Default: 10
Example: pagination[limit]=10

Specify the number of items to return.

pagination[offset]
integer >= 0
Default: 0
Example: pagination[offset]=10

Specify the number of items to skip before starting to collect the result set.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique Public Key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of request. It allows verifying whether the request from the merchant is genuine on the payment gateway server.

Responses

Response Schema: application/json
Array of objects

Contains an array of product data, each representing a specific price configuration.

object

Contains information about the pagination of the results.

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Update a price

By using this method, merchants can update the existing product price with the specified changes, providing the updated product price details.

Note that for products with an active subscription, only a limited set of fields can be updated, while products without a subscription can have their information fully updated.

path Parameters
product_id
required
string <uuid> = 36 characters
Example: ac43b415-5522-4373-b026-a365462f9657

Unique product identifier.

product_price_id
required
string <uuid>
Example: fa43b415-5522-4373-b026-a365562f9649

Unique product price identifier.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
status
string
Enum: "disabled" "active"

Product price status.

product_price
integer [ 1 .. 999999999 ]

Product price.

trial_price
integer [ 1 .. 999999999 ]

Trial price.

currency
string = 3 characters

Three-letter ISO-4217 currency code of the product price currency.

country
string <iso_code_a3> = 3 characters

Country code.

It is not available for the default price.

Responses

Response Schema: application/json
id
required
string <uuid>

Unique product price identifier.

default
required
boolean

Sets the specified price settings as the default.

status
required
string
Enum: "disabled" "active"

Product price status.

created_at
required
string <date-time>

Datetime of the product price creation.

updated_at
required
string <date-time>

Datetime of the product price update.

product_price
required
integer [ 1 .. 999999999 ]

Product price.

trial_price
integer [ 1 .. 999999999 ]

Trial price.

currency
required
string = 3 characters

Three-letter ISO-4217 currency code of the product price currency.

country
string <iso_code_a3> = 3 characters

Country code.

It is not available for the default price.

Request samples

Content type
application/json
{
  • "status": "active",
  • "product_price": 1000,
  • "trial_price": 500,
  • "currency": "USD",
  • "country": "USA"
}

Response samples

Content type
application/json
{
  • "id": "cb43b415-5522-4373-b026-a365462f9114",
  • "default": false,
  • "status": "active",
  • "created_at": "2024-05-31 12:53:12",
  • "updated_at": "2024-05-31 12:53:13",
  • "product_price": 1000,
  • "trial_price": 500,
  • "currency": "USD",
  • "country": "USA"
}

Calculate a product price

This method allows merchants to precalculate a product price for a specific location, which is particularly useful when a tax profile with the relevant tax rates is applied to a product.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
product_id
required
string <uuid> = 36 characters

Unique product identifier.

currency
string = 3 characters

Three-letter ISO-4217 currency code of the product price currency.

required
country (object) or ip_address (object)

Information about the cardholder's location, specified as either a country code or an IP address.

Responses

Response Schema: application/json
product_id
required
string <uuid> = 36 characters

Unique product identifier.

price_id
required
string <uuid> <= 36 characters

Unique product price identifier.

currency
required
string = 3 characters

Three-letter ISO-4217 currency code of the product price currency.

total_amount
required
integer

Payment total amount.

object

Information related to the tax calculation.

Request samples

Content type
application/json
{
  • "product_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
  • "currency": "USD",
  • "location": {
    }
}

Response samples

Content type
application/json
{
  • "product_id": "a51ba9fd-3be1-4ef9-b00f-bb85157597f5",
  • "price_id": "61b7f690-242a-498c-99a1-eb191f93f08c",
  • "currency": "USD",
  • "total_amount": 100,
  • "tax": {
    }
}

Taxes

Solidgate’s tax solution empowers businesses to manage and automate tax calculations across multiple regions efficiently. By integrating the tax solution, merchants can support accurate tax handling and compliance with local regulations.

Calculated tax Webhook

Webhooks provide merchants with instant notifications when the Solidgate tax solution calculates the tax amount of the transaction. These notifications allow merchants to notify users about paid taxes or to save tax information in real-time on the merchant’s side.

It delivers key tax details, such as calculated amounts and tax type breakdowns, ensuring accurate and automated tax application for transactions.

To prevent duplicated events, make your event processing idempotent. Log the event ID after processing, and skip any events already logged.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
order_id
string <= 255 characters

Order identifier defined by the merchant, which can be used to find the payment.

product_id
string <uuid> <= 36 characters

Unique product identifier.

Can be absent for payments without product_id.

total_amount
integer

Payment total amount in the smallest currency unit.

It is negative if the action is not sale, chargeback_reversed, or rdr_reversed.

currency
string = 3 characters

Currency used to initiate the payment by the merchant. Three-letter ISO-4217 currency code.

action
string
Enum: "sale" "refund" "chargeback" "rdr" "chargeback_reversed" … 2 more

Action of a transaction involving tax calculation.

For all action types except sale, chargeback_reversed, and rdr_reversed, the calculation amounts will be negative.

payment_category
string
Enum: "card-payment" "apm-payment"

Payment method used to process the payment.

transaction_date
string <date-time>

Datetime on which the payment was created.

tax_included
boolean

Indicates type of the tax.

object

Information related to the tax calculation.

It is absent if the tax calculation fails.

no_tax_reason
string

Reason for no tax calculated.

It is absent if the tax calculation is successful.

Responses

Request samples

Content type
application/json
{
  • "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "product_id": "1538344f-9e1a-4ad0-9a1e-7e6e4669775a",
  • "total_amount": 1000,
  • "currency": "USD",
  • "action": "sale",
  • "payment_category": "card-payment",
  • "transaction_date": "2024-12-06 15:18:40",
  • "tax_included": true,
  • "tax": {
    }
}

Manage subscriptions

Solidgate API for subscriptions empowers merchants in efficiently and securely managing subscriptions for a positive customer experience and business growth.

Merchants can easily handle their subscriptions using the available methods such as switching subscription products, pausing and resuming services, cancelling subscriptions, and providing customers with the option to update payment information.

Subscription status Webhook

Webhooks for subscription status empower merchants with real-time notifications in subscription status changes.

The webhook structure is similar to the subscription status method, with the addition of the callback_type parameter included in the response object.

There are legacy and extended versions of subscription events. The latest introduces an enhanced webhook event set with greater detail and context. It allows merchants to gain deeper insights into subscription stages, supporting improved management and analysis.

To prevent duplicated events, make your event processing idempotent. Log the event ID after processing, and skip any events already logged.

Parameters for each callback type can vary depending on factors such as the product, payment method, trial availability, and other specific conditions.

header Parameters
merchant
string
Example: wh_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

solidgate-event-id
string
Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Unique event identifier.

Request Body schema: application/json
One of
callback_type
required
string

Filled for subscription events.

View parameters specific to a particular callback type by choosing the relevant callback type.

required
object

Subscription details, including its status, payment method, and other essential information for tracking and managing its lifecycle.

required
object

Product details for a subscription, including information such as name, payment logic, amount, currency, trial details, and more.

The list of fields within the object differs from the field set during the creation of the product.

required
object

Customer details related to the subscription, including key information such as the customer's email address.

object

Invoice data, including subscription billing information, current state, financial details, and associated order history.

Responses

Request samples

Content type
application/json
Example
{
  • "callback_type": "create",
  • "subscription": {
    },
  • "product": {
    },
  • "customer": {
    },
  • "invoices": {
    }
}

Switch product

By using this method, the merchant can replace the product used in the active subscription with a new one. After executing the product switch request, a callback will be initiated to communicate the relevant update, incorporating the new product for the subscription. The revised product settings will come into effect following the subsequent debiting date.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
subscription_id
required
string <uuid> = 36 characters

Unique subscription identifier.

new_product_id
required
string <uuid> = 36 characters

Unique product identifier to apply to the specified subscription.

Responses

Request samples

Content type
application/json
{
  • "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
  • "new_product_id": "ac43b415-5522-4373-b026-a365462f9657"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Update subscription token

This method provides a mechanism for merchants to update the payment token when the customer's preferred payment method changes.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
subscription_id
required
string <uuid> = 36 characters

Unique subscription identifier.

token
required
string = 100 characters

A secure payment token representing sensitive card or payment method information.

Responses

Request samples

Content type
application/json
{
  • "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
  • "token": "uPrZ4lx6OFxDOC5wVeA0w5E2dBtDgCdGINo5jWPtxwQbsENzrFUIAUFT9rk7J0xWkpKj0NjVlEoa1ufu8fBIexEdyHFSNaPYQC7F"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Create subscription pause

By using this method, merchants can schedule a subscription pause, setting the specific start and end dates for the pause period.

path Parameters
subscription_id
required
string <uuid> = 36 characters
Example: 83b19018-cbc4-45f0-899a-dda84fd2705e

Unique subscription identifier.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
required
object

Defines the initial timestamp of the subscription pause period.

Depending on the type parameter, it may represent a specific date.

required
object

Defines the concluding timestamp of the subscription pause period.

Depending on the type parameter, it may represent a specific date.

Responses

Response Schema: application/json
id
required
string <uuid>

Unique subscription identifier.

status
required
string
Enum: "active" "paused"

Current subscription status.

  • active - the subscription is currently ongoing and charges are recurring
  • paused - the subscription is temporarily on hold and there are no charges
required
object

Contains the details of the subscription pause.

Request samples

Content type
application/json
{
  • "start_point": {
    },
  • "stop_point": {
    }
}

Response samples

Content type
application/json
{
  • "id": "bd43b415-4321-6275-c137-b365462f9645",
  • "status": "active",
  • "pause": {
    }
}

Update subscription pause

By using this method, merchants can modify the existing pause schedule, including the possibility of adjusting the start and end dates of the pause period.

Note that if the subscription pause is active, only its end date can be updated, while an inactive pause allows for updates to both start and end dates.

path Parameters
subscription_id
required
string <uuid> = 36 characters
Example: 83b19018-cbc4-45f0-899a-dda84fd2705e

Unique subscription identifier.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
object

Defines the initial timestamp of the subscription pause period.

Depending on the type parameter, it may represent a specific date.

object

Defines the concluding timestamp of the subscription pause period.

Depending on the type parameter, it may represent a specific date.

Responses

Response Schema: application/json
id
required
string <uuid>

Unique subscription identifier.

status
required
string
Enum: "active" "paused"

Current subscription status.

  • active - the subscription is currently ongoing and charges are recurring
  • paused - the subscription is temporarily on hold and there are no charges
required
object

Contains the details of the subscription pause.

Request samples

Content type
application/json
{
  • "start_point": {
    },
  • "stop_point": {
    }
}

Response samples

Content type
application/json
{
  • "id": "bd43b415-4321-6275-c137-b365462f9645",
  • "status": "active",
  • "pause": {
    }
}

Remove subscription pause

This method provides a way to delete the scheduled pause, reverting the subscription to its previous active state or as specified.

path Parameters
subscription_id
required
string <uuid> = 36 characters
Example: 83b19018-cbc4-45f0-899a-dda84fd2705e

Unique subscription identifier.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Responses

Response Schema: application/json
id
required
string <uuid>

Unique subscription identifier.

status
required
string
Enum: "active" "paused"

Current subscription status.

  • active - the subscription is currently ongoing and charges are recurring
  • paused - the subscription is temporarily on hold and there are no charges

Response samples

Content type
application/json
{
  • "id": "bd43b415-4321-6275-c137-b365462f9645",
  • "status": "active"
}

Cancel subscription

By using this method, merchants can cancel the specific subscription by its subscription identifier.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
subscription_id
required
string <uuid> = 36 characters

Unique subscription identifier.

force
boolean
Default: false

Controls cancellation timing.

  • true - cancels the subscription immediately
  • false - cancellation occurs at the end of the billing period
cancel_code
string
Enum: 8.01 8.02 8.03 8.04 8.05 … 10 more

Reason code that is used to cancel the subscription.

Responses

Request samples

Content type
application/json
{
  • "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
  • "force": false,
  • "cancel_code": "8.01"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Cancel subscriptions by customer

By using this method, the merchant can cancel all subscriptions for the specific customer.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
customer_account_id
required
string <= 100 characters

Customer identifier defined by the merchant.

force
boolean
Default: false

Controls cancellation timing.

  • true - cancels the subscription immediately
  • false - cancellation occurs at the end of the billing period
cancel_code
string
Enum: 8.01 8.02 8.03 8.04 8.05 … 10 more

Reason code that is used to cancel the subscription.

Responses

Request samples

Content type
application/json
{
  • "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
  • "force": false,
  • "cancel_code": "8.01"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Restore subscription

By using this method, merchants can restore the specific subscription of their customer in case it was cancelled.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
subscription_id
required
string <uuid> = 36 characters

Unique subscription identifier.

expired_at
string <date-time>

Datetime of subscription expiration.

Responses

Request samples

Content type
application/json
{
  • "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
  • "expired_at": "2025-12-25 0:00:00"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Retrieve subscription data

Solidgate API for accessing subscription information provides merchants with the ability to obtain precise and up-to-date details regarding customer subscriptions.

To get in-depth insights into customer subscriptions, use subscription report that is specifically designed to retrieve and combine all subscription-related data.

Subscription status

By using this method, merchants can retrieve subscription data by subscription identifier and obtain its details, such as the start date, status, and the information about the most recent invoice related to the subscription.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
subscription_id
required
string <uuid> = 36 characters

Unique subscription identifier.

Responses

Response Schema: application/json
required
object

Subscription details, including its status, payment method, and other essential information for tracking and managing its lifecycle.

required
object

Product details for a subscription, including information such as name, payment logic, amount, currency, trial details, and more.

The list of fields within the object differs from the field set during the creation of the product.

required
object

Customer details related to the subscription, including key information such as the customer's email address.

required
object

Map of invoices, containing details such as a subscription's billing overview, current state, financial information, and associated order history.

Request samples

Content type
application/json
{
  • "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e"
}

Response samples

Content type
application/json
{
  • "subscription": {
    },
  • "product": {
    },
  • "customer": {
    },
  • "invoices": {
    }
}

Retrieve subscriptions by customer

This method allows the merchant to retrieve all subscriptions and their statuses for the specific customer by the customer identifier.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
customer_account_id
required
string <= 100 characters

Customer identifier defined by the merchant.

Responses

Response Schema: application/json
object

Information about a specific subscription and its associated payment and customer data.

object

Information about a specific subscription and its associated payment and customer data.

Request samples

Content type
application/json
{
  • "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa"
}

Response samples

Content type
application/json
{
  • "<subscription_id_value_#1>": {
    },
  • "<subscription_id_value_#2>": {
    }
}

List invoices by subscription

By using this method, merchants can get a list of invoices related to a specific subscription.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
subscription_id
required
string <uuid> = 36 characters

Unique subscription identifier.

object

Contains information about the pagination of the results.

If either of the key-value pairs, offset or limit, is included in the object, both must be present. For the key-value pair that is not intended to be used, specify its default value.

Responses

Response Schema: application/json
required
Array of objects

List of invoices, each representing a billing event for a subscription.

required
object

Contains information about the pagination of the results.

Request samples

Content type
application/json
{
  • "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
  • "pagination": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

List orders by invoice

By using this method, merchants can retrieve a list of orders associated with a particular invoice.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
invoice_id
required
string <uuid> = 36 characters

Unique invoice identifier associated with a specific subscription.

object

Contains information about the pagination of the results.

If either of the key-value pairs, offset or limit, is included in the object, both must be present. For the key-value pair that is not intended to be used, specify its default value.

Responses

Response Schema: application/json
required
Array of objects

List of orders, each containing attributes like order identifier, status, type, amount, currency, and timestamps for creation and updates.

required
object

Contains information about the pagination of the results.

Request samples

Content type
application/json
{
  • "invoice_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
  • "pagination": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Fraud prevention

Solidgate API for fraud prevention enables merchants to set up and manage fraud prevention lists, helping tp block fraudulent activities while ensuring secure transactions.

By configuring fraud prevention lists, merchants can define specific conditions to allow or reject transactions, enhancing the security and reliability of their payment operations.

Create fraud prevention list items

This method allows you to add new items to fraud prevention list linked to the merchant's account.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
required
Array of objects <= 100 items

List of fraud prevention list items to be created.

Responses

Response Schema: application/json
Any of
required
Array of objects

List of created fraud prevention list items.

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "items": [
    ]
}

List fraud prevention list items

This method retrieves existing fraud prevention list items linked to the merchant's account.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
list_type
string
Enum: "pass" "reject"

Type of the list item.

object

Payment field and value to be checked.

limit
integer [ 1 .. 2000 ]
Default: 2000

Limit value indicates the maximum number of items to be returned.

next_page_iterator
string

Reference point for retrieving the next page of results

If this value is null, it indicates that all available data has been successfully retrieved by the merchant.

Responses

Response Schema: application/json
Any of
required
Array of objects

Fraud prevention list items.

required
object

Metadata object containing pagination and count information.

Request samples

Content type
application/json
{
  • "list_type": "pass",
  • "payment_field_value": {
    },
  • "limit": 2000,
  • "next_page_iterator": "1234567"
}

Response samples

Content type
application/json
Example
{
  • "items": [
    ],
  • "metadata": {
    }
}

Delete fraud prevention list item

This method allows you to delete an existing fraud prevention list item linked to the merchant's account.

path Parameters
id
required
string

Identifier of the fraud prevention list item to be deleted.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Responses

Response Schema: application/json
Any of
id
required
string <= 255 characters

Fraud prevention list item identifier.

list_type
required
string
Enum: "pass" "reject"

Type of the list item.

payment_field
required
string
Enum: "card_id" "cardholder" "customer_id" "customer_email" "ip_address"

Payment field to be checked.

required
card_id (string) or cardholder (string) or customer_id (string) or customer_email (string) or ip_address (string)

The value of the payment_field to be checked.

Depending on the value provided in payment_field, the corresponding validation rules will be enforced.

expired_at
string

Expiration date of the item.

If not provided, the item will never expire.

description
string <= 255 characters

Reason for creating the item.

Response samples

Content type
application/json
Example
{
  • "id": "1234567",
  • "list_type": "pass",
  • "payment_field": "card_id",
  • "field_value": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  • "expired_at": "2024-12-21 11:21:30",
  • "description": "This is a pass rule"
}

Payment page

Solidgate Payment Page allows merchants to securely redirect customers to a payment gateway's hosted page for completing transactions, without the need for custom integration on the merchant's website.

Create page

Please note that the payment page link expires in 24 hours.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
One of
required
object

Information required to create an order.

required
object

Information required to customize the payment page display.

Responses

Response Schema: application/json
Any of
url
required
string

Specific URL where the customer should be directed to complete their transaction.

guid
required
string

Uniquely identifies a payment session and ensures the security and integrity of the transaction.

Request samples

Content type
application/json
Example
{
  • "order": {
    },
  • "page_customization": {
    }
}

Response samples

Content type
application/json
Example
{}

Reports

Solidgate API for reports allows merchants to securely access transaction data and generate customized reports for analyzing and tracking the performance of their payment operations.

With Solidgate’s reconciliation functionality, merchants can track cash daily, identify fund flow gaps, gain complete transaction lifecycle visibility, implement strong financial controls, and establish scalable financial processes.

Solidgate data comes with a 60-minute delay, thus it is not recommended for real-time analysis.

Please note that reports may be inaccessible for about 30 minutes on Wednesdays at 5:00 PM (UTC) due to scheduled external maintenances. Once complete, all reports will be available with data preserved.

Card orders

The report provides essential data for merchants, including transaction details, customer information, and technical insights, facilitating comprehensive order tracking, financial reconciliation, and enhanced operational and marketing strategies.

This report uses the updated_at as the default parameter for unloading data, which reflects the latest update to card orders.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
filter
string
Default: "updated_at"
Enum: "updated_at" "created_at"

Filtering criteria for the report data.

date_from
required
string <date-time>

Start datetime for the report stated in UTC+0.

date_to
required
string <date-time>

End datetime for the report stated in UTC+0.

limit
integer [ 1 .. 2000 ]
Default: 2000

Limit value indicates the maximum number of items to be returned.

next_page_iterator
string

Pagination helps in managing large datasets by dividing them into smaller, manageable chunks.

If this value is null, it indicates that all available data has been successfully retrieved by the merchant.

Responses

Response Schema: application/json
Any of
required
Array of objects

List of orders, each containing attributes like order identifier, status, type, amount, currency, and timestamps for creation and updates.

required
object

Metadata object containing pagination and count information.

Request samples

Content type
application/json
{
  • "filter": "created_at",
  • "date_from": "2024-08-15 11:00:00",
  • "date_to": "2024-08-18 11:00:00",
  • "limit": 2000,
  • "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}

Response samples

Content type
application/json
Example
{
  • "orders": [
    ],
  • "metadata": {
    }
}

APM orders

The report is essential for merchants using alternative payment methods, offering comprehensive transaction details, including order IDs, statuses, amounts, customer information, crucial for a complete understanding of APM transaction dynamics.

This report uses the updated_at as the default parameter for unloading data, indicating the latest update to the APM orders.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
filter
string
Default: "updated_at"
Enum: "updated_at" "created_at"

Filtering criteria for the report data.

date_from
required
string <date-time>

Start datetime for the report stated in UTC+0.

date_to
required
string <date-time>

End datetime for the report stated in UTC+0.

limit
integer [ 1 .. 2000 ]
Default: 2000

Limit value indicates the maximum number of items to be returned.

next_page_iterator
string

Pagination helps in managing large datasets by dividing them into smaller, manageable chunks.

If this value is null, it indicates that all available data has been successfully retrieved by the merchant.

Responses

Response Schema: application/json
Any of
required
Array of objects

List of orders, each containing attributes like order identifier, status, type, amount, currency, and timestamps for creation and updates.

required
object

Metadata object containing pagination and count information.

Request samples

Content type
application/json
{
  • "filter": "created_at",
  • "date_from": "2024-08-15 11:00:00",
  • "date_to": "2024-08-18 11:00:00",
  • "limit": 2000,
  • "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}

Response samples

Content type
application/json
Example
{
  • "orders": [
    ],
  • "metadata": {
    }
}

Subscriptions

The report offers a comprehensive overview for merchants, detailing customer subscriptions, payment methods, key customer data, and associated invoices, which are important for managing recurring revenues, customer retention, and informed decision-making in subscription-based businesses.

The updated_at parameter is used when unloading subscription data, indicating the most recent update to a subscription.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
filter
string
Default: "updated_at"
Enum: "updated_at" "created_at"

Filtering criteria for the report data.

date_from
required
string <date-time>

Start datetime for the report stated in UTC+0.

date_to
required
string <date-time>

End datetime for the report stated in UTC+0.

limit
integer [ 1 .. 2000 ]
Default: 2000

Limit value indicates the maximum number of items to be returned.

next_page_iterator
string

Pagination helps in managing large datasets by dividing them into smaller, manageable chunks.

If this value is null, it indicates that all available data has been successfully retrieved by the merchant.

Responses

Response Schema: application/json
Any of
required
object

Map of subscriptions, including detailed information such as status, payment details, cancellation info, associated customer and product data, invoice history, and pause schedule parameters.

required
object

Contains metadata related to the request, particularly for pagination.

Request samples

Content type
application/json
{
  • "filter": "created_at",
  • "date_from": "2024-08-15 11:00:00",
  • "date_to": "2024-08-18 11:00:00",
  • "limit": 2000,
  • "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}

Response samples

Content type
application/json
Example
{
  • "subscriptions": {
    },
  • "metadata": {
    }
}

Chargebacks

The report is essential for merchants, providing exhaustive insights into each chargeback, including identifiers, dates, types, amounts, reasons, and related original order details, which is crucial for understanding chargeback patterns, enhancing dispute resolution, and fraud prevention.

Chargeback information is unloaded using the updated_at as the default parameter, which reflects the date when the latest chargeback flow was created.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
filter
string
Default: "updated_at"
Enum: "updated_at" "created_at"

Filtering criteria for the report data.

date_from
required
string <date-time>

Start datetime for the report stated in UTC+0.

date_to
required
string <date-time>

End datetime for the report stated in UTC+0.

limit
integer [ 1 .. 2000 ]
Default: 2000

Limit value indicates the maximum number of items to be returned.

next_page_iterator
string

Pagination helps in managing large datasets by dividing them into smaller, manageable chunks.

If this value is null, it indicates that all available data has been successfully retrieved by the merchant.

Responses

Response Schema: application/json
Any of
required
Array of objects

List of orders, each containing attributes like order identifier, status, type, amount, currency, and timestamps for creation and updates.

required
object

Metadata object containing pagination and count information.

Request samples

Content type
application/json
{
  • "filter": "created_at",
  • "date_from": "2024-08-15 11:00:00",
  • "date_to": "2024-08-18 11:00:00",
  • "limit": 2000,
  • "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}

Response samples

Content type
application/json
Example
{
  • "orders": [
    ],
  • "metadata": {
    }
}

PayPal disputes

The report is crucial, offering detailed insights on each PayPal dispute and lifecycle stage. These details are essential for effective dispute management and enhancing customer satisfaction.

This report uses the created_at as the default parameter for unloading data.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
filter
string
Default: "created_at"
Enum: "updated_at" "created_at"

Filtering criteria for the report data.

date_from
required
string <date-time>

Start datetime for the report stated in UTC+0.

date_to
required
string <date-time>

End datetime for the report stated in UTC+0.

limit
integer [ 1 .. 2000 ]
Default: 2000

Limit value indicates the maximum number of items to be returned.

next_page_iterator
string

Pagination helps in managing large datasets by dividing them into smaller, manageable chunks.

If this value is null, it indicates that all available data has been successfully retrieved by the merchant.

Responses

Response Schema: application/json
Any of
required
Array of objects

List of disputes, each containing attributes like identifiers, dates, amounts, currencies, stages, channels, reasons, and status.

required
object

Metadata object containing pagination and count information.

Request samples

Content type
application/json
{
  • "filter": "created_at",
  • "date_from": "2024-08-15 11:00:00",
  • "date_to": "2024-08-18 11:00:00",
  • "limit": 2000,
  • "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}

Response samples

Content type
application/json
Example
{
  • "disputes": [
    ],
  • "metadata": {
    }
}

Prevention alerts

The report retrieves data to identify and resolve potential issues, thereby preventing the generation of alerts.

This report uses the created_at as the default parameter for unloading data.

In successful response, you will receive a link to the file report_url

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
filter
string
Default: "created_at"
Enum: "updated_at" "created_at"

Filtering criteria for the report data.

date_from
required
string <date-time>

Start datetime for the report stated in UTC+0.

date_to
required
string <date-time>

End datetime for the report stated in UTC+0.

Responses

Response Schema: application/json
Any of
report_url
string

URL for the report stored on Amazon S3, which needs to be downloaded.

Request samples

Content type
application/json
{
  • "filter": "created_at",
  • "date_from": "2024-08-15 11:00:00",
  • "date_to": "2024-09-20 13:00:00"
}

Response samples

Content type
application/json
Example

Download prevention alerts

The report offering detailed information on prevention alerts. It provides insights into each alert, including unique identifiers, alert types, amounts, outcomes, and the alert generation timeline.

In success response, you will be redirected to S3, where the file download starts.

The report unloads data based on the date range parameters, which corresponds to the date the operation was executed.

path Parameters
report_id
required
string
Example: 2A1N0V1

Identifier of the report to download.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Responses

Response Schema: application/json
Any of
required
object

Error object.

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}

Card fraud alerts

The report is vital for merchants, providing detailed fraud-related information such as order IDs, amounts, and timings, along with specific fraud types and reason codes, crucial for swiftly identifying, analyzing, and formulating effective strategies to enhance transaction security.

The created_at as the default parameter is used to unload fraud alert data. It specifies the exact time when a fraud alert was created.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
filter
string
Default: "created_at"
Enum: "updated_at" "created_at"

Filtering criteria for the report data.

date_from
required
string <date-time>

Start datetime for the report stated in UTC+0.

date_to
required
string <date-time>

End datetime for the report stated in UTC+0.

limit
integer [ 1 .. 2000 ]
Default: 2000

Limit value indicates the maximum number of items to be returned.

next_page_iterator
string

Pagination helps in managing large datasets by dividing them into smaller, manageable chunks.

If this value is null, it indicates that all available data has been successfully retrieved by the merchant.

Responses

Response Schema: application/json
Any of
Array of objects

List of alerts, each containing detailed attributes such as order identifier, creation, update, and report dates, amounts in original currency and USD, fraud type, card scheme, and reason code description.

object

Metadata object containing pagination and count information.

Request samples

Content type
application/json
{
  • "filter": "created_at",
  • "date_from": "2024-08-15 11:00:00",
  • "date_to": "2024-08-18 11:00:00",
  • "limit": 2000,
  • "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}

Response samples

Content type
application/json
Example
{
  • "alerts": [
    ],
  • "metadata": {
    }
}

Financial entries by date range

In successful response, you will receive a link to the file report_url

The financial data are in a CSV file, which can be found at the link. Data is available for export from the July 2022.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
date_from
required
string <date-time>

Start datetime for the report stated in UTC+0.

date_to
required
string <date-time>

End datetime for the report stated in UTC+0.

Responses

Response Schema: application/json
Any of
report_url
string

URL for the report stored on Amazon S3, which needs to be downloaded.

Request samples

Content type
application/json
{
  • "date_from": "2024-08-15 11:00:00",
  • "date_to": "2024-09-20 13:00:00"
}

Response samples

Content type
application/json
Example

Financial entries by settlement

This operation is deprecated and will be removed from the API methods in the near future. Its functionality is coming soon in Settlements within Solidgate HUB, and you can switch to it to ensure uninterrupted access to financial data.

In a successful response, you receive a link report_url to download financial data as a CSV file. Data is available for export from July 2022.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Request Body schema: application/json
settlement_id
required
string <= 100 characters

Identifier of the settlement.

Responses

Response Schema: application/json
Any of
report_url
string

URL for the report stored on Amazon S3, which needs to be downloaded.

Request samples

Content type
application/json
{
  • "settlement_id": "2A1N0V1"
}

Response samples

Content type
application/json
Example

Download financial entries

The report offers an extensive overview of financial transactions, detailing financial record IDs, order and transaction IDs, dates, amounts, currencies, payment methods, and geographical data essential for comprehensive financial analysis and management.

In success response, you will be redirected to S3, where the file download starts.

The report unloads data based on the created_at + 2 days parameter, which corresponds to the date the operation was executed.

path Parameters
report_id
required
string
Example: 2A1N0V1

Identifier of the report to download.

header Parameters
merchant
string
Example: api_pk_7b197...ba108f842

Unique public key is provided upon registration and must be shared for identification purposes.

signature
string
Example: M2E3OTkyNzcz...xMmExODI4

Signature of the request, allowing verification of the request's authenticity from the merchant on the payment gateway server.

Responses

Response Schema: application/json
Any of
required
object

Error object.

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}

Changelog

The changelog documents all modifications, enhancements, and removals to the API. It helps developers and users to track changes, understand new features, and adjust their implementations.

It is equally important to be aware of updates in the broader payment guide changelog, which includes comprehensive details on product-level changes that may affect overall payment processing.

Changes to the Solidgate APIs are aimed at minimizing the impact on existing integrations. However, depending on the type of change, actions may be required.

Non-breaking changes

These modifications do not affect existing integrations and ensure backward compatibility:

  • New fields: Introduction of new, optional request fields or parameters in existing APIs.
  • Response modifications: Addition of new fields to API responses.
  • HTTP headers: Inclusion of new, optional HTTP request or response headers.
  • String length: Expansion of existing string field values.
  • Identifier format: Changes such as altering or removing prefixes from existing identifiers.
  • Webhook events: Addition of new webhook event types, which requires explicit opt-in.
  • Webhook schema: Inclusion of new fields in existing webhook event schemas.
  • Versioning: Older API versions remain supported for a set period, with advance notice for deprecation.
  • Rate limiting: Any modifications to rate limits will be communicated at least one month in advance.

Breaking changes

Breaking changes can impact existing integrations and require adjustments. These are marked with a breaking changes badge and include:

  • Operation removal: Removing an entire API operation.
  • Parameter modifications: Removing, renaming, or making an optional parameter required.
  • Response modifications: Removing or renaming a response field.
  • Type changes: Modifying the data type of a parameter or response field.
  • Enum updates: Removing existing enum values.
  • Validation rules: Adding new validation rules to an existing parameter.
  • Authentication and authorization: Changing authentication or authorization requirements.

19 March 2025

Added
product_id to the order object in the order status webhook and check order status response.

13 March 2025

Added cs Czech, sk Slovak language to the order object for the create page and create link requests.

11 March 2025

Added one-time product model of product requests and responses used to create, update, and retrieve product details.
one-time product model to card payment and APM requests for one-time purchase of goods or services.
category_id to the tax object in product endpoints for the US tax calculations.
customer_account_id to the order object in the order status webhook and check order status response.

07 March 2025

Added configuration: usage_mode for create link request.

06 March 2025

Added create, list and delete endpoints for manage fraud prevention lists.

05 March 2025 Breaking changes

Added pix as an alternative payment_method option in the init payment and recurring request.
Changed Breaking change ! payment_type_data validation from required to conditional depending on the blik direct / redirect flow for alternative payment_method in the init payment request.

26 February 2025

Added is_decrypted to the Google Pay request, which indicates whether the payload received from Google Pay was previously decrypted.

21 February 2025

Added psp_order_id and provider_payment_id to the order object in the order status webhook and check order status response.

19 February 2025

Added is_decrypted to the Apple Pay request, which indicates whether the payload received from Apple Pay was previously decrypted.

17 February 2025

Added auth_code to the order object in the order status event and responses of the card payments operations.

13 February 2025 Breaking changes

Deprecated financial entries by settlement endpoint, which provided a report with financial data by settlement.

06 February 2025 Breaking changes

Added payment_type, card_id, order_metadata and segment_id to the orders object in the card orders report.
Changed Breaking change ! type validation from optional to required in the create payment page and create payment link requests.

31 January 2025

Changed amount validation to support zero-amount flow for the recurring and resign request.

22 January 2025 Breaking changes

Changed ds_enrollment_response, authentification_response, and three_ds_flow fields in external_mpi_data object from optional to required in card payments endpoints.

10 January 2025

Added PayPal dispute webhook to deliver critical insights into its lifecycle.

27 December 2024

Added deactivate payment link request to prevent its further use.

Removed guid field from create payment link response and replaced it with the id.


24 December 2024

Added prevention alerts report to support proactive management of disputes and fraud prevention strategies.


18 December 2024

Deprecated the payer_details object from APMs response as it will no longer be expanded or guaranteed to provide consistent data.


12 December 2024

Added the calculated tax webhook for real-time updates on tax calculations.


09 December 2024

Changed option value to pix-qr for the PIX method as an alternative payment_method option in the init payment request.


06 December 2024

Added:

  • the ability to modify the product name field when updating a product
  • the segment_id field to the routing cascade_steps object in the card payments response

28 November 2024

Added the auth_0_amount type to the payment_action field for free product trials in the create a product and update a product endpoints.


27 November 2024

Added pix as an alternative payment_method option in the init payment request.


26 November 2024

Added the ability to modify trial settings by updating a product, which excludes adding or removing trials for active subscriptions.


20 November 2024

Added the flow field to the three_ds object in the check order status response and order status webhook.


19 November 2024

Added:

  • the dispute_outcome field to the PayPal disputes report response
  • the scof type for tokenization in the network token created and updated webhook

13 November 2024

Added the verification_result object to the check order status response and the order status webhook.


06 November 2024

Added the merchant object with the account_id field to the order object in the recurring and check order status responses, and the order status webhook.

22 October 2024

Added to product and price management:


11 October 2024

Added the pending and expired statuses and the extended version of subscription events.


01 October 2024

Removed sofort from alternative payment_method in the init payment request.

20 September 2024

Added the calculate product price endpoint for calculation of the product price.


12 September 2024

Added filtering filter criteria to the Subscriptions report.


10 September 2024

Added trial_started_at and trial_ended_at fields to the subscription object of the subscription status response.


03 September 2024

Removed bic field from alternative payment method ideal in the init payment request.

21 August 2024

Added filtering filter criteria to the APM orders and PayPal disputes reports.


20 August 2024

Added price_id to the product object of the subscription status response.


19 August 2024

Added immediate and infinite pause types for the subscription pause management.


06 August 2024

Added legal_entity field to the financial entries report.

31 July 2024

Added openbanking as an alternative payment_method option in the init payment request.


10 July 2024

Added id for fraud alert webhook to conveniently track updates.


09 July 2024

Removed giropay from alternative payment_method in the init payment request.


05 July 2024

Added filtering filter criteria to the chargebacks and card fraud alerts reports.

12 June 2024

Added to the card orders report:

  • filter field in request
  • mid to the orders object in response

13 May 2024

Added cashapp as an alternative payment_method option in the init payment request.

22 April 2024

Removed the deprecated verified field from all endpoints.


17 April 2024

Removed mpesa from alternative payment_method in the init payment request.