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
Solidgate offers a suite of APIs for processing and managing payments, supporting both direct use of HTTP/REST libraries and the use of our own 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/ |
Subscriptions | https://subscriptions.solidgate.com/api/v1/ |
Reports | https://reports.solidgate.com/api/v1/ |
Get started quickly by:
▶ Solidgate Postman CollectionThis collection offers example API requests to assist in understanding the effective use of our services.
For mass operations, it is advised to utilize requests with a reasonable rate limiter established (10-15 rps).
Great care is taken to ensure that changes to the Solidgate APIs do not impact existing integrations. Below are the types of changes considered to be backward-compatible:
When managing webhooks in Solidgate, addressing duplicate and non-ordered events is crucial:
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.
Solidgate API for card payments allows merchants to securely integrate with a payment gateway to process and manage card transactions.
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.
Occasionally you could receive the same event more than once. For example, it could happen while retrying notifications or when you request to resend some events. We advise you to guard against duplicated events by making your event processing idempotent. One way of doing this is logging the event ID you have processed and then not processing already-logged events.
We provide the event ID
in the request header params as described below.
merchant | string Example: wh_pk_7b197...ba108f842 A 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. |
solidgate-event-id | string Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1 The unique event identifier. |
object Object with order information. | |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object The transaction object. | |
object The map of transactions. The keys are transaction identifiers. | |
object Returns information related to the processing of the payment. | |
verify_url | string The URL where the customer should be redirected to complete 3DS authentication. |
object The map of chargebacks. The keys are chargeback identifiers. | |
object The device info object. | |
object Object with routing info.
| |
object Deprecated The payment adviser object. |
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "customer_email": "example.user@example-email.com",
- "payment_type": "1-click",
- "mid": "bank-mid-1",
- "descriptor": "google.com",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "refunded_amount": 0,
- "traffic_source": "facebook"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "transaction": {
- "descriptor": "google.com",
- "amount": 100,
- "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435"
}, - "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "processing",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "3.12",
- "messages": "Closed User Account",
- "merchant_advice_code": "21"
}
}, - "transactions": {
- "<transaction_id_value_#1>": {
- "descriptor": "google.com",
- "amount": 100,
- "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "country": "USA",
- "number": "444111XXXXXX9435"
}, - "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "processing",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "3.12",
- "messages": "Closed User Account",
- "merchant_advice_code": "21"
}
}
}, - "three_ds": {
- "eci": null
}, - "chargebacks": {
- "id": 148812,
- "dispute_date": "2022-07-11 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb",
- "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}, - "device_info": {
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
}, - "routing": {
- "cascade_steps": [
- {
- "mid": "mid-1",
- "mid_descriptor": "descriptor-1",
- "route_id": "pm-1",
- "cascade_number": 1
}
]
}
}
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.
merchant | string Example: wh_pk_7b197...ba108f842 A 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. |
solidgate-event-id | string Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1 The unique event identifier. |
card_id | string <uuid> The unique identifier of the card provided by merchant in payment request. |
tokenization_type | string Enum: "vts" "mdes" Type of tokenization associated with the card.
|
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. |
{- "card_id": "123e4567-e89b-12d3-a456-426614174000",
- "tokenization_type": "vts",
- "status": "INACTIVE",
- "created_at": "2023-08-17 11:45:30",
- "updated_at": "2023-08-17 11:45:30"
}
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.
merchant | string Example: wh_pk_7b197...ba108f842 A 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. |
solidgate-event-id | string Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1 The unique event identifier. |
card_id | string <uuid> The unique identifier of the card provided by merchant in payment request. |
tokenization_type | string Enum: "vts" "mdes" Type of tokenization associated with the card.
|
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. |
{- "card_id": "123e4567-e89b-12d3-a456-426614174000",
- "tokenization_type": "vts",
- "status": "INACTIVE",
- "created_at": "2023-08-17 11:45:30",
- "updated_at": "2023-08-17 11:45:30"
}
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.
Occasionally you could receive the same event more than once. For example, it could happen while retrying notifications or when you request to resend some events. We advise you to guard against duplicated events by making your event processing idempotent. One way of doing this is logging the event ID you have processed and then not processing already-logged events.
We provide the event ID
in the request header params as described below.
merchant | string Example: wh_pk_7b197...ba108f842 A 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. |
solidgate-event-id | string Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1 The unique event identifier. |
object The map of chargebacks. The keys are chargeback identifiers. | |
Array of objects The map of chargeback flows. The keys are chargeback flow identifiers. | |
object Object with order information. |
{- "chargeback": {
- "id": 148812,
- "dispute_date": "2022-07-11 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb"
}, - "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
], - "order": {
- "amount": 100,
- "currency": "USD",
- "order_id": "1672068260960AlexKhoRecurring11",
- "status": "processing"
}
}
Webhooks enable to preemptively identify and resolve potential issues, thereby preventing the generation of alert.
Occasionally you could receive the same event more than once. For example, it could happen while retrying notifications or when you request to resend some events. We advise you to guard against duplicated events by making your event processing idempotent. One way of doing this is logging the event ID you’ve processed and then not processing already-logged events.
We provide the event ID
in the request header params as described below.
merchant | string Example: wh_pk_7b197...ba108f842 A 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. |
solidgate-event-id | string Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1 The unique event identifier. |
object Object with chargeback alert information. | |
object Object with order information. |
{- "alert": {
- "id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "provider_name": "ethoca",
- "alert_date": "2019-11-25 11:01:03",
- "alert_type": "init-refund",
- "amount": 200,
- "currency": "EUR",
- "outcome": "reversed"
}, - "order": {
- "id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "amount": 100,
- "currency": "USD",
- "status": "processing",
- "created_at": "2022-12-27 11:45:30"
}
}
Webhooks for fraud alerts allow merchants to securely receive real-time notifications of fraud reported by card schemes.
Occasionally you could receive the same event more than once. For example, it could happen while retrying notifications or when you request to resend some events. We advise you to guard against duplicated events by making your event processing idempotent. One way of doing this is logging the event ID you have processed and then not processing already-logged events.
We provide the event ID
in the request header params as described below.
merchant | string Example: wh_pk_7b197...ba108f842 A 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. |
solidgate-event-id | string Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1 The unique event identifier. |
order_id | string <= 255 characters Order ID. |
fraud_amount | integer Fraud order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. |
fraud_currency | string Fraud order currency (3 letter code under ISO 4217). |
fraud_amount_usd | integer Fraud order amount in USD. |
fraud_type | string Type of fraud. |
fraud_report_day | string Day of the report of the fraud. |
card_scheme | string Card Scheme. |
reason_code_description | string Description of reason code. |
{- "order_id": "1672068260960AlexKhoRecurring11",
- "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"
}
Basic operation of funds withdrawal from cardholder’s account. This operation can be performed with additional cardholder verification via 3D Secure. When the operation is successfully finalized, cardholder data is tokenized so that the subsequent payments can be made via token (tokenized payment).
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
amount required | integer >= 0 Order amount in its smallest currency unit (cent for euro). For instance, 1020 means 10 EUR and 20 cents.
|
currency required | string = 3 characters The three-letter ISO currency code under ISO-4217. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
order_description required | string <= 255 characters A description of the order. |
order_items | string List and description of the items included in the order. |
order_date | string <= 50 characters yyyy-MM-dd HH:mm:ss Date of order creation defined by the merchant. |
order_number | integer The index number of order per customer. |
type | string Default: "auth" Enum: "auth" "charge" Whether to process this payment as authorization or charge. |
settle_interval | integer [ 0 .. 144 ] Delay applied before settlement of the transaction. Indicates the delay (in hours) before the settle.
Should be provided together with
|
payment_type required | string Enum: "1-click" "recurring" "retry" "installment" "rebill" The transaction 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.
The value must be required if |
scheme_transaction_id | string Card scheme specific transaction ID required for payments that use stored card details, such as recurring payments. For |
retry_attempt | integer >= 0 The number of retry attempts for the subscription payments. This parameter is used for analytics and conversion tuning purposes. |
force3ds | boolean Default: false Whether to process a payment as a 3D Secure payment.
|
object Required information to process a payment that has been 3DS authenticated using a third-party merchant plug-in (MPI). | |
customer_account_id | string <= 100 characters The customer ID defined by the merchant. |
customer_date_of_birth | string <= 10 characters yyyy-MM-dd The customer's date of birth. |
customer_email required | string <= 100 characters The customer's email address. |
customer_first_name | string <= 100 characters The customer's first name. |
customer_last_name | string <= 100 characters The customer's last name. |
customer_phone | string <= 18 characters The customer's phone number, including the country code. |
ip_address required | string <= 50 characters The public IP address of the cardholder. Required for antifraud checks. Both IPv4 and IPv6 are supported. For recurring payments, use the last session or registration IP.
|
traffic_source | string <= 255 characters This field could be used for traffic segmentation or analytical purposes. |
transaction_source | string <= 255 characters This field could be used for traffic segmentation or analytical purposes. |
purchase_country | string <iso_code_a3> = 3 characters The country where the goods are purchased or where the seller is based is identified using the ISO-3166 alpha-3 country code. If you are registered with international payment systems as a marketplace, this parameter is required. Being registered as a marketplace, in the context of international payment systems, typically implies that you operate a platform where numerous sellers can offer their goods or services. |
geo_country | string <iso_code_a3> = 3 characters Default: "GBR" The customer's registration country. |
geo_city | string <= 100 characters The customer's registration city. |
zip_code | string <= 10 characters The billing zip/postal code. |
state | string <= 10 characters The billing address state.
|
city | string <= 100 characters The billing address city. |
address | string <= 100 characters The first and second line of the billing address. |
object The address to ship.
| |
language | string = 2 characters Default: "en" Enum: "en" "fr" "es" "pt" "ja" … 5 more Customer language settings. |
website | string The website from which payment is originated. |
device | string <= 50 characters The name and model of the device. |
platform required | string = 3 characters Default: "WEB" Enum: "APP" "WEB" "MOB" Device Platform, which the customer used at the moment of payment. Available values:
|
header_accept | string Actual content of the
|
header_accept_language | string A string indicating the language of the browser. It is obtained from the client browser via the
|
browser_color_depth | integer The color depth of the customer browser during the payment.
|
browser_screen_height | integer The screen height of the customer browser during the payment.
|
browser_screen_width | integer The 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
|
time_zone_offset | integer The 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 The device user-agent.
|
card_number required | string [ 12 .. 19 ] characters 535572XXXXXX1833 The card number (without separators). |
card_holder | string [ 3 .. 50 ] characters ^[a-zA-Z]+ [a-zA-Z]+(?: [a-zA-Z]+)*$ The cardholder name as it appears on the card, which is essential for transaction processing.
|
card_exp_month required | string [0][1-9]$|^[1][0-2]$ The expiry month of the card. |
card_exp_year required | integer ^[2]\d{3}$ The expiry year of the card. |
card_cvv | string ^[0-9]{3,4}$ The card verification value/code (for card sources). 3 digits, except for Amex (4 digits). |
card_pin | string <= 10 characters The card PIN code. Required only for VERVE card brand. |
order_metadata | object 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. The full list of additional fields is provided in the guide of regional considerations. |
success_url | string <= 255 characters Allows you to set the URL for browser redirect after a successful 3D Secure or redirect payment method. |
fail_url | string <= 255 characters Allows you to set the URL for browser redirect after an unsuccessful 3D Secure or redirect payment method. |
verified | boolean Deprecated Default: false A user was verified on the shop side. |
fraudulent | boolean Deprecated Default: false Whether the customer is detected by the merchant system to be suspicious one. |
required | object Object with order information. |
object The device info object. | |
redirect_url | string The URL where customer should be redirected after finishing 3D Secure or redirect payment method. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object The transaction object. | |
required | object The map of transactions. The keys are transaction identifiers. |
object The map of chargebacks. The keys are chargeback identifiers. | |
object Returns information related to the processing of the payment. | |
object Object with routing info.
| |
object Deprecated The payment form object. | |
object Deprecated The payment adviser object. |
{- "amount": 1020,
- "currency": "EUR",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "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": {
- "three_ds_version": "2.2.0",
- "eci": "01",
- "cryptogram": "QURZRU4gM0RTMiBURVNUIENBVlY=",
- "ds_transaction_id": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
- "cryptogram_algorithm": "A",
- "three_ds_flow": "frictionless",
- "three_ds_server_transaction_id": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
- "ds_enrollment_response": "Y",
- "acs_challenge_mandated_ind": "Y",
- "transaction_challenge_exemption": "05",
- "authentification_response": "Y",
- "authentication_timestamp": "2023-12-05T12:00:00.000Z",
- "ds_transaction_reason": "01",
- "acs_transaction_id": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
- "authentication_method": [
- "02",
- "03"
], - "challenge_cancel_ind": "01"
}, - "customer_account_id": "4245d7b0-a84c-4623-91ff-e9de0254735b",
- "customer_date_of_birth": "1988-11-21",
- "customer_email": "test@solidgate.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",
- "shipping_address": {
- "country": "USA",
- "state": "NY",
- "city": "Boston",
- "address": "123 Main St",
- "zip": "91191"
}, - "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",
- "card_number": "535572XXXXXX1833",
- "card_holder": "John Snow",
- "card_exp_month": "12",
- "card_exp_year": 25,
- "card_cvv": "123",
- "card_pin": "4492",
- "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "payment_type_data": {
- "panama_id": "234234234234",
- "iban": "UA345678000987654"
},
}
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "customer_email": "example.user@example-email.com",
- "payment_type": "1-click",
- "mid": "bank-mid-1",
- "descriptor": "google.com",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "refunded_amount": 0,
- "traffic_source": "facebook"
}, - "device_info": {
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "transaction": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}, - "transactions": {
- "<transaction_id_value_#1>": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}
}, - "chargebacks": {
- "<chargeback_id_value_#1>": {
- "id": 12345,
- "dispute_date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb",
- "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}
}, - "three_ds": {
- "eci": null
}, - "routing": {
- "cascade_steps": [
- {
- "mid": "mid-1",
- "mid_descriptor": "descriptor-1",
- "route_id": "pm-1",
- "cascade_number": 1
}
]
}
}
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 ID, which will be processed, and the response will be sent back with the transaction details.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
amount required | integer > 0 Order amount in its smallest currency unit (cent for euro). For instance, 1020 means 10 EUR and 20 cents. |
currency required | string = 3 characters The three-letter ISO currency code under ISO-4217. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
order_description required | string <= 255 characters A description of the order. |
order_items | string List and description of the items included in the order. |
order_date | string <= 50 characters yyyy-MM-dd HH:mm:ss Date of order creation defined by the merchant. |
order_number | integer The index number of order per customer. |
type | string Default: "auth" Enum: "auth" "charge" Whether to process this payment as authorization or charge. |
settle_interval | integer [ 0 .. 144 ] Delay applied before settlement of the transaction. Indicates the delay (in hours) before the settle.
Should be provided together with
|
retry_attempt | integer >= 0 The number of retry attempts for the subscription payments. This parameter is used for analytics and conversion tuning purposes. |
force3ds | |
customer_account_id | string <= 100 characters The customer ID defined by the merchant. |
customer_date_of_birth | string <= 10 characters yyyy-MM-dd The customer's date of birth. |
customer_email required | string <= 100 characters The customer's email address. |
customer_first_name | string <= 100 characters The customer's first name. |
customer_last_name | string <= 100 characters The customer's last name. |
customer_phone | string <= 18 characters The customer's phone number, including the country code. |
ip_address required | string <= 50 characters The public IP address of the cardholder. Required for antifraud checks. Both IPv4 and IPv6 are supported. For recurring payments, use the last session or registration IP.
|
traffic_source | string <= 255 characters This field could be used for traffic segmentation or analytical purposes. |
transaction_source | string <= 255 characters This field could be used for traffic segmentation or analytical purposes. |
purchase_country | string <iso_code_a3> = 3 characters The country where the goods are purchased or where the seller is based is identified using the ISO-3166 alpha-3 country code. If you are registered with international payment systems as a marketplace, this parameter is required. Being registered as a marketplace, in the context of international payment systems, typically implies that you operate a platform where numerous sellers can offer their goods or services. |
geo_country | string <iso_code_a3> = 3 characters Default: "GBR" The customer's registration country. |
geo_city | string <= 100 characters The customer's registration city. |
zip_code | string <= 10 characters The billing zip/postal code. |
state | string <= 10 characters The billing address state.
|
city | string <= 100 characters The billing address city. |
address | string <= 100 characters The first and second line of the billing address. |
object The address to ship.
| |
language | string = 2 characters Default: "en" Enum: "en" "fr" "es" "pt" "ja" … 5 more Customer language settings. |
website | string The website from which payment is originated. |
device | string <= 50 characters The name and model of the device. |
platform required | string = 3 characters Default: "WEB" Enum: "APP" "WEB" "MOB" Device Platform, which the customer used at the moment of payment. Available values:
|
header_accept | string Actual content of the
|
header_accept_language | string A string indicating the language of the browser. It is obtained from the client browser via the
|
browser_color_depth | integer The color depth of The customer browser during the payment.
|
browser_screen_height | integer The screen height of The customer browser during the payment.
|
browser_screen_width | integer The 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
|
time_zone_offset | integer The 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 The device user-agent.
|
data | string Encrypted payment data. Base64 encoded as a string.
|
signature required | string Verifies the message that came from Google. The signature is created using ECDSA.
|
signedMessage required | string A serialized JSON string containing the encryptedMessage, ephemeralPublicKey, and tag. To simplify the signature verification process this value is serialized.
|
protocolVersion required | string Identifies which encryption/signing scheme created this message. In this way, the protocol can evolve over time if needed. If it is not set, assume ECv0.
|
version | string Version information about the payment token. The token uses
|
network | string The card brand. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
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. The full list of additional fields is provided in the guide of regional considerations. |
success_url | string <= 255 characters Allows you to set the URL for browser redirect after a successful 3D Secure or redirect payment method. |
fail_url | string <= 255 characters Allows you to set the URL for browser redirect after an unsuccessful 3D Secure or redirect payment method. |
verified | boolean Deprecated Default: false A user was verified on the shop side. |
fraudulent | boolean Deprecated Default: false Whether the customer is detected by the merchant system to be suspicious one. |
required | object Object with order information. |
object The device info object. | |
redirect_url | string The URL where customer should be redirected after finishing 3D Secure or redirect payment method. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object The transaction object. | |
required | object The map of transactions. The keys are transaction identifiers. |
object The map of chargebacks. The keys are chargeback identifiers. | |
object Returns information related to the processing of the payment. | |
object Object with routing info.
| |
object Deprecated The payment form object. | |
object Deprecated The payment adviser object. |
{- "amount": 1020,
- "currency": "EUR",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "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": "test@solidgate.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",
- "shipping_address": {
- "country": "USA",
- "state": "NY",
- "city": "Boston",
- "address": "123 Main St",
- "zip": "91191"
}, - "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": "MEQCIGJGG....0ZpM4YzvUA==",
- "signedMessage": "{\"\"\"\"encryptedMessage\"\"\"\":\"\"J......t1+Eu003d\"\"}",
- "protocolVersion": "ECv1",
- "version": "EC_v1",
- "network": "VISA",
- "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "header": {
- "transactionId": "7126df4ff8ac61dc60278b5cd549cc98d16b8f41",
- "applicationData": null,
- "ephemeralPublicKey": "MFkwEwY......+Dh2JDCwaKeLKXQ0cUM9ya/1wnrtMHXN4A==",
- "publicKeyHash": "mQaQhyhrXX3ZDSQv...ByX0iii0MVHthSQiXQ=",
- "wrappedKey": null
}, - "payment_type_data": {
- "panama_id": "234234234234",
- "iban": "UA345678000987654"
},
}
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "customer_email": "example.user@example-email.com",
- "payment_type": "1-click",
- "mid": "bank-mid-1",
- "descriptor": "google.com",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "refunded_amount": 0,
- "traffic_source": "facebook"
}, - "device_info": {
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "transaction": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}, - "transactions": {
- "<transaction_id_value_#1>": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}
}, - "chargebacks": {
- "<chargeback_id_value_#1>": {
- "id": 12345,
- "dispute_date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb",
- "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}
}, - "three_ds": {
- "eci": null
}, - "routing": {
- "cascade_steps": [
- {
- "mid": "mid-1",
- "mid_descriptor": "descriptor-1",
- "route_id": "pm-1",
- "cascade_number": 1
}
]
}
}
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 ID, which will be processed, and the response will be sent back with the transaction details.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
amount required | integer > 0 Order amount in its smallest currency unit (cent for euro). For instance, 1020 means 10 EUR and 20 cents. |
currency required | string = 3 characters The three-letter ISO currency code under ISO-4217. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
order_description required | string <= 255 characters A description of the order. |
order_items | string List and description of the items included in the order. |
order_date | string <= 50 characters yyyy-MM-dd HH:mm:ss Date of order creation defined by the merchant. |
order_number | integer The index number of order per customer. |
type | string Default: "auth" Enum: "auth" "charge" Whether to process this payment as authorization or charge. |
settle_interval | integer [ 0 .. 144 ] Delay applied before settlement of the transaction. Indicates the delay (in hours) before the settle.
Should be provided together with
|
retry_attempt | integer >= 0 The number of retry attempts for the subscription payments. This parameter is used for analytics and conversion tuning purposes. |
force3ds | |
customer_account_id | string <= 100 characters The customer ID defined by the merchant. |
customer_date_of_birth | string <= 10 characters yyyy-MM-dd The customer's date of birth. |
customer_email required | string <= 100 characters The customer's email address. |
customer_first_name | string <= 100 characters The customer's first name. |
customer_last_name | string <= 100 characters The customer's last name. |
customer_phone | string <= 18 characters The customer's phone number, including the country code. |
ip_address required | string <= 50 characters The public IP address of the cardholder. Required for antifraud checks. Both IPv4 and IPv6 are supported. For recurring payments, use the last session or registration IP.
|
traffic_source | string <= 255 characters This field could be used for traffic segmentation or analytical purposes. |
purchase_country | string <iso_code_a3> = 3 characters The country where the goods are purchased or where the seller is based is identified using the ISO-3166 alpha-3 country code. If you are registered with international payment systems as a marketplace, this parameter is required. Being registered as a marketplace, in the context of international payment systems, typically implies that you operate a platform where numerous sellers can offer their goods or services. |
geo_country | string <iso_code_a3> = 3 characters Default: "GBR" The customer's registration country. |
geo_city | string <= 100 characters The customer's registration city. |
zip_code | string <= 10 characters The billing zip/postal code. |
state | string <= 10 characters The billing address state.
|
city | string <= 100 characters The billing address city. |
address | string <= 100 characters The first and second line of the billing address. |
object The address to ship.
| |
language | string = 2 characters Default: "en" Enum: "en" "fr" "es" "pt" "ja" … 5 more Customer language settings. |
website | string The website from which payment is originated. |
device | string <= 50 characters The name and model of the device. |
platform required | string = 3 characters Default: "WEB" Enum: "APP" "WEB" "MOB" Device Platform, which the customer used at the moment of payment. Available values:
|
header_accept | string Actual content of the
|
header_accept_language | string This string indicates the language preference of the browser, obtained via the
|
browser_color_depth | integer The color depth of The customer browser during the payment.
|
browser_screen_height | integer The screen height of The customer browser during the payment.
|
browser_screen_width | integer The 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
|
time_zone_offset | integer The 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 The 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. |
protocolVersion | string Identifies which encryption/signing scheme created this message. In this way, the protocol can evolve over time if needed. If it is not set, assume ECv0. |
version required | string Version information about the payment token. The token uses |
network | string The card brand. |
order_metadata | object 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. The full list of additional fields is provided in the guide of regional considerations. |
success_url | string <= 255 characters Allows you to set the URL for browser redirect after a successful 3D Secure or redirect payment method. |
fail_url | string <= 255 characters Allows you to set the URL for browser redirect after an unsuccessful 3D Secure or redirect payment method. |
verified | boolean Deprecated Default: false A user was verified on the shop side. |
fraudulent | boolean Deprecated Default: false Whether the customer is detected by the merchant system to be suspicious one. |
required | object Object with order information. |
object The device info object. | |
redirect_url | string The URL where customer should be redirected after finishing 3D Secure or redirect payment method. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object The transaction object. | |
required | object The map of transactions. The keys are transaction identifiers. |
object The map of chargebacks. The keys are chargeback identifiers. | |
object Returns information related to the processing of the payment. | |
object Object with routing info.
| |
object Deprecated The payment form object. | |
object Deprecated The payment adviser object. |
{- "amount": 1020,
- "currency": "EUR",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "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": "test@solidgate.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": {
- "country": "USA",
- "state": "NY",
- "city": "Boston",
- "address": "123 Main St",
- "zip": "91191"
}, - "language": "en",
- "website": "merchant.example",
- "platform": "WEB",
- "device": "iPhone 8 iOS 12.0",
- "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",
- "protocolVersion": "ECv1",
- "version": "EC_v1",
- "network": "VISA",
- "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "header": {
- "transactionId": "7126df4ff8ac61dc60278b5cd549cc98d16b8f41",
- "applicationData": null,
- "ephemeralPublicKey": "MFkwEwY......+Dh2JDCwaKeLKXQ0cUM9ya/1wnrtMHXN4A==",
- "publicKeyHash": "mQaQhyhrXX3ZDSQv...ByX0iii0MVHthSQiXQ=",
- "wrappedKey": null
}, - "payment_type_data": {
- "panama_id": "234234234234",
- "iban": "UA345678080987654"
},
}
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "customer_email": "example.user@example-email.com",
- "payment_type": "1-click",
- "mid": "bank-mid-1",
- "descriptor": "google.com",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "refunded_amount": 0,
- "traffic_source": "facebook"
}, - "device_info": {
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "transaction": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}, - "transactions": {
- "<transaction_id_value_#1>": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}
}, - "chargebacks": {
- "<chargeback_id_value_#1>": {
- "id": 12345,
- "dispute_date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb",
- "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}
}, - "three_ds": {
- "eci": null
}, - "routing": {
- "cascade_steps": [
- {
- "mid": "mid-1",
- "mid_descriptor": "descriptor-1",
- "route_id": "pm-1",
- "cascade_number": 1
}
]
}
}
Method that allows you to initiate tokenized payments. In contrast to Charge, token previously received has to be sent in the request instead of cardholder data.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
amount required | integer > 0 Order amount in its smallest currency unit (cent for euro). For instance, 1020 means 10 EUR and 20 cents. |
currency required | string = 3 characters The three-letter ISO currency code under ISO-4217. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
order_description required | string <= 255 characters A description of the order. |
order_items | string List and description of the items included in the order. |
order_date | string <= 50 characters yyyy-MM-dd HH:mm:ss Date of order creation defined by the merchant. |
order_number | integer The index number of order per customer. |
type | string Default: "auth" Enum: "auth" "charge" Whether to process this payment as authorization or charge. |
settle_interval | integer [ 0 .. 144 ] Delay applied before settlement of the transaction. Indicates the delay (in hours) before the settle.
Should be provided together with
|
payment_type required | string Enum: "1-click" "recurring" "retry" "installment" "rebill" The transaction 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.
The value must be required if |
recurring_token required | string Token associated with a card method that could be used for the subsequent payments. |
retry_attempt | integer >= 0 The number of retry attempts for the subscription payments. This parameter is used for analytics and conversion tuning purposes. |
force3ds | boolean Default: false Whether to process a payment as a 3D Secure payment.
|
object Required information to process a payment that has been 3DS authenticated using a third-party merchant plug-in (MPI). | |
customer_account_id | string <= 100 characters The customer ID defined by the merchant. |
customer_date_of_birth | string <= 10 characters yyyy-MM-dd The customer's date of birth. |
customer_email required | string <= 100 characters The customer's email address. |
customer_first_name | string <= 100 characters The customer's first name. |
customer_last_name | string <= 100 characters The customer's last name. |
customer_phone | string <= 18 characters The customer's phone number, including the country code. |
ip_address required | string <= 50 characters The public IP address of the cardholder. Required for antifraud checks. Both IPv4 and IPv6 are supported. For recurring payments, use the last session or registration IP.
|
traffic_source | string <= 255 characters This field could be used for traffic segmentation or analytical purposes. |
transaction_source | string <= 255 characters This field could be used for traffic segmentation or analytical purposes. |
purchase_country | string <iso_code_a3> = 3 characters The country where the goods are purchased or where the seller is based is identified using the ISO-3166 alpha-3 country code. If you are registered with international payment systems as a marketplace, this parameter is required. Being registered as a marketplace, in the context of international payment systems, typically implies that you operate a platform where numerous sellers can offer their goods or services. |
geo_country | string <iso_code_a3> = 3 characters Default: "GBR" The customer's registration country. |
geo_city | string <= 100 characters The customer's registration city. |
zip_code | string <= 10 characters The billing zip/postal code. |
state | string <= 10 characters The billing address state.
|
city | string <= 100 characters The billing address city. |
address | string <= 100 characters The 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 The website from which payment is originated. |
device | string <= 50 characters The name and model of the device. |
platform required | string = 3 characters Default: "WEB" Enum: "APP" "WEB" "MOB" Device Platform, which the customer used at the moment of payment. Available values:
|
header_accept | string Actual content of the
|
header_accept_language | string A string indicating the language of the browser. It is obtained from the client browser via the
|
browser_color_depth | integer The color depth of the customer browser during the payment.
|
browser_screen_height | integer The screen height of the customer browser during the payment.
|
browser_screen_width | integer The 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
|
time_zone_offset | integer The 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 The device user-agent.
|
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
success_url | string <= 255 characters Allows you to set the URL for browser redirect after a successful 3D Secure or redirect payment method. |
fail_url | string <= 255 characters Allows you to set the URL for browser redirect after an unsuccessful 3D Secure or redirect payment method. |
verified | boolean Deprecated Default: false A user was verified on the shop side. |
fraudulent | boolean Deprecated Default: false Whether the customer is detected by the merchant system to be suspicious one. |
required | object Object with order information. |
object The device info object. | |
redirect_url | string The URL where customer should be redirected after finishing 3D Secure or redirect payment method. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object The transaction object. | |
required | object The map of transactions. The keys are transaction identifiers. |
object The map of chargebacks. The keys are chargeback identifiers. | |
object Returns information related to the processing of the payment. | |
object Deprecated The payment form object. | |
object Deprecated The payment adviser object. |
{- "amount": 1020,
- "currency": "EUR",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "order_items": "item 1 x 10, item 2 x 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": {
- "three_ds_version": "2.2.0",
- "eci": "01",
- "cryptogram": "QURZRU4gM0RTMiBURVNUIENBVlY=",
- "ds_transaction_id": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
- "cryptogram_algorithm": "A",
- "three_ds_flow": "frictionless",
- "three_ds_server_transaction_id": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
- "ds_enrollment_response": "Y",
- "acs_challenge_mandated_ind": "Y",
- "transaction_challenge_exemption": "05",
- "authentification_response": "Y",
- "authentication_timestamp": "2023-12-05T12:00:00.000Z",
- "ds_transaction_reason": "01",
- "acs_transaction_id": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
- "authentication_method": [
- "02",
- "03"
], - "challenge_cancel_ind": "01"
}, - "customer_account_id": "4245d7b0-a84c-4623-91ff-e9de0254735b",
- "customer_date_of_birth": "1988-11-21",
- "customer_email": "test@solidgate.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": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
},
}
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "customer_email": "example.user@example-email.com",
- "payment_type": "1-click",
- "mid": "bank-mid-1",
- "descriptor": "google.com",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "refunded_amount": 0,
- "traffic_source": "facebook"
}, - "device_info": {
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "transaction": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}, - "transactions": {
- "<transaction_id_value_#1>": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}
}, - "chargebacks": {
- "<chargeback_id_value_#1>": {
- "id": 12345,
- "dispute_date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb",
- "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}
}, - "three_ds": {
- "eci": null
}
}
Resign one-click enables token-based transactions (one-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 100 attempts.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
amount required | integer > 0 Order amount in its smallest currency unit (cent for euro). For instance, 1020 means 10 EUR and 20 cents. |
currency required | string = 3 characters The three-letter ISO currency code under ISO-4217. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
order_description required | string <= 255 characters A description of the order. |
order_items | string List and description of the items included in the order. |
order_date | string <= 50 characters yyyy-MM-dd HH:mm:ss Date of order creation defined by the merchant. |
order_number | integer The index number of order per customer. |
type | string Default: "auth" Enum: "auth" "charge" Whether to process this payment as authorization or charge. |
settle_interval | integer [ 0 .. 144 ] Delay applied before settlement of the transaction. Indicates the delay (in hours) before the settle.
Should be provided together with
|
recurring_token required | string Token associated with a card method that could be used for the subsequent payments. |
retry_attempt | integer >= 0 The number of retry attempts for the subscription payments. This parameter is used for analytics and conversion tuning purposes. |
force3ds | boolean Default: false Whether to process a payment as a 3D Secure payment.
|
object Required information to process a payment that has been 3DS authenticated using a third-party merchant plug-in (MPI). | |
customer_account_id | string <= 100 characters The customer ID defined by the merchant. |
customer_date_of_birth | string <= 10 characters yyyy-MM-dd The customer's date of birth. |
customer_email required | string <= 100 characters The customer's email address. |
customer_first_name | string <= 100 characters The customer's first name. |
customer_last_name | string <= 100 characters The customer's last name. |
customer_phone | string <= 18 characters The customer's phone number, including the country code. |
ip_address required | string <= 50 characters The public IP address of the cardholder. Required for antifraud checks. Both IPv4 and IPv6 are supported. For recurring payments, use the last session or registration IP.
|
traffic_source | string <= 255 characters This field could be used for traffic segmentation or analytical purposes. |
transaction_source | string <= 255 characters This field could be used for traffic segmentation or analytical purposes. |
purchase_country | string <iso_code_a3> = 3 characters The country where the goods are purchased or where the seller is based is identified using the ISO-3166 alpha-3 country code. If you are registered with international payment systems as a marketplace, this parameter is required. Being registered as a marketplace, in the context of international payment systems, typically implies that you operate a platform where numerous sellers can offer their goods or services. |
geo_country | string <iso_code_a3> = 3 characters Default: "GBR" The customer's registration country. |
geo_city | string <= 100 characters The customer's registration city. |
language | string = 2 characters Default: "en" Enum: "en" "fr" "es" "pt" "ja" … 5 more Customer language settings. |
website | string The website from which payment is originated. |
device | string <= 50 characters The name and model of the device. |
platform required | string = 3 characters Default: "WEB" Enum: "APP" "WEB" "MOB" Device Platform, which the customer used at the moment of payment. Available values:
|
header_accept | string Actual content of the
|
header_accept_language | string A string indicating the language of the browser. It is obtained from the client browser via the
|
browser_color_depth | integer The color depth of The customer browser during the payment.
|
browser_screen_height | integer The screen height of The customer browser during the payment.
|
browser_screen_width | integer The 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
|
time_zone_offset | integer The 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 The device user-agent.
|
card_cvv | string ^[0-9]{3,4}$ The card verification value/code (for card sources). 3 digits, except for Amex (4 digits). |
zip_code | string <= 10 characters The billing zip/postal code. |
state | string <= 10 characters The billing address state.
|
city | string <= 100 characters The billing address city. |
address | string <= 100 characters The first and second line of the billing address. |
order_metadata | object 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. The full list of additional fields is provided in the guide of regional considerations. |
success_url | string <= 255 characters Allows you to set the URL for browser redirect after a successful 3D Secure or redirect payment method. |
fail_url | string <= 255 characters Allows you to set the URL for browser redirect after an unsuccessful 3D Secure or redirect payment method. |
verified | boolean Deprecated Default: false A user was verified on the shop side. |
fraudulent | boolean Deprecated Default: false Whether the customer is detected by the merchant system to be suspicious one. |
required | object Object with order information. |
object The device info object. | |
redirect_url | string The URL where customer should be redirected after finishing 3D Secure or redirect payment method. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object The transaction object. | |
required | object The map of transactions. The keys are transaction identifiers. |
object The map of chargebacks. The keys are chargeback identifiers. | |
object Returns information related to the processing of the payment. | |
object Object with routing info.
| |
object Deprecated The payment form object. | |
object Deprecated The payment adviser object. |
{- "amount": 1020,
- "currency": "EUR",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "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": {
- "three_ds_version": "2.2.0",
- "eci": "01",
- "cryptogram": "QURZRU4gM0RTMiBURVNUIENBVlY=",
- "ds_transaction_id": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
- "cryptogram_algorithm": "A",
- "three_ds_flow": "frictionless",
- "three_ds_server_transaction_id": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
- "ds_enrollment_response": "Y",
- "acs_challenge_mandated_ind": "Y",
- "transaction_challenge_exemption": "05",
- "authentification_response": "Y",
- "authentication_timestamp": "2023-12-05T12:00:00.000Z",
- "ds_transaction_reason": "01",
- "acs_transaction_id": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
- "authentication_method": [
- "02",
- "03"
], - "challenge_cancel_ind": "01"
}, - "customer_account_id": "4245d7b0-a84c-4623-91ff-e9de0254735b",
- "customer_date_of_birth": "1988-11-21",
- "customer_email": "test@solidgate.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",
- "card_cvv": "123",
- "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "payment_type_data": {
- "panama_id": "234234234234",
- "iban": "UA345678000987654"
},
}
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "customer_email": "example.user@example-email.com",
- "payment_type": "1-click",
- "mid": "bank-mid-1",
- "descriptor": "google.com",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "refunded_amount": 0,
- "traffic_source": "facebook"
}, - "device_info": {
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "transaction": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}, - "transactions": {
- "<transaction_id_value_#1>": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}
}, - "chargebacks": {
- "<chargeback_id_value_#1>": {
- "id": 12345,
- "dispute_date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb",
- "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}
}, - "three_ds": {
- "eci": null
}, - "routing": {
- "cascade_steps": [
- {
- "mid": "mid-1",
- "mid_descriptor": "descriptor-1",
- "route_id": "pm-1",
- "cascade_number": 1
}
]
}
}
Request for transferring funds back to the cardholder. Refunds can be made only for approved 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 100 attempts.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
amount required | integer > 0 Order amount in its smallest currency unit (cent for euro). For instance, 1020 means 10 EUR and 20 cents. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
refund_reason_code | string = 4 characters Refund reason - a 4-digit code specified in the refund reason list.
|
required | object Object with order information. |
object The device info object. | |
redirect_url | string The URL where customer should be redirected after finishing 3D Secure or redirect payment method. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object The transaction object. | |
required | object The map of transactions. The keys are transaction identifiers. |
object The map of chargebacks. The keys are chargeback identifiers. | |
object Returns information related to the processing of the payment. | |
object Object with routing info.
| |
object Deprecated The payment form object. | |
object Deprecated The payment adviser object. |
{- "amount": 1020,
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "refund_reason_code": "0022"
}
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "customer_email": "example.user@example-email.com",
- "payment_type": "1-click",
- "mid": "bank-mid-1",
- "descriptor": "google.com",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "refunded_amount": 0,
- "traffic_source": "facebook"
}, - "device_info": {
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "transaction": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}, - "transactions": {
- "<transaction_id_value_#1>": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}
}, - "chargebacks": {
- "<chargeback_id_value_#1>": {
- "id": 12345,
- "dispute_date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb",
- "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}
}, - "three_ds": {
- "eci": null
}, - "routing": {
- "cascade_steps": [
- {
- "mid": "mid-1",
- "mid_descriptor": "descriptor-1",
- "route_id": "pm-1",
- "cascade_number": 1
}
]
}
}
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 100 attempts.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
required | object Object with order information. |
object The device info object. | |
redirect_url | string The URL where customer should be redirected after finishing 3D Secure or redirect payment method. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object The transaction object. | |
required | object The map of transactions. The keys are transaction identifiers. |
object The map of chargebacks. The keys are chargeback identifiers. | |
object Returns information related to the processing of the payment. | |
object Object with routing info.
| |
object Deprecated The payment form object. | |
object Deprecated The payment adviser object. |
{- "order_id": "wd4SUp"
}
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "customer_email": "example.user@example-email.com",
- "payment_type": "1-click",
- "mid": "bank-mid-1",
- "descriptor": "google.com",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "refunded_amount": 0,
- "traffic_source": "facebook"
}, - "device_info": {
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "transaction": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}, - "transactions": {
- "<transaction_id_value_#1>": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}
}, - "chargebacks": {
- "<chargeback_id_value_#1>": {
- "id": 12345,
- "dispute_date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb",
- "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}
}, - "three_ds": {
- "eci": null
}, - "routing": {
- "cascade_steps": [
- {
- "mid": "mid-1",
- "mid_descriptor": "descriptor-1",
- "route_id": "pm-1",
- "cascade_number": 1
}
]
}
}
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 100 attempts.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
amount required | integer > 0 Order amount in its smallest currency unit (cent for euro). For instance, 1020 means 10 EUR and 20 cents. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
required | object Object with order information. |
object The device info object. | |
redirect_url | string The URL where customer should be redirected after finishing 3D Secure or redirect payment method. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object The transaction object. | |
required | object The map of transactions. The keys are transaction identifiers. |
object The map of chargebacks. The keys are chargeback identifiers. | |
object Returns information related to the processing of the payment. | |
object Object with routing info.
| |
object Deprecated The payment form object. | |
object Deprecated The payment adviser object. |
{- "amount": 1020,
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55"
}
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "customer_email": "example.user@example-email.com",
- "payment_type": "1-click",
- "mid": "bank-mid-1",
- "descriptor": "google.com",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "refunded_amount": 0,
- "traffic_source": "facebook"
}, - "device_info": {
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "transaction": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}, - "transactions": {
- "<transaction_id_value_#1>": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}
}, - "chargebacks": {
- "<chargeback_id_value_#1>": {
- "id": 12345,
- "dispute_date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb",
- "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}
}, - "three_ds": {
- "eci": null
}, - "routing": {
- "cascade_steps": [
- {
- "mid": "mid-1",
- "mid_descriptor": "descriptor-1",
- "route_id": "pm-1",
- "cascade_number": 1
}
]
}
}
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
.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
required | object Object with order information. |
object The device info object. | |
redirect_url | string The URL where customer should be redirected after finishing 3D Secure or redirect payment method. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
required | object The map of transactions. The keys are transaction identifiers. |
object The map of chargebacks. The keys are chargeback identifiers. | |
object Returns information related to the processing of the payment. | |
object Object with routing info.
| |
object Deprecated The payment form object. | |
object Deprecated The payment adviser object. |
{- "order_id": "wd4SUp"
}
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "customer_email": "example.user@example-email.com",
- "payment_type": "1-click",
- "mid": "bank-mid-1",
- "descriptor": "google.com",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "refunded_amount": 0,
- "traffic_source": "facebook"
}, - "device_info": {
- "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "transactions": {
- "<transaction_id_value_#1>": {
- "descriptor": "google.com",
- "amount": 100,
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
- "country": "USA",
- "number": "444111XXXXXX9435",
- "card_token": {
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}
}, - "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "created",
- "updated_at": "2022-12-28 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "marketing_amount": 0,
- "marketing_currency": "USD",
- "billing_details": {
- "address": "21 Bedford Ave",
- "city": "Boston",
- "country": "USA",
- "state": "NY",
- "zip": "91191"
}, - "error": {
- "code": "2.01",
- "messages": [
- "Invalid Data"
], - "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
- "merchant_advice_code": "30"
}
}
}, - "chargebacks": {
- "<chargeback_id_value_#1>": {
- "id": 12345,
- "dispute_date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-11 00:00:00",
- "amount": 100,
- "currency": "USD",
- "reason_code": "10.4",
- "status": "reversed",
- "reason_group": "Fraud",
- "reason_description": "Fraud – Card-Absent Environment",
- "type": "2nd_chb",
- "chargeback_flow": [
- {
- "id": 12345,
- "amount": 100,
- "dispute_amount": 0,
- "currency": "USD",
- "type": "2nd_chb",
- "status": "reversed",
- "date": "2022-07-10 00:00:00",
- "settlement_date": "2022-07-10 00:00:00",
- "updated_date": "2022-07-11 00:00:00",
- "deadline_date": "2022-07-12 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}
}, - "three_ds": {
- "eci": null
}, - "routing": {
- "cascade_steps": [
- {
- "mid": "mid-1",
- "mid_descriptor": "descriptor-1",
- "route_id": "pm-1",
- "cascade_number": 1
}
]
}
}
The get ARN codes request obtains ARN codes for specific orders, providing essential information about refunds, currencies, and transaction statuses.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
Array of objects Array data with information about ARN codes corresponding to the order requested. |
{- "order_id": "wd4SUp"
}
{- "arn_codes": [
- {
- "amount_refunded": 100,
- "arn_code": "7.48711523108244e+22",
- "created_at": "2022-12-27 11:45:30",
- "currency": "USD",
- "transaction_status": "success"
}
]
}
Solidgate API for alternative payment methods allows merchants to securely integrate with a payment gateway to process and manage APM transactions such as PayPal, Sofort, Giropay. etc.
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.
Occasionally you could receive the same event more than once. For example, it could happen while retrying notifications or when you request to resend some events. We advise you to guard against duplicated events by making your event processing idempotent. One way of doing this is logging the event ID you’ve processed and then not processing already-logged events.
We provide the event ID
in the request header params as described below.
merchant | string Example: wh_pk_7b197...ba108f842 A 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. |
solidgate-event-id | string Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1 The unique event identifier. |
object Object with order information. | |
Array of objects The map of transactions. The keys are transaction identifiers. | |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object Deprecated Object with data payment form data. |
{- "order": {
- "amount": 100,
- "currency": "USD",
- "order_id": "1672068260960AlexKhoRecurring11",
- "status": "processing",
- "method": "paypal-vault",
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
- "customer_email": "example.user@example-email.com",
- "ip_address": "8.8.8.8",
- "order_description": "Premium package",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "provider_data": {
- "billing_address": {
- "country": "USA",
- "state": "WA",
- "city": "New York",
- "zip": "10005",
- "line1": "123 Main St.",
- "line2": "Apt. 123"
}, - "shipping_address": {
- "country": "USA",
- "state": "NY",
- "city": "Boston",
- "zip": "91191",
- "line1": "777 Main St.",
- "line2": "Apt. 321"
}, - "payer": {
- "email": "example@email.com",
- "first_name": "John",
- "last_name": "Doe"
}
}
}, - "transactions": [
- {
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "status": "processing",
- "method": "paypal-vault",
- "amount": 100,
- "currency": "USD",
- "type": "pay",
- "created_at": "2022-12-27 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "payer_details": {
- "payer_email": "example.user@example-email.com",
- "invoice_id": "123443334"
}
}
], - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}
}
Operation for the initiation of a payment using an alternative payment method, performs order creation and prepares the transaction for payment, allowing the customer to proceed with the payment process.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
payment_method required | string The requested payment method name. |
amount required | integer >= 0 Order amount in its smallest currency unit (cent for euro).
|
currency required | string = 3 characters The three-letter ISO currency code under ISO-4217. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
order_description required | string <= 100 characters A 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 field configured in the product settings - Public Product Description (HUB → Subscriptions → Products → Select product → Edit details) |
item_category | string Enum: "physical_goods" "digital_goods" A value that uniquely identifies the category of the item.
|
object The billing address of the cardholder. | |
object The address to ship.
| |
customer_date_of_birth | string <= 10 characters yyyy-MM-dd The customer's date of birth. |
customer_account_id | string <= 100 characters The customer ID defined by the merchant. |
customer_email required | string <= 100 characters The customer's email address. |
customer_first_name | string <= 100 characters The customer's first name. |
customer_last_name | string <= 100 characters The customer's last name. |
customer_phone | string <= 50 characters The customer's phone number. Mandatory for locations UGA, KEN, TZA, GHA. |
ip_address required | string <= 50 characters The public IP address of the cardholder. Required for antifraud checks. Both IPv4 and IPv6 are supported. For recurring payments, use the last session or registration IP.
|
platform required | string = 3 characters Default: "WEB" Enum: "APP" "WEB" "MOB" Device Platform, which the customer used at the moment of payment. Available values:
|
user_agent | string [ 1 .. 1000 ] characters The user-agent string of the device used by the customer.
|
success_url | string <= 255 characters Allows you to set the URL for browser redirect after a successful 3D Secure or redirect alternative payment method. |
fail_url | string <= 255 characters Allows you to set the URL for browser redirect after an unsuccessful 3D Secure or redirect payment method. |
return_url | string <= 255 characters Allows you to set the URL for browser redirect after a successful 3D Secure or redirect payment method. |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
object Object with information of the order.
| |
Array of objects The map of transactions.
| |
object Object with data payment form data. | |
object Additional data that is required to make payments with the specific APMs. | |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
{- "payment_method": "paypal-vault",
- "amount": 1020,
- "currency": "USD",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "item_category": "digital_goods",
- "billing_address": {
- "country": "USA",
- "state": "WA",
- "city": "New York",
- "zip": "10005",
- "line1": "123 Main St.",
- "line2": "Apt. 123"
}, - "shipping_address": {
- "country": "USA",
- "state": "NY",
- "city": "Boston",
- "zip": "91191",
- "line1": "777 Main St.",
- "line2": "Apt. 321"
}, - "customer_date_of_birth": "1988-11-21",
- "customer_email": "test@solidgate.com",
- "customer_first_name": "Nikola",
- "customer_last_name": "Tesla",
- "customer_phone": "+10111111111",
- "ip_address": "8.8.8.8",
- "platform": "WEB",
- "user_agent": "Mozilla/5.0",
- "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}
}
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "method": "paypal-vault",
- "amount": 1020,
- "currency": "USD",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "status": "processing",
- "ip_address": "8.8.8.8",
- "customer_email": "test@solidgate.com"
}, - "transactions": [
- {
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "method": "paypal-vault",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "created_at": "2022-12-27 11:45:30",
- "type": "pay"
}, - {
- "id": "another_unique_id",
- "method": "paypal-vault",
- "status": "success",
- "amount": 50,
- "currency": "USD",
- "created_at": "2022-12-28 12:00:00",
- "type": "refund",
- "payer_details": {
- "payer_email": "example@gmail.com",
- "invoice_id": "191110512",
- "billing_address": {
- "country": "USA",
- "state": "NY",
- "city": "city",
- "zip": "91191",
- "line1": "Bedford Ave",
- "line2": "22"
}
}
}
], - "pay_form": {
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}
}
For alternative payment methods, a token-based recurring payment refers to an automatic charge 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.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
amount required | integer > 0 Order amount in its smallest currency unit. |
currency required | string = 3 characters The three-letter ISO currency code under ISO-4217. |
product_id | string <uuid> = 36 characters Product ID of the subscription which you create in Solidgate. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
order_description required | string <= 100 characters A description of the order. |
object The billing address of the cardholder. | |
object The address to ship.
| |
customer_date_of_birth | string <= 10 characters yyyy-MM-dd The customer's date of birth. |
customer_account_id | string <= 100 characters The customer ID defined by the merchant. |
customer_email required | string <= 100 characters The customer's email address. |
customer_first_name | string <= 100 characters The customer's first name. |
customer_last_name | string <= 100 characters The customer's last name. |
customer_phone | string <= 50 characters The customer's phone number. |
ip_address required | string <= 50 characters The public IP address of the cardholder. Required for antifraud checks. Both IPv4 and IPv6 are supported. For recurring payments, use the last session or registration IP.
|
platform required | string = 3 characters Default: "WEB" Enum: "APP" "WEB" "MOB" Device Platform, which the customer used at the moment of payment. Available values:
|
fail_url | string <= 255 characters Allows you to set the URL for browser redirect after an unsuccessful 3D Secure or redirect payment method. |
return_url | string <= 255 characters Allows you to set the URL for browser redirect after a successful 3D Secure or redirect payment method. |
token required | string The payment token includes values such as payment amount, currency, transaction ID, and merchant identifier that are used to initiate and process a payment transaction. |
geo_country | string <iso_code_a3> = 3 characters Default: "GBR" The customer's registration country. |
object Object with information of the order. | |
object Object with data payment form data. | |
Array of objects List of transactions. | |
object The payment type data object.
| |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
{- "amount": 1020,
- "currency": "EUR",
- "product_id": "ac43b415-5522-4373-b026-a365462f9657",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_description": "Premium package",
- "billing_address": {
- "country": "USA",
- "state": "WA",
- "city": "New York",
- "zip": "10005",
- "line1": "123 Main St.",
- "line2": "Apt. 123"
}, - "shipping_address": {
- "country": "USA",
- "state": "NY",
- "city": "Boston",
- "zip": "91191",
- "line1": "777 Main St.",
- "line2": "Apt. 321"
}, - "customer_date_of_birth": "1988-11-21",
- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "customer_email": "test@solidgate.com",
- "customer_first_name": "Nikola",
- "customer_last_name": "Tesla",
- "customer_phone": "+10111111111",
- "ip_address": "8.8.8.8",
- "platform": "WEB",
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
- "geo_country": "GBR"
}
{- "order": {
- "amount": 1020,
- "currency": "USD",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "status": "processing",
- "method": "paypal-vault",
- "customer_email": "example.user@example-email.com",
- "ip_address": "8.8.8.8",
- "order_description": "Premium package",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "pay_form": {
}, - "transactions": [
- {
- "status": "processing",
- "method": "paypal-vault",
- "amount": 100,
- "currency": "USD",
- "type": "pay",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "created_at": "2022-12-27 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "payer_details": {
- "payer_email": "example.user@example-email.com",
- "invoice_id": "123443334"
}
}
], - "payment_type_data": {
- "brazil_cpf": 45053975809,
- "phone": 380000000000,
- "bic": "ABNANL2A",
- "argentina_dni": 42243309114,
- "mexico_curp": "ZAZD801124MBSYQN13",
- "iban": "DE25100100101234567893"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}
}
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.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
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. |
refund_reason_code | string = 4 characters Refund reason - a 4-digit code specified in the refund reason list.
|
object Object with information of the order. | |
object Object with data payment form data. | |
Array of objects List of transactions. | |
object The payment type data object.
| |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
{- "order_id": "string",
- "amount": 0,
- "refund_reason_code": "stri"
}
{- "order": {
- "amount": 1020,
- "currency": "USD",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "status": "processing",
- "method": "paypal-vault",
- "customer_email": "example.user@example-email.com",
- "ip_address": "8.8.8.8",
- "order_description": "Premium package",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "pay_form": {
}, - "transactions": [
- {
- "status": "processing",
- "method": "paypal-vault",
- "amount": 100,
- "currency": "USD",
- "type": "pay",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "created_at": "2022-12-27 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "payer_details": {
- "payer_email": "example.user@example-email.com",
- "invoice_id": "123443334"
}
}
], - "payment_type_data": {
- "brazil_cpf": 45053975809,
- "phone": 380000000000,
- "bic": "ABNANL2A",
- "argentina_dni": 42243309114,
- "mexico_curp": "ZAZD801124MBSYQN13",
- "iban": "DE25100100101234567893"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}
}
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.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
order_id required | string <= 255 characters Order identifier defined by the merchant, which can be used later to find this payment. |
object Object with information of the order. | |
object Object with data payment form data. | |
Array of objects List of transactions. | |
object The payment type data object.
| |
order_metadata | object Metadata is useful for storing additional, structured information about an object.
|
{- "order_id": "wd4SUp"
}
{- "order": {
- "amount": 1020,
- "currency": "USD",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "status": "processing",
- "method": "paypal-vault",
- "customer_email": "example.user@example-email.com",
- "ip_address": "8.8.8.8",
- "order_description": "Premium package",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
- "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299"
}, - "pay_form": {
}, - "transactions": [
- {
- "status": "processing",
- "method": "paypal-vault",
- "amount": 100,
- "currency": "USD",
- "type": "pay",
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "created_at": "2022-12-27 11:45:30",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "payer_details": {
- "payer_email": "example.user@example-email.com",
- "invoice_id": "123443334"
}
}
], - "payment_type_data": {
- "brazil_cpf": 45053975809,
- "phone": 380000000000,
- "bic": "ABNANL2A",
- "argentina_dni": 42243309114,
- "mexico_curp": "ZAZD801124MBSYQN13",
- "iban": "DE25100100101234567893"
}, - "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}
}
Solidgate API for subscriptions enables to create and manage prices for subscription products.
This method allows merchants to create new products by providing the required details.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
Create product request
name required | string [ 1 .. 500 ] characters Product name.
|
description required | string [ 1 .. 500 ] characters Product description. |
public_description | string [ 1 .. 100 ] characters Product description for customer. |
status required | string Enum: "disabled" "active" Product status.
|
term_length | integer Number of maximum billing cycles.
|
required | object Billing period in special time units. |
payment_action required | string Enum: "charge" "auth_settle" Specifies 2-phase or 1-phase strategy for money withdrawal with next return or without. |
settle_interval | integer [ 0 .. 144 ] Used in 2-phase withdrawal Required if product |
object This object specifies the trial period settings, applicable for products offering free or paid trials.
| |
retry_strategy_id | string <uuid> Product retry strategy identifier. |
id required | string <uuid> = 36 characters Product identifier. |
created_at required | string < yyyy-MM-dd HH:mm:ss> Product created date time. |
updated_at required | string < yyyy-MM-dd HH:mm:ss> Product updated date time. |
name required | string [ 1 .. 500 ] characters The product name.
|
description required | string [ 1 .. 500 ] characters Product description. |
public_description | string [ 1 .. 100 ] characters Product description for customer. |
status required | string Enum: "disabled" "active" Product status.
|
term_length | integer Number of maximum billing cycles.
|
required | object Billing period in special time units. |
payment_action required | string Enum: "charge" "auth_settle" Specifies 2-phase or 1-phase strategy for money withdrawal with next return or without. |
settle_interval | integer [ 0 .. 144 ] Used in 2-phase withdrawal Required if product |
object Trial settings. Required if trial type is free or paid. Mustn't be sent if type is absent.
| |
retry_strategy_id | string <uuid> Product retry strategy identifier. |
{- "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",
- "term_length": 20,
- "billing_period": {
- "unit": "day",
- "value": 10
}, - "payment_action": "auth_settle",
- "settle_interval": 48,
- "trial": {
- "billing_period": {
- "unit": "day",
- "value": 10
}, - "payment_action": "auth_settle",
- "settle_interval": 48
}, - "retry_strategy_id": "db43b415-5522-4373-b026-a365462f9439"
}
{- "id": "ac43b415-5522-4373-b026-a365462f9657",
- "created_at": "2022-05-31 12:53:12",
- "updated_at": "2022-05-31 12:53:13",
- "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",
- "term_length": 20,
- "billing_period": {
- "unit": "day",
- "value": 10
}, - "payment_action": "auth_settle",
- "settle_interval": 48,
- "trial": {
- "billing_period": {
- "unit": "day",
- "value": 10
}, - "payment_action": "auth_settle",
- "settle_interval": 48
}, - "retry_strategy_id": "db43b415-5522-4373-b026-a365462f9439"
}
By using this method, merchants can find products and retrieve their details by applying filters such as product ID, status, trial availability, and sorting criteria, with pagination support.
filter[id] | string <= 100 characters Example: filter[id]=ac43b415-5522-4373-b026-a365462f9657,xx33b415-5522-4373-b026-a365462f9657 Comma separated products ids. |
filter[status] | string Enum: "active" "disabled" Specify the desired status of products to be returned. Use |
filter[has_trial] | boolean Specify whether the products should have a trial available. Use |
pagination[limit] | integer [ 1 .. 100 ] Default: 10 Example: pagination[limit]=10 The numbers of items to return. |
pagination[offset] | integer >= 0 Default: 0 Example: pagination[offset]=10 The number of items to skip before starting to collect the result set. |
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
Array of objects Contains an array of product data. | |
object Contains information about the pagination of the results. |
{- "data": [
- {
- "id": "cb43b415-5522-4373-b026-a365462f9114",
- "created_at": "2023-05-31 12:53:12",
- "updated_at": "2023-05-31 12:53:13",
- "status": "active",
- "name": "Luxury product",
- "description": "This product is the best product all over the world",
- "public_description": "That cool product which you have bought",
- "term_length": 20,
- "billing_period": {
- "unit": "day",
- "value": 10
}, - "payment_action": "auth_settle",
- "settle_interval": 48,
- "trial": {
- "billing_period": {
- "unit": "day",
- "value": 10
}, - "payment_action": "auth_settle",
- "settle_interval": 48
}, - "retry_strategy_id": "db43b415-5522-4373-b026-a365462f9439"
}
], - "pagination": {
- "offset": 20,
- "limit": 10,
- "total_count": 150
}
}
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.
product_id required | string <uuid> = 36 characters Example: ac43b415-5522-4373-b026-a365462f9657 Product identifier. |
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
name | string [ 1 .. 500 ] characters Product name.
|
description | string [ 1 .. 500 ] characters Product description. |
public_description | string [ 1 .. 100 ] characters Product description for customers.
|
status | string Enum: "disabled" "active" Product status.
|
term_length | integer Number of maximum billing cycles.
|
object Billing period in special time units. | |
payment_action | string Enum: "charge" "auth_settle" Specifies 2-phase or 1-phase strategy for money withdrawal with next return or without. |
settle_interval | integer [ 0 .. 144 ] Used in 2-phase withdrawal Required if product |
object This object specifies the trial period settings, applicable for products offering free or paid trials.
| |
retry_strategy_id | string <uuid> Product retry strategy identifier. If you wish to disable the retry strategy for a product, either set the No retry strategy for this parameter by specifying the |
id required | string <uuid> = 36 characters Product identifier. |
created_at required | string yyyy-MM-dd HH:mm:ss Product created date time. |
updated_at required | string yyyy-MM-dd HH:mm:ss Product updated date time. |
name required | string [ 1 .. 500 ] characters The product name.
|
description required | string [ 1 .. 500 ] characters Product description. |
public_description | string [ 1 .. 100 ] characters Product description for customer. |
status required | string Enum: "disabled" "active" Product status.
|
term_length | integer Number of maximum billing cycles.
|
required | object Billing period in special time units. |
payment_action required | string Enum: "charge" "auth_settle" Specifies 2-phase or 1-phase strategy for money withdrawal with next return or without. |
settle_interval | integer [ 0 .. 144 ] Used in 2-phase withdrawal Required if product |
object Trial settings. Required if trial type is free or paid. Mustn't be sent if type is absent.
| |
retry_strategy_id | string <uuid> Product retry strategy identifier. |
{- "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",
- "term_length": 20,
- "billing_period": {
- "unit": "day",
- "value": 10
}, - "payment_action": "auth_settle",
- "settle_interval": 48,
- "trial": {
- "billing_period": {
- "unit": "day",
- "value": 10
}, - "payment_action": "auth_settle",
- "settle_interval": 48
}, - "retry_strategy_id": "db43b415-5522-4373-b026-a365462f9439"
}
{- "id": "ac43b415-5522-4373-b026-a365462f9657",
- "created_at": "2022-05-31 12:53:12",
- "updated_at": "2022-05-31 12:53:13",
- "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",
- "term_length": 20,
- "billing_period": {
- "unit": "day",
- "value": 10
}, - "payment_action": "auth_settle",
- "settle_interval": 48,
- "trial": {
- "billing_period": {
- "unit": "day",
- "value": 10
}, - "payment_action": "auth_settle",
- "settle_interval": 48
}, - "retry_strategy_id": "db43b415-5522-4373-b026-a365462f9439"
}
By using this method, merchants can create a new product price with specified details and retrieve the created product price information.
product_id required | string <uuid> = 36 characters Example: ac43b415-5522-4373-b026-a365462f9657 Product identifier. |
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
default required | boolean Marks that this price settings will be used by 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 The three-letter ISO product price currency code under ISO-4217. |
country | string <iso_code_a3> = 3 characters Country code.
|
id required | string <uuid> Product price identifier. |
created_at required | string < yyyy-MM-dd HH:mm:ss> Product price created date time. |
updated_at required | string < yyyy-MM-dd HH:mm:ss> Product price updated date time. |
default required | boolean Marks that this price settings will be used by default. |
product_price required | integer [ 1 .. 999999999 ] Product price. |
trial_price | integer [ 1 .. 999999999 ] Trial price. |
currency required | string = 3 characters The three-letter ISO product price currency code under ISO-4217. |
country | string <iso_code_a3> = 3 characters Country code.
|
status required | string Enum: "disabled" "active" Product price status. |
{- "default": false,
- "status": "active",
- "product_price": 1000,
- "trial_price": 500,
- "currency": "USD",
- "country": "USA"
}
{- "id": "cb43b415-5522-4373-b026-a365462f9114",
- "created_at": "2023-05-31 12:53:12",
- "updated_at": "2023-05-31 12:53:13",
- "default": false,
- "product_price": 1000,
- "trial_price": 500,
- "currency": "UAH",
- "country": "USA",
- "status": "active"
}
This method allows merchants to retrieve product prices based on the specified filter criteria and pagination settings, returning the results along with pagination information.
product_id required | string <uuid> = 36 characters Example: ac43b415-5522-4373-b026-a365462f9657 Product identifier. |
filter[currency] | string Example: filter[currency]=UAH,USD Comma separated currencies. |
filter[country] | string <iso_code_a3> = 3 characters Example: filter[country]=USA Country code. |
pagination[limit] | integer [ 1 .. 100 ] Default: 10 Example: pagination[limit]=10 The numbers of items to return. |
pagination[offset] | integer >= 0 Default: 0 Example: pagination[offset]=10 The number of items to skip before starting to collect the result set. |
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
Array of objects Contains an array of product data. | |
object Contains information about the pagination of the results. |
{- "data": [
- {
- "id": "cb43b415-5522-4373-b026-a365462f9114",
- "created_at": "2023-05-31 12:53:12",
- "updated_at": "2023-05-31 12:53:13",
- "default": false,
- "product_price": 1000,
- "trial_price": 500,
- "currency": "UAH",
- "country": "USA",
- "status": "active"
}
], - "pagination": {
- "offset": 20,
- "limit": 10,
- "total_count": 150
}
}
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.
product_id required | string <uuid> = 36 characters Example: ac43b415-5522-4373-b026-a365462f9657 Product identifier. |
product_price_id required | string <uuid> Example: fa43b415-5522-4373-b026-a365562f9649 Product price identifier. |
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
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 The three-letter ISO product price currency code under ISO-4217. |
country | string <iso_code_a3> = 3 characters Country code. |
id required | string <uuid> Product price identifier. |
created_at required | string < yyyy-MM-dd HH:mm:ss> Product price created date time. |
updated_at required | string < yyyy-MM-dd HH:mm:ss> Product price updated date time. |
default required | boolean Marks that this price settings will be used by default. |
product_price required | integer [ 1 .. 999999999 ] Product price. |
trial_price | integer [ 1 .. 999999999 ] Trial price. |
currency required | string = 3 characters The three-letter ISO product price currency code under ISO-4217. |
country | string <iso_code_a3> = 3 characters Country code.
|
status required | string Enum: "disabled" "active" Product price status. |
{- "status": "active",
- "product_price": 1000,
- "trial_price": 500,
- "currency": "USD",
- "country": "USA"
}
{- "id": "cb43b415-5522-4373-b026-a365462f9114",
- "created_at": "2023-05-31 12:53:12",
- "updated_at": "2023-05-31 12:53:13",
- "default": false,
- "product_price": 1000,
- "trial_price": 500,
- "currency": "UAH",
- "country": "USA",
- "status": "active"
}
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.
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 several types of callbacks: init
, renew
, update
, pause
, resume
, pause_schedule.create
, pause_schedule.update
, pause_schedule.delete
, and cancel
.
Occasionally you could receive the same event more than once. For example, it could happen while retrying notifications or when you request to resend some events. We advise you to guard against duplicated events by making your event processing idempotent. One way of doing this is logging the event ID you’ve processed and then not processing already-logged events.
We provide the event ID
in the request header params as described below.
merchant | string Example: wh_pk_7b197...ba108f842 A 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. |
solidgate-event-id | string Example: e1765cf7-70f7-4e56-8fb2-bd88744a94d1 The unique event identifier. |
object The subscription object. | |
object The product object.
| |
object The customer object. | |
object The invoices object. The keys are invoice identifiers. | |
callback_type | string Filed for events occur in the subscription.
|
{- "subscription": {
- "id": "9e252e9f-c5a3-4dca-93df-4c9fcf54267e",
- "status": "active",
- "updated_at": "2022-12-08 12:37:25",
- "started_at": "2022-12-08 12:37:24",
- "expired_at": "2022-12-12 12:37:24",
- "next_charge_at": "2022-11-26 11:43:52",
- "trial": false,
- "payment_type": "card"
}, - "product": {
- "product_id": "a51ba9fd-3be1-4ef9-b00f-bb85157597f5",
- "name": "autotest_paypal-vault 2",
- "amount": 100,
- "currency": "USD",
- "trial": true,
- "payment_action": "auth_void",
- "trial_period": 1440,
- "trial_amount": 99,
- "trial_currency": "USD"
}, - "customer": {
- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "customer_email": "example.user@example-email.com"
}, - "invoices": {
- "<invoice_id_value_#1>": {
- "id": "4022a203-ace8-415f-9ae7-730014fceb25",
- "amount": 100,
- "status": "success",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "billing_period_started_at": "2022-12-29 11:45:30",
- "billing_period_ended_at": "2022-12-30 11:45:30",
- "subscription_term_number": 1,
- "orders": {
- "<order_id_value_#1>": {
- "id": "1672066481283AlexKho",
- "status": "processing",
- "amount": 100,
- "created_at": "2022-12-27 11:45:30",
- "processed_at": "2022-12-28 11:45:30",
- "operation": "pay",
- "retry_attempt": 0,
- "payment_details": {
- "payer_email": "example.user@example-email.com",
- "invoice_id": "123443334"
}
}
}, - "order_metadata": {
- "partner_id": "123989"
}
}
}, - "callback_type": "init"
}
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 name for the subscription. The revised product settings will come into effect following the subsequent debiting date.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
subscription_id required | string <uuid> = 36 characters The ID of the customer’s subscription provided by Solidgate. |
new_product_id required | string <uuid> = 36 characters Provide Subscription Product ID, which should be applied for the specified subscription ID. |
{- "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
- "new_product_id": "ac43b415-5522-4373-b026-a365462f9657"
}
{- "error": {
- "code": "2.01",
- "message": "Validation error",
- "constraints": {
- "property1": [
- {
- "code": "NotNull",
- "message": "must not be null"
}
], - "property2": [
- {
- "code": "NotNull",
- "message": "must not be null"
}
]
}
}
}
This method provides a mechanism for merchants to update the payment token when the customer's preferred payment method changes.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
subscription_id required | string <uuid> = 36 characters The ID of the customer’s subscription provided by Solidgate. |
token required | string = 100 characters The payment token includes values such as payment amount, currency, transaction ID, and merchant identifier that are used to initiate and process a payment transaction. |
{- "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
- "token": "uPrZ4lx6OFxDOC5wVeA0w5E2dBtDgCdGINo5jWPtxwQbsENzrFUIAUFT9rk7J0xWkpKj0NjVlEoa1ufu8fBIexEdyHFSNaPYQC7F"
}
{- "error": {
- "code": "2.01",
- "message": "Validation error",
- "constraints": {
- "property1": [
- {
- "code": "NotNull",
- "message": "must not be null"
}
], - "property2": [
- {
- "code": "NotNull",
- "message": "must not be null"
}
]
}
}
}
By using this method, merchants can schedule a subscription pause, setting the specific start and end dates for the pause period.
subscription_id required | string <uuid> = 36 characters Example: 83b19018-cbc4-45f0-899a-dda84fd2705e The ID of the customer’s subscription provided by Solidgate. |
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
required | object This object parameter is used to define the initial timestamp of the subscription pause period. Depending on the |
required | object This object parameter is used to define the concluding timestamp of the subscription pause period. Depending on the |
id required | string <uuid> This is a unique identifier (UUID) for the specific subscription. |
status required | string Enum: "active" "paused" The current status of the subscription. It can be either |
required | object This object contains the details of the subscription pause. |
{- "start_point": {
- "type": "specific_date",
- "date": "2023-03-09 12:53:12"
}, - "stop_point": {
- "type": "specific_date",
- "date": "2023-03-23 08:13:46"
}
}
{- "id": "bd43b415-4321-6275-c137-b365462f9645",
- "status": "active",
- "pause": {
- "from_date": "2023-03-09 12:53:12",
- "to_date": "2023-03-23 08:13:46"
}
}
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.
subscription_id required | string <uuid> = 36 characters Example: 83b19018-cbc4-45f0-899a-dda84fd2705e The ID of the customer’s subscription provided by Solidgate. |
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
object This object parameter is used to define the initial timestamp of the subscription pause period. Depending on the | |
object This object parameter is used to define the concluding timestamp of the subscription pause period. Depending on the |
id required | string <uuid> This is a unique identifier (UUID) for the specific subscription. |
status required | string Enum: "active" "paused" The current status of the subscription. It can be either |
required | object This object contains the details of the subscription pause. |
{- "start_point": {
- "type": "specific_date",
- "date": "2023-03-09 12:53:12"
}, - "stop_point": {
- "type": "specific_date",
- "date": "2023-03-23 08:13:46"
}
}
{- "id": "bd43b415-4321-6275-c137-b365462f9645",
- "status": "active",
- "pause": {
- "from_date": "2023-03-09 12:53:12",
- "to_date": "2023-03-23 08:13:46"
}
}
This method provides a way to delete the scheduled pause, reverting the subscription to its previous active state or as specified.
subscription_id required | string <uuid> = 36 characters Example: 83b19018-cbc4-45f0-899a-dda84fd2705e The ID of the customer’s subscription provided by Solidgate. |
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
id required | string <uuid> This is a unique identifier (UUID) for the specific subscription. |
status required | string Enum: "active" "paused" The current status of the subscription. It can be either |
{- "id": "bd43b415-4321-6275-c137-b365462f9645",
- "status": "active"
}
By using this method, merchants can cancel the specific subscription by its subscription ID.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
subscription_id required | string <uuid> = 36 characters The ID of the customer’s subscription provided by Solidgate. |
force | boolean Default: false It should be set true to cancel the subscription immediately. Otherwise, the subscription would be cancelled at the end of the billing period. |
cancel_code | string Enum: 8.01 8.02 8.03 8.04 8.05 … 9 more It should be one of allowed codes, means cancel reason. All possible values are described in the payment guide. |
{- "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
- "force": false,
- "cancel_code": "8.01"
}
{- "error": {
- "code": "2.01",
- "message": "Validation error",
- "constraints": {
- "property1": [
- {
- "code": "NotNull",
- "message": "must not be null"
}
], - "property2": [
- {
- "code": "NotNull",
- "message": "must not be null"
}
]
}
}
}
By using this method, the merchant can cancel all subscriptions for the specific customer.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
customer_account_id required | string <= 100 characters The customer ID defined by the merchant. |
force | boolean Default: false It should be set true to cancel the subscription immediately. Otherwise, the subscription would be cancelled at the end of the billing period. |
cancel_code | string Enum: 8.01 8.02 8.03 8.04 8.05 … 9 more It should be one of allowed codes, means cancel reason. All possible values are described in the payment guide. |
{- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "force": false,
- "cancel_code": "8.01"
}
{- "error": {
- "code": "2.01",
- "message": "Validation error",
- "constraints": {
- "property1": [
- {
- "code": "NotNull",
- "message": "must not be null"
}
], - "property2": [
- {
- "code": "NotNull",
- "message": "must not be null"
}
]
}
}
}
By using this method, merchants can restore the specific subscription of their customer in case it was cancelled.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
subscription_id required | string <uuid> = 36 characters The ID of the customer’s subscription provided by Solidgate. |
expired_at | string yyyy-MM-dd HH:mm:ss The desired subscription expiration date. |
{- "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
- "expired_at": "2025-12-25 0:00:00"
}
{- "error": {
- "code": "2.01",
- "message": "Validation error",
- "constraints": {
- "property1": [
- {
- "code": "NotNull",
- "message": "must not be null"
}
], - "property2": [
- {
- "code": "NotNull",
- "message": "must not be null"
}
]
}
}
}
Solidgate API for accessing subscription information provides merchants with the ability to obtain precise and up-to-date details regarding customer subscriptions.
By using this method, merchants can retrieve subscription data by subscription ID and obtain its details, such as the start date, status, and the information about the most recent invoice related to the subscription.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
subscription_id required | string <uuid> = 36 characters The ID of the customer’s subscription provided by Solidgate. |
required | object The subscription object. |
required | object The product object.
|
required | object The customer object. |
required | object The map of invoices. The keys are invoice identifiers. |
{- "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e"
}
{- "subscription": {
- "id": "9e252e9f-c5a3-4dca-93df-4c9fcf54267e",
- "updated_at": "2022-12-08 12:37:25",
- "started_at": "2022-12-08 12:37:24",
- "expired_at": "2022-12-12 12:37:24",
- "next_charge_at": "2022-12-12 14:37:24",
- "cancelled_at": "2022-12-12 19:37:24",
- "cancellation_requested_at": "2022-12-11 19:37:24",
- "trial": "false,",
- "cancel_code": "8.09",
- "cancel_message": "Cancellation after redemption period",
- "payment_type": "card",
- "status": "active",
- "pause": {
- "from_date": "2023-03-27 11:26:08",
- "to_date": "2023-03-27 11:26:08"
}
}, - "product": {
- "id": "a51ba9fd-3be1-4ef9-b00f-bb85157597f5",
- "name": "autotest_paypal-vault 2",
- "amount": 100,
- "currency": "USD",
- "trial": true,
- "payment_action": "auth_void",
- "trial_period": 1,
- "trial_amount": 99,
- "trial_currency": "USD"
}, - "customer": {
- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "customer_email": "example.user@example-email.com"
}, - "invoices": {
- "<invoice_id_value_#1>": {
- "id": "4022a203-ace8-415f-9ae7-730014fceb25",
- "amount": 100,
- "status": "success",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "billing_period_started_at": "2022-12-29 11:45:30",
- "billing_period_ended_at": "2022-12-30 11:45:30",
- "subscription_term_number": 1,
- "orders": {
- "<order_id_value_#1>": {
- "id": "1672066481283AlexKho",
- "status": "processing",
- "amount": 100,
- "created_at": "2022-12-27 11:45:30",
- "processed_at": "2022-12-28 11:45:30",
- "operation": "pay",
- "retry_attempt": 0,
- "payment_details": {
- "payer_email": "example.user@example-email.com",
- "invoice_id": "123443334"
}
}
}
}
}
}
This method allows the merchant to retrieve all subscriptions and their statuses for the specific customer by the customer ID.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
customer_account_id required | string <= 100 characters The customer ID defined by the merchant. |
object This object encapsulates detailed information about a specific subscription and its associated payment and customer data. | |
object This object encapsulates detailed information about a specific subscription and its associated payment and customer data. |
{- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa"
}
{- "<subscription_id_value_#1>": {
- "id": "64e1c283-17bf-45a7-90ea-2cb938081b2f",
- "updated_at": "2022-06-10 15:42:25",
- "started_at": "2022-06-10 15:42:24",
- "expired_at": "2022-09-10 16:42:24",
- "next_charge_at": "2022-11-26 11:43:52",
- "cancelled_at": "2022-06-26 06:43:58",
- "cancellation_requested_at": "2022-06-25 06:43:58",
- "trial": true,
- "cancel_code": "8.01",
- "cancel_message": "Card brand is not supported",
- "payment_type": "paypal-vault",
- "status": "cancelled",
- "customer": {
- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "customer_email": "example.user@example-email.com"
}, - "pause": {
- "from_date": "2023-03-27 11:26:08",
- "to_date": "2023-03-27 11:26:08"
}
}, - "<subscription_id_value_#2>": {
- "id": "64e1c283-17bf-45a7-90ea-2cb938081b2f",
- "updated_at": "2022-06-10 15:42:25",
- "started_at": "2022-06-10 15:42:24",
- "expired_at": "2022-09-10 16:42:24",
- "next_charge_at": "2022-11-26 11:43:52",
- "cancelled_at": "2022-06-26 06:43:58",
- "cancellation_requested_at": "2022-06-25 06:43:58",
- "trial": true,
- "cancel_code": "8.01",
- "cancel_message": "Card brand is not supported",
- "payment_type": "paypal-vault",
- "status": "cancelled",
- "customer": {
- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "customer_email": "example.user@example-email.com"
}, - "pause": {
- "from_date": "2023-03-27 11:26:08",
- "to_date": "2023-03-27 11:26:08"
}
}
}
By using this method, merchants can get a list of invoices related to a specific subscription.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
subscription_id required | string <uuid> = 36 characters The ID of the customer’s subscription provided by Solidgate. |
object It contains information about the pagination of the results.
|
required | Array of objects List of invoices. |
required | object It contains information about the pagination of the results. |
{- "subscription_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
- "pagination": {
- "offset": 20,
- "limit": 10
}
}
{- "data": [
- {
- "id": "4022a203-ace8-415f-9ae7-730014fceb25",
- "amount": 100,
- "status": "fail",
- "billing_period_started_at": "2022-12-29 11:45:30",
- "billing_period_ended_at": "2022-12-30 11:45:30",
- "subscription_term_number": 1,
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30"
}
], - "pagination": {
- "offset": 20,
- "limit": 10,
- "total_count": 150
}
}
By using this method, merchants can retrieve a list of orders associated with a particular invoice.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
invoice_id required | string <uuid> = 36 characters The ID of the subscription invoice provided by Solidgate. |
object It contains information about the pagination of the results.
|
required | Array of objects List of orders. |
required | object It contains information about the pagination of the results. |
{- "invoice_id": "83b19018-cbc4-45f0-899a-dda84fd2705e",
- "pagination": {
- "offset": 20,
- "limit": 10
}
}
{- "data": [
- {
- "id": "1672066481283AlexKho",
- "status": "processing",
- "amount": 100,
- "processed_at": "2022-12-28 11:45:30",
- "operation": "pay",
- "retry_attempt": 0,
- "payment_details": {
- "payer_email": "example.user@example-email.com",
- "invoice_id": "123443334"
}, - "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-27 11:46:30"
}
], - "pagination": {
- "offset": 20,
- "limit": 10,
- "total_count": 150
}
}
The report offers a comprehensive overview for merchants, detailing customer subscriptions, payment methods, crucial customer data, and associated invoices, which are crucial 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.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
date_from required | string yyyy-MM-dd HH:mm:ss Start datetime for the report stated in UTC+0. |
date_to required | string yyyy-MM-dd HH:mm:ss End datetime for the report stated in UTC+0. |
limit | integer [ 1 .. 2000 ] Default: 2000 The limit value indicates the maximum number of items to be returned. |
next_page_iterator | string To perform pagination please add the field with the value from the previous response. |
required | object The map of subscriptions. The keys are subscription identifiers. |
required | object The metadata object. |
{- "date_from": "2022-08-15 11:00:00",
- "date_to": "2022-08-18 11:00:00",
- "limit": 2000,
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}
{- "subscriptions": {
- "<subscription_id_value_#1>": {
- "id": "64e1c283-17bf-45a7-90ea-2cb938081b2f",
- "updated_at": "2022-06-10 15:42:25",
- "started_at": "2022-06-10 15:42:24",
- "expired_at": "2022-09-10 16:42:24",
- "next_charge_at": "2022-11-26 11:43:52",
- "cancelled_at": "2022-06-26 06:43:58",
- "trial": true,
- "cancel_code": "8.01",
- "cancel_message": "Card brand is not supported",
- "payment_type": "paypal-vault",
- "status": "cancelled",
- "customer": {
- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "customer_email": "example.user@example-email.com"
}, - "product": {
- "id": "a51ba9fd-3be1-4ef9-b00f-bb85157597f5",
- "name": "autotest_paypal-vault 2",
- "amount": 100,
- "currency": "USD",
- "trial": true,
- "payment_action": "auth_void",
- "trial_period": 1,
- "trial_amount": 99,
- "trial_currency": "USD"
}, - "invoices": {
- "<invoice_id_value_#1>": {
- "id": "4022a203-ace8-415f-9ae7-730014fceb25",
- "amount": 100,
- "status": "fail",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "billing_period_started_at": "2022-12-29 11:45:30",
- "billing_period_ended_at": "2022-12-30 11:45:30",
- "subscription_term_number": 1,
- "orders": {
- "<order_id_value_#1>": {
- "id": "1672066481283AlexKho",
- "status": "processing",
- "amount": 100,
- "created_at": "2022-12-27 11:45:30",
- "processed_at": "2022-12-28 11:45:30",
- "operation": "pay",
- "retry_attempt": 0,
- "payment_details": {
- "payer_email": "example.user@example-email.com",
- "invoice_id": "123443334"
}
}
}
}
}, - "pause": {
- "from_date": "2023-03-27 11:26:08",
- "to_date": "2023-03-27 11:26:08"
}
}
}, - "metadata": {
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9",
- "count": 1
}
}
Solidgate API for 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.
Please note that the payment page link expires in 24 hours.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
required | object Object with the information required to create an order in the Solidgate system. |
required | object Object with the required information to be displayed on the payment page. |
url required | string Parameter used to specify the specific URL where the customer should be directed to complete their transaction. |
guid required | string Parameters used to uniquely identify a payment session and ensure the security and integrity of the transaction. |
{- "order": {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "order_date": "2015-12-21 11:21:30",
- "order_items": "item 1 x 10, item 2 x 30",
- "order_description": "Premium package",
- "order_number": 9,
- "currency": "EUR",
- "amount": 1020,
- "customer_email": "test@solidgate.com",
- "customer_first_name": "Nikola",
- "customer_last_name": "Tesla",
- "customer_phone": "+10111111111",
- "customer_date_of_birth": "1988-11-21",
- "language": "pt",
- "force3ds": false,
- "type": "auth",
- "settle_interval": 0,
- "transaction_source": "main_menu",
- "purchase_country": "USA",
- "retry_attempt": 3,
- "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "traffic_source": "facebook",
- "geo_country": "USA or US",
- "geo_city": "New Castle",
- "google_pay_allowed_auth_methods": [
- "PAN_ONLY"
]
}, - "page_customization": {
- "public_name": "Public Name",
- "order_title": "Order Title",
- "order_description": "Premium package",
- "payment_methods": [
- "paypal"
], - "button_font_color": "#FFFFFF",
- "button_color": "#00816A",
- "font_name": "Open Sans",
- "is_cardholder_visible": true,
}
}
{- "guid": "1b9a536f-57eb-4f79-9597-1319097882fa"
}
Solidgate Payment Link feature offers a hassle-free way to conduct online sales without integration, allowing merchants to share a URL that leads customers to a secure payment page for both one-time and subscription transactions.
Payment Links are code-free and reusable, allowing you to share them as many times as needed.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
required | object Object with the information required to create an order in the Solidgate system. |
required | object Object with the required information to be displayed on the payment page. |
url required | string Parameter used to specify the specific URL where the customer should be directed to complete their transaction. |
guid required | string Parameters used to uniquely identify a payment session and ensure the security and integrity of the transaction. |
{- "order": {
- "order_description": "Premium package",
- "currency": "EUR",
- "amount": 1020,
- "language": "pt",
- "type": "auth",
- "settle_interval": 0,
- "transaction_source": "main_menu",
- "order_metadata": {
- "coupon_code": "NY2018",
- "partner_id": "123989"
}, - "traffic_source": "facebook",
- "google_pay_allowed_auth_methods": [
- "PAN_ONLY"
]
}, - "page_customization": {
- "public_name": "Public Name",
- "order_title": "Order Title",
- "order_description": "Premium package",
- "button_font_color": "#FFFFFF",
- "button_color": "#00816A",
- "font_name": "Open Sans",
- "is_cardholder_visible": true,
}
}
{- "guid": "1b9a536f-57eb-4f79-9597-1319097882fa"
}
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.
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
parameter for unloading data, which reflects the latest update to card orders.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
date_from required | string yyyy-MM-dd HH:mm:ss Start datetime for the report stated in UTC+0. |
date_to required | string yyyy-MM-dd HH:mm:ss End datetime for the report stated in UTC+0. |
limit | integer [ 1 .. 2000 ] Default: 2000 The limit value indicates the maximum number of items to be returned. |
next_page_iterator | string To perform pagination please add the field with the value from the previous response. |
required | Array of objects List of orders. |
required | object The metadata object. |
{- "date_from": "2022-08-15 11:00:00",
- "date_to": "2022-08-18 11:00:00",
- "limit": 2000,
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}
{- "orders": [
- {
- "order_id": "1672068260960AlexKhoRecurring11",
- "status": "processing",
- "type": "pay",
- "amount": 100,
- "currency": "USD",
- "processing_amount": 0,
- "processing_currency": "USD",
- "order_description": "Premium package",
- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "customer_email": "example.user@example-email.com",
- "customer_first_name": "Nikola",
- "customer_last_name": "Tesla",
- "traffic_source": "facebook",
- "geo_country": "USA",
- "ip_address": "8.8.8.8",
- "error_code": "3.02",
- "platform": "MOB",
- "is_secured": true,
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "psp_order_id": "854756336423874823bdfsg6743gf5",
- "provider_payment_id": "charge_64789DFS3827563HGF56",
- "routing": {
- "cascade_steps": [
- {
- "mid": "mid-1",
- "mid_descriptor": "descriptor-1",
- "route_id": "pm-1",
- "cascade_number": 1
}
]
}, - "transactions": [
- {
- "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
- "operation": "pay",
- "status": "processing",
- "descriptor": "google.com",
- "amount": 100,
- "currency": "USD",
- "refund_reason": "Solidgate - Issuer Fraud Notification",
- "refund_reason_code": "0022",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "card": {
- "bank": "JSC UNIVERSAL BANK",
- "bin": "444111",
- "brand": "VISA",
- "card_exp_month": "12",
- "card_exp_year": 2028,
- "card_holder": "John Snow",
- "card_type": "CREDIT",
- "country": "USA",
- "number": "444111XXXXXX9435"
}
}
]
}
], - "metadata": {
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9",
- "count": 1
}
}
The report is essential for merchants using alternative payment methods, offering comprehensive transaction details, including order IDs, statuses, amounts, customer information, and anti-fraud data, crucial for a complete understanding of APM transaction dynamics.
Similar to the Card orders API, this report unloads data based on the
updated_at
parameter, indicating the latest update to the APM orders.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
date_from required | string yyyy-MM-dd HH:mm:ss Start datetime for the report stated in UTC+0. |
date_to required | string yyyy-MM-dd HH:mm:ss End datetime for the report stated in UTC+0. |
limit | integer [ 1 .. 2000 ] Default: 2000 The limit value indicates the maximum number of items to be returned. |
next_page_iterator | string To perform pagination please add the field with the value from the previous response. |
required | Array of objects List of orders. |
required | object The metadata object. |
{- "date_from": "2022-08-15 11:00:00",
- "date_to": "2022-08-18 11:00:00",
- "limit": 2000,
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}
{- "orders": [
- {
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "status": "processing",
- "amount": 100,
- "currency": "USD",
- "order_description": "Premium package",
- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "customer_email": "example.user@example-email.com",
- "processing_amount": 0,
- "processing_currency": "USD",
- "geo_country": "USA",
- "ip_address": "8.8.8.8",
- "error_code": "3.02",
- "method": "paypal-vault",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-28 11:45:30",
- "transactions": [
- {
- "status": "processing",
- "type": "pay",
- "method": "paypal-vault",
- "created_at": "2022-12-28 11:45:30",
- "updated_at": "2022-12-29 11:45:30",
- "amount": 100,
- "currency": "USD",
- "psp_transaction_id": null
}
]
}
], - "metadata": {
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9",
- "count": 1
}
}
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
created_at
parameter, which reflects the date when the latest chargeback flow was created.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
date_from required | string yyyy-MM-dd HH:mm:ss Start datetime for the report stated in UTC+0. |
date_to required | string yyyy-MM-dd HH:mm:ss End datetime for the report stated in UTC+0. |
limit | integer [ 1 .. 2000 ] Default: 2000 The limit value indicates the maximum number of items to be returned. |
next_page_iterator | string To perform pagination please add the field with the value from the previous response. |
required | Array of objects List of orders. |
required | object The metadata object. |
{- "date_from": "2022-08-15 11:00:00",
- "date_to": "2022-08-18 11:00:00",
- "limit": 2000,
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}
{- "orders": [
- {
- "order_id": "1672068260960AlexKhoRecurring11",
- "status": "approved",
- "type": "pay",
- "amount": 100,
- "currency": "USD",
- "order_description": "Premium package",
- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "customer_email": "example@email.com",
- "customer_first_name": "Nikola",
- "customer_last_name": "Tesla",
- "geo_country": "USA",
- "ip_address": "8.8.8.8",
- "platform": "WEB",
- "is_secured": false,
- "created_at": "2023-08-18 09:57:42",
- "updated_at": "2023-08-18 09:57:42",
- "chargebacks": [
- {
- "id": "892140",
- "created_at": "2023-08-18 09:57:49",
- "updated_at": "2023-08-18 09:57:49",
- "dispute_date": "2023-08-18 09:57:49",
- "settlement_date": "2023-08-18 09:57:49",
- "status": "reversed",
- "type": "1st_chb",
- "amount": 100,
- "currency": "USD",
- "reason_group": "Fraud",
- "reason_code": "10.4",
- "reason_description": "Fraud – Card-Absent Environment",
- "flows": [
- {
- "id": "1159271",
- "amount": 100,
- "dispute_amount": 100,
- "currency": "USD",
- "type": "1st_chb",
- "status": "in_progress",
- "date": "2023-08-18 00:00:00",
- "settlement_date": "2023-08-18 00:00:00",
- "created_at": "2023-08-18 09:57:48",
- "updated_at": "2023-08-18 09:57:49",
- "deadline_date": "2023-08-28 00:00:00",
- "arn_code": "7.487115236108244e+22"
}
]
}
]
}
], - "metadata": {
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9",
- "count": 1
}
}
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
parameter is used to unload fraud alert data. It specifies the exact time when a fraud alert was created.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
date_from required | string yyyy-MM-dd HH:mm:ss Start datetime for the report stated in UTC+0. |
date_to required | string yyyy-MM-dd HH:mm:ss End datetime for the report stated in UTC+0. |
limit | integer [ 1 .. 2000 ] Default: 2000 The limit value indicates the maximum number of items to be returned. |
next_page_iterator | string To perform pagination please add the field with the value from the previous response. |
Array of objects The alerts object. | |
object The metadata object. |
{- "date_from": "2022-08-15 11:00:00",
- "date_to": "2022-08-18 11:00:00",
- "limit": 2000,
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}
{- "alerts": [
- {
- "order_id": "923bb4e6-4a5f-41ec-81fb-48eb8a152e55",
- "fraud_amount": 50,
- "fraud_currency": "USD",
- "fraud_amount_usd": 100,
- "fraud_report_day": "2022-03-24 14:22:15",
- "card_scheme": "VISA",
- "fraud_type": "6",
- "reason_code_description": "Fraudulent Use of Account Number",
- "created_at": "2022-12-27 11:45:30",
- "updated_at": "2022-12-27 11:45:30"
}
], - "metadata": {
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9",
- "count": 1
}
}
The report is crucial, offering detailed insights on each dispute with PayPal, including dispute IDs, order details, and lifecycle stages, which are essential for effective dispute management and enhancing customer satisfaction.
This report uses the
created_at
parameter for unloading data. It’s understood that this report refers to PayPal disputes specifically.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
date_from required | string yyyy-MM-dd HH:mm:ss Start datetime for the report stated in UTC+0. |
date_to required | string yyyy-MM-dd HH:mm:ss End datetime for the report stated in UTC+0. |
limit | integer [ 1 .. 2000 ] Default: 2000 The limit value indicates the maximum number of items to be returned. |
next_page_iterator | string To perform pagination please add the field with the value from the previous response. |
Array of objects The dispute object. | |
object The metadata object. |
{- "date_from": "2022-08-15 11:00:00",
- "date_to": "2022-08-18 11:00:00",
- "limit": 2000,
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"
}
{- "disputes": [
- {
- "dispute_id": "PP-D-85112454",
- "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
- "dispute_amount": 100,
- "dispute_currency": "USD",
- "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
- "status": "WAITING_FOR_BUYER_RESPONSE",
- "dispute_life_cycle_stage": "INQUIRY",
- "dispute_channel": "INTERNAL",
- "dispute_create_time": "2022-07-02 23:39:06",
- "dispute_update_time": "2022-07-08 1:40:44",
- "customer_email": "test@gmail.com",
- "seller_response_due_date": "2020-09-14 16:29:12",
- "created_at": "2020-08-23 12:05:28",
- "updated_at": "2020-08-23 12:05:28",
- "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
- "subscription_product_id": "ac43b415-5522-4373-b026-a365462f9657",
- "subscription_service_id": "fb603790-xxxx-1111-xxxx-ae4d59d5d378"
}
], - "metadata": {
- "next_page_iterator": "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9",
- "count": 1
}
}
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.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
date_from required | string yyyy-MM-dd HH:mm:ss Start datetime for the report stated in UTC+0. |
date_to required | string yyyy-MM-dd HH:mm:ss End datetime for the report stated in UTC+0. |
report_url | string This field represents the URL for the report stored on Amazon S3, which needs to be downloaded. |
{- "date_from": "2020-08-15 11:00:00",
- "date_to": "2020-09-20 13:00:00"
}
{- "report_url": {
- "type": "string",
- "description": "This field represents the URL for the report stored on Amazon S3, which needs to be downloaded.",
}
}
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.
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
settlement_id required | string <= 100 characters ID of the settlement. |
report_url | string This field represents the URL for the report stored on Amazon S3, which needs to be downloaded. |
{- "settlement_id": "2A1N0V1"
}
{- "report_url": {
- "type": "string",
- "description": "This field represents the URL for the report stored on Amazon S3, which needs to be downloaded.",
}
}
The report offer 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.
report_id required | string Example: 2A1N0V1 ID of the report to download. |
merchant | string Example: api_pk_7b197...ba108f842 A 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. |
required | object The error object. |
{- "error": {
- "code": "1.01",
- "messages": [
- "Authentication failed"
]
}
}
The changelog is crucial for documenting all modifications, enhancements, and removals to the API. It is essential for developers and users to track changes, understand new features, and adjust their implementations.
It is 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.
19 March 2024
Added a dedicated section encompassing methods tailored for retrieving subscription data
18 March 2024
Added:
discount_id
for subscription flow in recurring, apple-pay, google-pay requests12 March 2024
Added mid
and payment_type
fields to the order
object in all card payments responses
28 February 2024
Removed the deprecated:
design_name
field from the pay_form
objectprovider_id
field from the alert
object from the prevent alert webhook08 February 2024
Added outcome
field to the alert
object for the prevent alert webhook
05 February 2024
Added:
02 February 2024
Added create payment link endpoint allows to create a reusable Payment Page URL with no code required
30 January 2024
Added:
upi
as an alternative payment_method
option in the init payment requestlimit
field in the request body for reports to specify the maximum number of items to be returned, and introduced the count
field in the metadata
object of the response to indicate the number of orders on the page, along with the updated_at
field for common objects in the response24 January 2024
Added update subscription token endpoint for recurring payments