Личный кабинет Вход
Рус
Консультация
Вход

API Документация.

    Аутентификация.

    Доступы к API

    Cascad API построены с учётом REST и используют JSON-формат и стандартные коды ответов HTTP для обмена данными.

    Публичный API

    Адрес для запросов: pay.cascad.com/public-api/

    В запросах для публичного API используется Публичный ключ, боевой (live) или тестовый (test).

    Ключи для интеграции находятся в настройках аккаунта в разделе "Интеграция".

    Приватный API

    Адрес для запросов: pay.cascad.com

    Для авторизации используются ID аккаунта как Login (Username) и ключ API как Password. Данные параметры находятся в настройках коммерческого аккаунта в разделе "Интеграция".

    Стандарт BasicAuth: Authorization = Basic base64(username:password)

    Пример
    curl -X POST \
    
pay.cascad.com/payment-invoices \
    
-H 'Accept: */*' \
    
-H 'Authorization: Basic Y29tYV92VDZMRFUwVHhPeG1iT290OkJlTlZRQ2hLcFV2RUxac3gwVmVpbnRaUmNlSmFWSWdrZVY2N1NvOVB0Wnc=' \
    
-d '{...}'

    Аккаунт.

    Получение данных аккаунта

    Endpoint: /account

    Method: GET

    Авторизация: Private API BasicAuth

    Пример ответа
    {
	"data": {
		"type": "account",
    "id": "coma_CebLG6xR7jOhQmkD",
    "attributes": {
			"status": "active",
			"name": "MyAccount",
			"icon": "https://example.com/images/coma_CebLG6xR7jOhQmkD/logo.png?1583399986",
			"description": "",
			"website": "https://example.com",
			"payment_fee_shift_out": false,
			"hp_domain": "https://example.eu/",
			"payment_options": {
				"descriptor_template": null,
				"attempts_limit": 5,
				"disabled_services": [
					"comcps_HSORYCGLJ237V07d",
					"comcps_a8WLGWFgNDm1jA48"
				],
				"disable_new_services": true,
				"reverse_fee": false,
				"fee_strategy": "internal",
				"invoice_lifetime": 2880,
				"forbid_public_creation": false,
				"public_zero_fee": false,
				"public_fee": false,
				"expose_internal_data": true,
				"bypass_hpp": true,
				"force_commerce_return_url": true,
				"send_operation_context_on_return": true,
				"refund_fee": false,
				"recurrent": false,
				"allow_overwrite_descriptor": false
			},
			"payout_options": {
				"descriptor_template": null,
				"disabled_services": [],
				"batch_options": {
				"attempts_limit": 5,
				"processing_mode": "parallel"
				},
				"methods": [],
				"disable_new_services": false,
				"reverse_fee": true,
				"fee_strategy": "internal",
				"moderation_required": false,
				"invoice_lifetime": 30,
				"split_mode": false,
				"attempts_limit": 5,
				"parallel_mode": false,
				"allow_partially": false,
				"public_zero_fee": false,
				"public_fee": false,
				"expose_internal_data": false
			},
			"api_key": "jA55tDxgWwROc******5L0XtZZW2hKbsNLxBXs",
			"api_key_updated": 1581174500,
			"live_public_key": "pk_live_gHJXSMdFxG********ncFZDOhMBaf0MYkk",
			"live_private_key": "sk_live_r52mIq_qbL497********g-Vr8pfoN6Ojrw98E",
			"test_public_key": "pk_test_eCEOeg*****7M46Rv3bIn2Ag",
			"test_private_key": "sk_test_0Jb_N2x*************LbHXW0VC6wRcGf_Qxs1DAs",
			"callback_url": "https://example.site/026c96db-be91-481e-b7c6-4a82bac744a7",
			"ledger_scheme": "simple",
			"api_ip_white_list": [],
			"created": 1556285176,
			"updated": 1583327142,
			"currency_accounts": {
				"EUR": {
				"active_balance": "11.00",
				"pending_balance": "1.00",
				"reserved_balance": "0.00",
				"overdraft_limit": "10.00"
				},
				"BTC": {
				"active_balance": "0.00000000",
				"pending_balance": "0.00000000",
				"reserved_balance": "0.00000000",
				"overdraft_limit": "0.00000000"
				},
				"USD": {
				"active_balance": "0.22",
				"pending_balance": "2.00",
				"reserved_balance": "0.00",
				"overdraft_limit": "10.00"
				}
				},
				"report": true,
				"time_zone": "Europe/Kiev"
			},
			"links": {
			"self": "/api/account"
			}
	}
}

    Балансы

    Запрос на получение данных аккаунта содержит объект с балансами по валютам — currency_accounts :

    • Active ( active_balance ) — активный баланс (доступные средства для вывода)
    • Pending ( pending_balance ) — баланс с суммами в обработке (включает в себя незавершенные выплаты)
    • Reserved ( reserved_balance ) — «замороженный» баланс (может быть установлено резервирование части суммы принятых платежей на определённый период)
    • Overdraft ( overdraft_limit ) — Овердрафт лимит (доступные кредитные средства)
    Пример ответа
    {
	   "currency_accounts": {
	      "EUR": {
	         "active_balance": "11.00",
	         "pending_balance": "1.00",
	         "reserved_balance": "0.00",
	         "overdraft_limit": "10.00"
	      },
	      "BTC": {
	         "active_balance": "0.00000000",
	         "pending_balance": "0.00000000",
	         "reserved_balance": "0.00000000",
	         "overdraft_limit": "0.00000000"
	      },
	      "USD": {
	         "active_balance": "0.22",
	         "pending_balance": "2.00",
	         "reserved_balance": "0.00",
	         "overdraft_limit": "10.00"
	      }
	   }
	}

    Приём платежей с перенаправлением пользователя на платежную страницу.

    Предзапрос платежа через публичный API

    Предзапросы используются для получения списка доступных для данной валюты сервисов.

    Предзапрос не предусматривает фильтрацию сервисов по инициированной сумме, так как пользователь может оплатить в валюте, отличной от переданной.

    Endpoint: /payment-prerequest

    Method: POST

    Примеры (JSON)
    Запрос
    Ответ
    {
	"public_key" : "pk_test_ClSQHi2T9WXuFa76WcwwBB6rspRpg6ANM69cS9zNOJy",
	"currency" : "UAH"
}
    {
		"data": {
		"currency": "UAH",
		"test_mode": true,
		"services": {
			"payment_card_uah_hpp": {
				"code": "payment_card_uah_hpp",
				"method": "payment_card",
				"flow": "hpp",
				"currency": "UAH",
				"fields": [],
				"amount_min": 0.01,
				"amount_max": 1000000
			},
			"test_uah_test": {
				"code": "test_uah_test",
				"method": "test",
				"flow": "test",
				"currency": "UAH",
				"fields": [
					{
						"key": "status",
						"type": "string",
						"label": {
							"ru": "Статус",
							"en": "Status",
							"uk": "Статус"
						},
						"example": null,
						"hint": {
							"ru": "Введите статус",
							"en": "Enter Status",
							"uk": "Введіть статус"
						},
						"regexp": "^[a-zA-Z_]*$",
						"required": true,
						"position": 0
					}
				],
				"amount_min": 0.01,
				"amount_max": 9999999
			}
		},
		"methods": {
			"payment_card": {
				"code": "payment_card",
				"category": "payment_card",
				"description": "",
				"name": {
					"en": "Payment card",
					"ru": "Платежная карта",
					"uk": "Платіжна карта"
				},
				"logo": "https://static.openfintech.io/payment_methods/payment_card/logo.svg",
				"icon": "https://static.openfintech.io/payment_methods/payment_card/icon.svg",
				"metadata": null,
				"position": null,
				"hide": null
			},
			"test": {
				"code": "test",
				"category": "alternative",
				"description": "",
				"name": {
					"en": "Test",
					"ru": "Тест",
					"uk": "Тест"
				},
				"logo": "https://static.openfintech.io/payment_methods/test/logo.png",
				"icon": "https://static.openfintech.io/payment_methods/test/icon.svg",
				"metadata": null,
				"position": null,
				"hide": null
			}
		},
		"account": {
			"name": "4Docs",
			"description": "4Docs only",
			"icon": "https://static-dev.psp.name/images/default.svg?1595844446",
			"website": null
			}
		}
	}

    Получение списка доступных сервисов через приватный API

    Полный список сервисов

    Endpoint: /payment-services

    Method: GET

    Пример ответа
    {
	"meta": {
	  "total": 124,
	  "pages": 7,
	  "page": 1
	},
	"links": {
	  "first": "/api/payment-services?page[number]=1&page[size]=20",
	  "next": "/api/payment-services?page[number]=2&page[size]=20",
	  "last": "/api/payment-services?page[number]=7&page[size]=20"
	},
	"data": [
	  {
		"type": "payment-services",
		"id": "comcps_wQmYGz5RbkcgfdLI",
		"attributes": {
			"service": "test_xts_test",
			"service_method": "test",
			"service_currency": "XTS",
			"available": true,
			"active": false,
			"enabled": true,
			"amount_min": 0.01,
			"amount_max": 9999999,
			"fee_min": 0,
			"fee_max": 0,
			"fee_rate": 0,
			"fee_fix": 0,
			"reserve_lifetime": 0,
			"reserve_rate": 0,
			"currency": "GBP",
			"test_mode": true
		},
		"relationships": {
			"payment-method": {
			  "data": {
				  "type": "payment-methods",
				  "id": "test"
			  }
			},
			"payment-service": {
			  "data": {
				  "type": "payment-services",
				  "id": "test_xts_test"
			  }
			}
		},
		"links": {
			"self": "/api/payment-services/comcps_wQmYGz5RbkcgfdLI"
		}
	  },
	  {
		"type": "payment-services",
		"id": "comcps_u1xxlHVw1NyeqmjJ",
		"attributes": {
			"service": "payment_card_uah_hpp",
			"service_method": "payment_card",
			"service_currency": "UAH",
			"available": true,
			"active": false,
			"enabled": true,
			"amount_min": 0.01,
			"amount_max": 1000000,
			"fee_min": 0,
			"fee_max": 0,
			"fee_rate": 0,
			"fee_fix": 0,
			"reserve_lifetime": 0,
			"reserve_rate": 0,
			"currency": "GBP",
			"test_mode": true
		},
		"relationships": {
			"payment-method": {
			  "data": {
				  "type": "payment-methods",
				  "id": "payment_card"
			  }
			},
			"payment-service": {
			  "data": {
				  "type": "payment-services",
				  "id": "payment_card_uah_hpp"
			  }
			}
		},
		"links": {
			"self": "/api/payment-services/comcps_u1xxlHVw1NyeqmjJ"
		}
	  },
	  {
		"type": "payment-services",
		"id": "comcps_TEKVfH0di0vGimkF",
		"attributes": {
			"service": "applepay_uah_hpp",
			"service_method": "applepay",
			"service_currency": "UAH",
			"available": true,
			"active": false,
			"enabled": true,
			"amount_min": 0.01,
			"amount_max": 1000000,
			"fee_min": 0,
			"fee_max": 0,
			"fee_rate": 0,
			"fee_fix": 0,
			"reserve_lifetime": 0,
			"reserve_rate": 0,
			"currency": "GBP",
			"test_mode": true
		},
		"relationships": {
			"payment-method": {
			  "data": {
				  "type": "payment-methods",
				  "id": "applepay"
			  }
			},
			"payment-service": {
			  "data": {
				  "type": "payment-services",
				  "id": "applepay_uah_hpp"
			  }
			}
		},
		"links": {
			"self": "/api/payment-services/comcps_TEKVfH0di0vGimkF"
		}
	  }
	]
	}

    Данные сервиса по ID

    Endpoint: /payment-services/{id}

    Method: GET

    Значение ID: из предыдущего запроса

    Пример ответа
    {
		"data": {
		"type": "payment-services",
		"id": "comcps_u1xxlHVw1NyeqmjJ",
		"attributes": {
			"service": "payment_card_uah_hpp",
			"service_method": "payment_card",
			"service_currency": "UAH",
			"available": true,
			"active": false,
			"enabled": true,
			"amount_min": 0.01,
			"amount_max": 1000000,
			"fee_min": 0,
			"fee_max": 0,
			"fee_rate": 0,
			"fee_fix": 0,
			"reserve_lifetime": 0,
			"reserve_rate": 0,
			"currency": "GBP",
			"test_mode": true
		},
		"relationships": {
			"payment-method": {
				"data": {
					"type": "payment-methods",
					"id": "payment_card"
				}
			},
			"payment-service": {
				"data": {
					"type": "payment-services",
					"id": "payment_card_uah_hpp"
				}
			}
		},
		"links": {
			"self": "/api/payment-services/comcps_u1xxlHVw1NyeqmjJ"
		}
	}
	}

    Инициирование инвойса

    Через публичный API

    Внимание

    Публичный API поддерживает инициирование инвойсов, если в настройках аккаунта для платежей отключен параметр «Только приватный API» (Forbid public access : FALSE)

    Настройки Инициирование инвойса - API Документация - Cascad.com Опции платежей

    Инициирование инвойса - API Документация - Cascad.com

    Endpoint: /payment-invoices

    Method: POST

    Обязательные поля запроса:

    • public_key — публичный ключ аккаунта
    • reference_id — уникальный идентификатор операции на стороне
    • service — идентификатор сервиса, например payment_card_usd_hpp. Список всех доступных сервисов можно посмотреть в настройках платежей
    • currency — валюта платежа
    • amount — сумма в float формате, например 100.55

    Дополнительное поле:

    • description
    Примеры (JSON)
    Запрос
    Ответ
    {
			"public_key": "pk_test_ClSQHi2T9WXuFa76WcwwBB6rspRpg6ANM69cS9zNOJy",
			"reference_id": "7135b08b-701b-4fbc-a7d2-b2763d96d415",
			"description": "Invoice Example",
			"service": "payment_card_uah_hpp",
			"currency": "UAH",
			"amount": 123.45
	}
    {
		"data": {
			"id": "cpi_QGcJxoBxnYStkuvN",
			"serial_number": "QGcJxoBxnYStkuvN",
			"created": 1595846278,
			"test_mode": true,
			"reference_id": "7135b08b-701b-4fbc-a7d2-b2763d96d415",
			"currency": "UAH",
			"amount": 123.45,
			"payment_amount": 123.45,
			"processed_amount": null,
			"refunded_amount": null,
			"description": "Invoice Example",
			"has_return_url": false,
			"status": "process_pending",
			"resolution": "OK",
			"service": "payment_card_uah_hpp",
			"service_method": "payment_card",
			"service_flow": "hpp",
			"service_currency": "UAH",
			"metadata": {
				"merchant_url": "https://lets.doc.it"
			},
			"active_payment": {
				"payload": {
					"action": "https://cardgate-staging.psp.name/hpp/cgi_8z1WIRwAtwvyI3G9",
					"method": "GET",
					"params": [],
					"metadata": {
						"sid": "cgi_8z1WIRwAtwvyI3G9",
						"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfOHoxV0lSd0F0d3Z5STNHOSIsImV4cCI6MTU5NTg0ODA3OH0.NZE80zZm6-L8B8Q38xING5vXS86tCryGoyIefq9Aju-pCSmk8Sq1gKvCfFxTmDeytv4J509JEuSg4Ti0TK2ZeTLTvNsDU-wqWJqxL9sUq6Hd-1-2qK60qbtFJ7NbqwGFUaRpe8lU3QKM4F1S7JcTmqXg-Iz9dsVNr9obNj9Pw2MGndInKGWk2qG-ZQRZV0IXRrk49xSLo24wtLYPaZRGEkY1rPmmrSeeO1AFigfDLyld7A3w13EzotPwWPtsoPZFA4Rhcggr1s8Fjnl8iZJk8MBhHWZ4xQjdI1TNAzd1w-s6mfWjAzJlrjXge59X7NI4nuVaUroOg-o63sCCSFNTZfcP-HHMcrw01UG1COyxV4DXogrzSGuLFubqEa67BMgQGdB_pRK_NMqMJyFXTGLzG-A8m0AtIfmh45zUJeSK5Xgjc-luSh0mJAthQt0II2sBKJ_iJXl6ZWWffJIdzuIqmPWrjdw8EK2yCvTZtXl7xD4Rj37PaoQ1-4ezn_rnXk"
					}
				},
				"status": "invoked",
				"resolution": "OK"
			}
		}
	}

    Через приватный API

    Endpoint: /payment-invoices

    Method: POST

    Обязательные поля запроса:

    • reference_id — уникальный идентификатор операции на стороне мерчанта
    • service идентификатор сервиса, например payment_card_usd_hpp. Список всех доступных сервисов можно посмотреть в личном кабинете
    • currency — валюта платежа
    • amount — сумма в float формате, например 100.55

    Дополнительное поле:

    • flow — определяет тип инвойса. Может принимать значения charge, verify. В случае отсутствия параметра в запросе по умолчанию принимается значение charge
    • service_fields — обязательный параметр в некоторых сервисах, которые требуют передачи реквизитов, предусматривает обязательный атрибут номер телефона или идентификатор кошелька
    • test_mode — признак тестовой / «боевой» операции. Может принимать значения true, false. В случае отсутствия параметра в запросе по умолчанию принимается значение false
    • description
    • customer
      • reference_id — обязательный атрибут при наличии объекта в запросе
      • name
      • email
      • phone
      • metadata
    • metadata
    • return_url — универсальный URL для возврата пользователя после оплаты
    • return_urls — специальный объект с 3-мя вариантами URL для возврата пользователя на основании статуса платежа
      • success
      • fail
      • pending — обязательный атрибут при наличии объекта в запросе
    • callback_url — URL для отправки уведомлений при изменении статуса операции
    • gateway_options — опции модификации шлюза, к примеру — для видоизменения платёжной страницы (необходимо уточнять набор и возможные значения для каждого конкретного аккаунта)
    Примеры (JSON)
    Запрос
    Ответ
    {
		"data": {
			"type":"payment-invoices",
			"attributes": {
			  "reference_id": "a30ebec4-035c-4fc5-8c48-b525ca601f37",
			  "amount": 100,
			  "currency": "UAH",
			  "service": "payment_card_uah_hpp",
			  "flow": "charge",
			  "test_mode": true,
			  "description": "Invoice Example",
			  "gateway_options": {
				  "cardgate": {
					"tokenize": false
				  }
			  },
			  "customer": {
				  "reference_id": "1203515",
				  "email": "somename@domain.com",
				  "name": "John Wick",
				  "phone": "+380987654321",
				  "metadata": {
					"key1": "value1",
					"key2": "value2"
				  }
			  },
			  "metadata": {
				  "key": "value"
			  },
			  "return_url": "https://example.com",
			  "return_urls": {
				  "success": "https://example.com/1",
				  "pending": "https://example.com/2",
				  "fail": "https://example.com/3"
			  },
			  "callback_url": "https://example.com"
			}
		}
	}
    {
	"data": {
	"type": "payment-invoices",
	"id": "cpi_HeSWMM9LvQonCcQc",
	"attributes": {
		"serial_number": "HeSWMM9LvQonCcQc",
		"status": "process_pending",
		"resolution": "ok",
		"moderation_required": false,
		"amount": 100,
		"payment_amount": 100,
		"currency": "UAH",
		"service_currency": "UAH",
		"reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
		"test_mode": true,
		"fee": 0,
		"deposit": 100,
		"processed": null,
		"processed_amount": null,
		"refunded_amount": null,
		"processed_fee": null,
		"processed_deposit": null,
		"metadata": {
			"key": "value",
			"merchant_url": "https://lets.doc.it"
		},
		"flow_data": {
			"action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
			"method": "GET",
			"params": [],
			"metadata": {
				"sid": "cgi_G0bsyhroZj802zQU",
				"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
			}
		},
		"flow": "hpp",
		"payment_flow": "charge",
		"created": 1597833098,
		"updated": 1597833098,
		"payload": null,
		"description": "Invoice Example",
		"descriptor": null,
		"callback_url": "https://example.com",
		"return_url": "https://example.com",
		"original_data": [],
		"rrn": null,
		"approval_code": null,
		"reserved_amount": null,
		"reserve_expires": null,
		"unreserved": null,
		"source": "merchant_api",
		"callback_logs": []
	},
	"relationships": {
		"payment-service": {
			"data": {
				"type": "payment-services",
				"id": "payment_card_uah_hpp"
			}
		},
		"payment-method": {
			"data": {
				"type": "payment-methods",
				"id": "payment_card"
			}
		},
		"customer": {
			"data": {
				"type": "customers",
				"id": "cus_Tjhe1ufEB3kRrgWy"
			}
		}
	},
	"links": {
		"self": "/api/payment-invoices/cpi_HeSWMM9LvQonCcQc"
	}
}
}

    Статусы инвойсов

    Перечень статусов

    Статус платежа — определяет этап проведения транзакции. Статус может быть промежуточным и финальным.

    Статусы инвойсов - API Документация - Cascad.com

    Статус Финальный Значение
    created Начальный статус после создания инвойса, процессирование не начато. В ответе должен быть возвращен 201 (Created) статус-код HTTP, что означает успешное создание инвойса
    expired Статусы инвойсов - API Документация - Cascad.com Время ожидания обработки платежного инвойса превысило лимит (заданный в настройках выплаты свойством invoice_lifetime)
    process_pending Результат обработки транзакции неизвестен (например, не получен ответ платежного провайдера) и также может быть неизвестен в течение продолжительного времени
    processed Статусы инвойсов - API Документация - Cascad.com* Подтверждает успешное процессирование платежа
    process_failed Статусы инвойсов - API Документация - Cascad.com** Означает сбой процессирования. Статус может быть присвоен в случае повторяющейся ошибки и сбое получения ответа
    refund_pending Результат возврата неизвестен (например, не получен ответ платежного провайдера) и также может быть неизвестен в течение продолжительного времени
    partially_refunded Статусы инвойсов - API Документация - Cascad.com Возврат произведен на сумму, меньшую чем сумма, указанная в инвойсе
    refunded Статусы инвойсов - API Документация - Cascad.com Платеж полностью возвращен
    refund_failed Статусы инвойсов - API Документация - Cascad.com Возврат завершился неуспешно

    * — Статус считается финальным, однако после него платеж может быть отклонен по дополнительным причинам или отправлен на возврат (рефанд или чарджбэк)

    ** — Статус определяется как финальный после достижения максимального количества попыток провести транзакцию (по умолчанию — 5)

    Идентификация платежа

    На разных этапах приема платежа идентификаторы обрабатываются с разными наименованиями. Связи между ними отображены на схеме ниже.

    Идентификация платежа - API Документация - Cascad.com

    Примечание

    Receiver Reference Number (RRN, номер получателя транзакции) и Acquirer Reference Number (ARN, номер транзакции, присваиваемый эквайером) используются только для карточных расчетов.

    Реконсиляция платежа (по ID)

    Через публичный API

    Endpoint: /payment-invoices/{id}

    Method: GET

    Пример ответа
    {
		"data": {
			"id": "cpi_HeSWMM9LvQonCcQc",
			"serial_number": "HeSWMM9LvQonCcQc",
			"created": 1597833098,
			"test_mode": true,
			"reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
			"currency": "UAH",
			"amount": 100,
			"payment_amount": 100,
			"processed_amount": 100,
			"refunded_amount": null,
			"description": "Invoice Example",
			"has_return_url": true,
			"status": "processed",
			"resolution": "OK",
			"service": "payment_card_uah_hpp",
			"service_method": "payment_card",
			"service_flow": "hpp",
			"service_currency": "UAH",
			"metadata": {
				"key": "value",
				"merchant_url": "https://lets.doc.it"
			},
			"active_payment": {
				"payload": {
					"action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
					"method": "GET",
					"params": [],
					"metadata": {
						"sid": "cgi_G0bsyhroZj802zQU",
						"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
					}
				},
				"status": "processed",
				"resolution": "OK"
			}
		}
	}

    Через приватный API

    Endpoint:

    • /payment-invoices/{id} — обязательный атрибут при наличии объекта в запросе
    • /payment-invoices?filter[reference_id]={reference_id} — для проверки по идентификатору заказа мерчанта reference_id

    Method: GET

    Пример ответа
    {
		"data": {
			"type": "payment-invoices",
			"id": "cpi_HeSWMM9LvQonCcQc",
			"attributes": {
				"serial_number": "HeSWMM9LvQonCcQc",
				"status": "processed",
				"resolution": "ok",
				"moderation_required": false,
				"amount": 100,
				"payment_amount": 100,
				"currency": "UAH",
				"service_currency": "UAH",
				"reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
				"test_mode": true,
				"fee": 0,
				"deposit": 100,
				"processed": 1597833205,
				"processed_amount": 100,
				"refunded_amount": null,
				"processed_fee": 0,
				"processed_deposit": 100,
				"metadata": {
					"key": "value",
					"merchant_url": "https://lets.doc.it"
				},
				"flow_data": {
					"action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
					"method": "GET",
					"params": [],
					"metadata": {
						"sid": "cgi_G0bsyhroZj802zQU",
						"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
					}
				},
				"flow": "hpp",
				"payment_flow": "charge",
				"created": 1597833098,
				"updated": 1597833207,
				"payload": {
					"token": null,
					"client_ip": "",
					"payment_card": {
						"last": "0000",
						"mask": "512381******0000",
						"brand": "mastercard",
						"first": "512381",
						"holder": null,
						"network": "mastercard",
						"expiry_year": "24",
						"issuer_name": "FIRST DATA CORPORATION",
						"expiry_month": "12",
						"issuer_country": "US"
					}
				},
				"description": "Invoice Example",
				"descriptor": null,
				"callback_url": "https://example.com",
				"return_url": "https://example.com",
				"original_data": {
					"external_id": "cgi_G0bsyhroZj802zQU",
					"merchant_id": "host2hostTest",
					"provider_id": null,
					"external_mid": "ma_aBctkJ3WiRndih0m",
					"provider_code": "test"
				},
				"rrn": null,
				"approval_code": null,
				"reserved_amount": null,
				"reserve_expires": null,
				"unreserved": null,
				"source": "merchant_api",
				"callback_logs": {
					"1597833098": {
						"status": "done",
						"processed": 1597833099,
						"response_code": 200,
						"transaction_status": "process_pending"
					},
					"1597833206": {
						"status": "done",
						"processed": 1597833207,
						"response_code": 200,
						"transaction_status": "processed"
					}
				}
			},
			"relationships": {
				"payment-service": {
					"data": {
						"type": "payment-services",
						"id": "payment_card_uah_hpp"
					}
				},
				"payment-method": {
					"data": {
						"type": "payment-methods",
						"id": "payment_card"
					}
				},
				"customer": {
					"data": {
						"type": "customers",
						"id": "cus_Tjhe1ufEB3kRrgWy"
					}
				}
			},
			"links": {
				"self": "/api/payment-invoices/cpi_HeSWMM9LvQonCcQc"
			}
		}
	}

    Получить полный список инвойсов (через приватный API)

    Endpoint: /payment-invoices

    Method: GET

    Пример ответа
    {
		"meta": {
			"count": 17,
			"size": 20,
			"before": "cpi_o8CBGwATmJag4p32",
			"after": "cpi_HeSWMM9LvQonCcQc"
		},
		"links": {
			"prev": "",
			"next": ""
		},
		"data": [
			{
				"type": "payment-invoices",
				"id": "cpi_HeSWMM9LvQonCcQc",
				"attributes": {
					"serial_number": "HeSWMM9LvQonCcQc",
					"status": "processed",
					"resolution": "ok",
					"moderation_required": false,
					"amount": 100,
					"payment_amount": 100,
					"currency": "UAH",
					"service_currency": "UAH",
					"reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
					"test_mode": true,
					"fee": 0,
					"deposit": 100,
					"processed": 1597833205,
					"processed_amount": 100,
					"refunded_amount": null,
					"processed_fee": 0,
					"processed_deposit": 100,
					"metadata": {
						"key": "value",
						"merchant_url": "https://lets.doc.it"
					},
					"flow_data": {
						"action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
						"method": "GET",
						"params": [],
						"metadata": {
							"sid": "cgi_G0bsyhroZj802zQU",
							"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
						}
					},
					"flow": "hpp",
					"payment_flow": "charge",
					"created": 1597833098,
					"updated": 1597833207,
					"payload": {
						"token": null,
						"client_ip": "",
						"payment_card": {
							"last": "0000",
							"mask": "512381******0000",
							"brand": "mastercard",
							"first": "512381",
							"holder": null,
							"network": "mastercard",
							"expiry_year": "24",
							"issuer_name": "FIRST DATA CORPORATION",
							"expiry_month": "12",
							"issuer_country": "US"
						}
					},
					"description": "Invoice Example",
					"descriptor": null,
					"callback_url": "https://example.com",
					"return_url": "https://example.com",
					"original_data": {
						"external_id": "cgi_G0bsyhroZj802zQU",
						"merchant_id": "host2hostTest",
						"provider_id": null,
						"external_mid": "ma_aBctkJ3WiRndih0m",
						"provider_code": "test"
					},
					"rrn": null,
					"approval_code": null,
					"reserved_amount": null,
					"reserve_expires": null,
					"unreserved": null,
					"source": "merchant_api",
					"callback_logs": {
						"1597833098": {
							"status": "done",
							"processed": 1597833099,
							"response_code": 200,
							"transaction_status": "process_pending"
						},
						"1597833206": {
							"status": "done",
							"processed": 1597833207,
							"response_code": 200,
							"transaction_status": "processed"
						}
					}
				},
				"relationships": {
					"payment-service": {
						"data": {
							"type": "payment-services",
							"id": "payment_card_uah_hpp"
						}
					},
					"payment-method": {
						"data": {
							"type": "payment-methods",
							"id": "payment_card"
						}
					},
					"customer": {
						"data": {
							"type": "customers",
							"id": "cus_Tjhe1ufEB3kRrgWy"
						}
					}
				},
				"links": {
					"self": "/api/payment-invoices/cpi_HeSWMM9LvQonCcQc"
				}
			},
			{
				"type": "payment-invoices",
				"id": "cpi_Qtg8wyWcnSYLksFh",
				"attributes": {
					"serial_number": "Qtg8wyWcnSYLksFh",
					"status": "process_failed",
					"resolution": "expired",
					"moderation_required": false,
					"amount": 100,
					"payment_amount": 100,
					"currency": "UAH",
					"service_currency": "UAH",
					"reference_id": "05233537-7b5c-4cb8-b596-d65ec9671c67",
					"test_mode": true,
					"fee": 0,
					"deposit": 100,
					"processed": null,
					"processed_amount": null,
					"refunded_amount": null,
					"processed_fee": null,
					"processed_deposit": null,
					"metadata": {
						"key": "value",
						"merchant_url": "https://lets.doc.it"
					},
					"flow_data": {
						"action": "https://cardgate-staging.psp.name/hpp/cgi_jYwKJcItnDjnYzZj",
						"method": "GET",
						"params": [],
						"metadata": {
							"sid": "cgi_jYwKJcItnDjnYzZj",
							"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfall3S0pjSXRuRGpuWXpaaiIsImV4cCI6MTU5NzQxODU2Mn0.y9oVZZx9KKdelCNxtY3U9hhWK0R6LIZrQI0w6GvTZamnwU5c1CAJqBydhEQ1v2o5kmrklUZFSlBFjTlKAy3LBUElW4pfZfaEpixgGC7NEtXkYK8lKYJ8cYLJl-S3s2ONcH5_Nhfu5FGdY0iTa8_giLNUgUZxMGnWY6hy29pexBaYr335I7L-lhqAzwhfY-KJH6KpYGOe_-rJgR447TEdABptqlOExGdAk9lS9PS77aJwIodOV1__xbbu0PRPW__L1S06WfDBfUUoaMulbn9-GyyUNbLs-qoADl_amrkxA0qWfs6ylyOAgsARlVUPs-gh2wVtqxHilPdflXZgfPVi9i9UphiquoGQIObOXJqm5CfuStvWxLNVDIOqcx9wbbXWt9i67W0quzVteQUpCDM0EVMR0WZ-j24JEnz2sllD_Lcz0cA22hZXH2b05tPCl30OwTWX0jkBy5ZzzLVYtQnWn-OPaOPoisK9tRdouDGk1UoTvmAJh_RUin1-wXWq9Zv2VXs6XamjR1sIEbj2Vd5IagCmiKyQiLwG7Jek_lbtF-N5e9JzBeAngf-k6UmA-q6RDS-EMdryH2_qfNF3szxUHq-Yz-LVtanxq263DeA7N8ytJGspZq6MzVsMiixPAyZoVf92M0T6rnYYh23hTdJzxzGBVcov_lOb05XCAHpkG4M"
						}
					},
					"flow": "hpp",
					"payment_flow": "charge",
					"created": 1597416762,
					"updated": 1597418667,
					"payload": null,
					"description": "Invoice Example",
					"descriptor": null,
					"callback_url": "https://example.com",
					"return_url": "https://example.com",
					"original_data": [],
					"rrn": null,
					"approval_code": null,
					"reserved_amount": null,
					"reserve_expires": null,
					"unreserved": null,
					"source": "merchant_api",
					"callback_logs": {
						"1597416763": {
							"status": "done",
							"processed": 1597416763,
							"response_code": 200,
							"transaction_status": "process_pending"
						},
						"1597418666": {
							"status": "done",
							"processed": 1597418667,
							"response_code": 200,
							"transaction_status": "process_failed"
						}
					}
				},
				"relationships": {
					"payment-service": {
						"data": {
							"type": "payment-services",
							"id": "payment_card_uah_hpp"
						}
					},
					"payment-method": {
						"data": {
							"type": "payment-methods",
							"id": "payment_card"
						}
					},
					"customer": {
						"data": {
							"type": "customers",
							"id": "cus_Tjhe1ufEB3kRrgWy"
						}
					}
				},
				"links": {
					"self": "/api/payment-invoices/cpi_Qtg8wyWcnSYLksFh"
				}
			}
		]
	}

    Используемые в ответах коды состояния HTTP

    Примеры ответов с кодами и описаниями ошибок
    401 (unauthorized)
    404 (not found)
    405 (incorrect method)
    422 (validation error)
    500 (internal server error)
    {
		"errors": [
			{
				"status": "Unauthorized",
				"code": "401"
			}
		]
	}
    {
		"errors": [
			{
				"status": "Not Found",
				"code": "404"
			}
		]
	}
    {
		"errors": [
			{
				"status": "Method Not Allowed",
				"code": "405"
			}
		]
	}
    {
		"errors": [
			{
				"amount": "This value should be greater than 0."
			}
		]
	}
    {
		"errors": [
			{
				"status": "Method Not Allowed",
				"code": "405",
				"title": "internal_error",
				"detail": "Internal server error."
			}
		]
	}

    2xx Успешные

    Код Описание
    200 ОK Запрос выполнен успешно
    201 Created POST запрос на создание инвойса выполнен успешно

    4xx Ошибки на стороне клиента

    Код Тип Описание Инструкции

    400

    Bad

    Request

    		 Транспортная Запрос невалидной структуры, сервер не может его обработать Необходимо запросить статус операции (если использован правильный метод, но на запрос статуса получена 404 ошибка, можно считать запрос неуспешным и повторить операцию)

    401

    Unauthorized

    		 Авторизации Для получения запрашиваемого ответа нужна аутентификация Проверить данные авторизации. Запрос финально неуспешен. Операция не создалась на стороне платформы (если ошибка возникла при создании, не при остальных методах)

    403

    Forbidden

    		 Авторизации У клиента нет прав доступа на вызов метода Проверить данные авторизации. Запрос финально неуспешен. Операция не создалась на стороне платформы (если ошибка возникла при создании, не при остальных методах)

    404

    Not Found

    		 Валидации Сервер не может найти запрашиваемый метод или ресурс В запросе указан некорректный метод или операции не существует (при корректном запросе статуса)

    405

    Method

    Not Allowed

    		 Валидации Метод отправки запроса не может быть использован Запрос финально неуспешен. Операция не создалась на стороне платформы (если ошибка возникла при создании, не при остальных методах)

    409

    Conflict

    		 Валидации Сущность с таким идентификатором уже существует. В ответе вернется код и сообщение ошибки, в теле вернутся данные существующей операции Обработать тело ответа с ранее созданной операцией согласно бизнес-логике на стороне мерчанта

    422

    Unprocessable

    Entity

    		 Валидации Сервер не может принять запрос (некорректные данные или настройки аккаунта) Запрос финально неуспешен. Операция не создалась на стороне платформы (если ошибка возникла при создании, не при остальных методах)

    5xx Ошибки на стороне сервера

    Код Описание Инструкции

    500

    Internal

    Server

    Error

    		 Внутренняя ошибка сервера. Не гарантирует ошибку создания операции. Необходимо запросить статус операции. В случае отсутствия операции на сервере можно повторно вызвать метод создания

    502

    Bad

    Gateway

    		 Проблема обработки запроса. Определён недействительный шлюз. Не гарантирует ошибку создания операции. Необходимо запросить статус операции. В случае отсутствия операции на сервере можно повторно вызвать метод создания

    503

    Service

    Unavailable

    		 Сервер недоступен в текущий момент. Не гарантирует ошибку создания операции. Необходимо запросить статус операции. В случае отсутствия операции на сервере можно повторно вызвать метод создания

    504

    Gateway

    Timeout

    		 Сервер не смог вернуть ответ за определённый промежуток времени. Не гарантирует ошибку создания операции. Необходимо запросить статус операции. В случае отсутствия операции на сервере можно повторно вызвать метод создания
    Внимание

    Если создание операции прошло успешно, а на любой другой запрос получен ответ с 4XX или 5XX HTTP кодом — необходимо уточнять статус методом реконсиляции или через каналы коммуникации технической поддержки.

    Примечание

    При использовании Callback метода оповещения — при получении ошибок необходимо дождаться Callback или вызвать метод запроса статуса для уточнения состояния операции.

    Host-to-host интеграция для получения платежей

    Начало

    Крупные организации, выполняющие требования PCI DSS, могут использовать Host-to-host (H2H) интеграцию для получения карточных платежей.

    Отправьте заявку службе поддержки, чтобы уточнить требования и включить для Вашего аккаунта режим H2H-платежей.

    Общая схема взаимодействия

    Общая схема взаимодействия - API Документация - Cascad.com

    Создание платежного инвойса

    Endpoint: /payment-invoices

    Method: POST

    JSON
    Пример запроса для инвойса
    Пример ответа
    {
		"data": {
			"type": "payment-invoices",
			"attributes": {
			"reference_id": "{guid}",
			"description": "Payment by order#1",
			"currency": "UAH",
			"amount": 17,
			"service": "payment_card_uah_hpp",
			"return_url": "https://example.com/",
			"callback_url": "https://example.com/payments/callback"
			}
		}
	}
    {
		"data": {
		  "type": "payment-invoices",
		  "id": "cpi_eqUNbE6SpIEmRB2K",
		  "attributes": {
			 "status": "process_pending",
			 "resolution": "ok",
			 "moderation_required": false,
			 "amount": 17,
			 "payment_amount": 17,
			 "currency": "UAH",
			 "service_currency": "UAH",
			 "reference_id": "{guid}",
			 "test_mode": true,
			 "fee": 0,
			 "deposit": 17,
			 "processed": null,
			 "processed_amount": null,
			 "processed_fee": null,
			 "processed_deposit": null,
			 "metadata": [

			 ],
			 "flow_data": {
				"action": "https:\/\/our.pay_domain\/hpp\/7b3df799-5608-56fa-a26b-5a9b3c26bb5c",
				"method": "GET",
				"params": [

				],
				"metadata": {
				   "sid": "7b3df799-5608-56fa-a26b-5a9b3c26bb5c",
				   "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9...fGbuc"
				}
			 },
			 "flow": "hpp",
			 "created": 1567434682,
			 "updated": 1567434682,
			 "payload": [

			 ],
			 "description": "Payment by order#1",
			 "callback_url": "pay.cascad.com\/payments\/callback",
			 "return_url": "pay.cascad.com"
		  },
		  "relationships": {
			 "payment-service": {
				"data": {
				   "type": "payment-services",
				   "id": "payment_card_uah_hpp"
				}
			 },
			 "payment-method": {
				"data": {
				   "type": "payment-methods",
				   "id": "payment_card"
				}
			 },
			 "customer": {
				"data": null
			 }
		  },
		  "links": {
			 "self": "\/api\/payment-invoices\/cpi_eqUNbE6SpIEmRB2K"
		  }
		}
	}

    Отправка данных карты на Card Gate

    API URL: при интеграции выдаётся менеджером

    Endpoint: /payment-invoices

    Method: POST

    Авторизация: bearerToken (передается параметр token, полученный в ответ на запрос создания инвойса, объект flow_data → metadata)

    JSON
    Пример запроса с карточными данными
    Пример ответа
    {
	"data": {
		"type": "sale-operation",
		"attributes": {
		  "card_number": "5519283812030000",
		  "card_holder": "Card Holder",
		  "cvv": "123",
		  "exp_month": "10",
		  "exp_year": "35"
			}
	  }
	}
    {
	"status": "auth_required",
	"auth_mode": "3ds",
	"auth_payload": {
		  "action": "https:\/\/acs.pay_domain\/acspage\/cap?RID=8\u0026VAA=A",
		  "method": "POST",
		  "params": {
			 "MD": "999999999",
			 "PaReq": "eJxVUlFvVA2jYv2jAQfuZfoD5v2E5KfQlLFJ2jAQfuZfoD5v2E5KQqurpe5os5wRBJU6dZCX79bszlDIrUe6+zWRkwjEe0qVHL3dmbqjeATGvs6XKz2Np1GBFSxq3r684PeiZvQbwnXOj9i951XdPeC4HWHT5bV1v+3z29+Vgs\/OIi+9oe48acmxbs8VxVT7cFNkaX3+raapimUYqiZPbGz2CAOvRCP6gbytXany0njnTX07Y3Ii6VYY9u64EQNFz3J5OPlalzjc\/4nyTv63+Lo+rfR6tFtlbfnofQDCDmaXpUEdS3SmcbXhU7MLJSwQ12gwovceazvouxlVLxmX8EgKkXeDuMSs7UoPPH47\/yLbkeV+MU3SeTqst8PT5mfi9m5WZtmv+eMzCzuTzr0rcpzulYTmVbAfBLejA8KAsIlhlij6b8b+AbaDvJg=",
			 "TermUrl":"https:\/\/pay.cascad.com\/3ds-return?pid=pay_Hjh3kMlNdqE4WpOmNPCoIgFU_K1_nM"
		  }
		}
	}

    (для 3DS) Перенаправление пользователя на ACS

    В ответе на запрос /payment/sale объект auth_payload cодержит данные для 3D-Secure.

    На action URL нужно передать параметры формы params методом method.

    JSON
    "auth_payload": {
		"action": "https:\/\/acs.pay_domain\/acspage\/cap?RID=8\u0026VAA=A",
		"method": "POST",
		"params": {
		   "MD": "999999999",
		   "PaReq": "eJxVUlFvVA2jYv2jAQfuZfoD5v2E5KfQlLFJ2jAQfuZfoD5v2E5KQqurpe5os5wRBJU6dZCX79bszlDIrUe6+zWRkwjEe0qVHL3dmbqjeATGvs6XKz2Np1GBFSxq3r684PeiZvQbwnXOj9i951XdPeC4HWHT5bV1v+3z29+Vgs\/OIi+9oe48acmxbs8VxVT7cFNkaX3+raapimUYqiZPbGz2CAOvRCP6gbytXany0njnTX07Y3Ii6VYY9u64EQNFz3J5OPlalzjc\/4nyTv63+Lo+rfR6tFtlbfnofQDCDmaXpUEdS3SmcbXhU7MLJSwQ12gwovceazvouxlVLxmX8EgKkXeDuMSs7UoPPH47\/yLbkeV+MU3SeTqst8PT5mfi9m5WZtmv+eMzCzuTzr0rcpzulYTmVbAfBLejA8KAsIlhlij6b8b+AbaDvJg=",
		   "TermUrl": "https:\/\/pay.cascad.com\/3ds-return?pid=pay_Hjh3kMlNdqE4WpOmNPCoIgFU_K1_nM"
		}
	}

    Сallbacks.

    Callbacks позволяют получать уведомления, когда изменяется статус операции.

    Чтобы настроить Callbacks для операций, необходимо задать адрес в callback_url в настройках интеграции или отправлять этот параметр в запросе.

    Примечание

    Callback — асинхронная функция и не рекомендуется для задач с жестким ограничением по времени. Существует немалая вероятность, что Ваше приложение получит Callbacks не в порядке отправки или они продублируются. Для задач с жестким временным ограничением мы рекомендуем использовать реконсиляцию по API для обновления данных в системе.

    Настройка

    Для настройки Callbacks Вам нужно перейти к настройкам аккаунта и добавить значение «Callback URL».

    Запросы Callbacks

    HTTP запрос, который мы отправим на Ваш callback_url, будет обладать следующими характеристиками:

    • это будет POST запрос;
    • тело запроса будет передано в JSON API формате, как в открытом API;
    • объекты type и id обязательно будут в теле запроса (а не в url-параметре).

    Ниже пример Callbacks для инвойса платежа:

    JSON
    {
	"data": {
		 "type": "payment-invoices",
		 "id": "cpi_TV465FXkbGch3GNe",
		 "attributes": {
			"status": "processed",
			"resolution": "ok",
			"moderation_required": false,
			"amount": 3.33,
			"payment_amount": 3.33,
			"currency": "UAH",
			"service_currency": "UAH",
			"reference_id": "{guid}",
			"test_mode": false,
			"fee": 0,
			"deposit": 3.33,
			"processed": 1564153164,
			"processed_amount": 3.33,
			"processed_fee": 0,
			"processed_deposit": 3.33,
			"metadata": [

			],
			"flow_data": {
			   "action": "https:\/\/pay.cascad.com\/hpp\/{guid}",
			   "method": "GET",
			   "params": [

			   ]
			},
			"flow": "hpp",
			"created": 1564153017,
			"updated": 1564153164,
			"payload": {
			   "payment_card": {
				  "last": "1111",
				  "mask": "511111******1111",
				  "brand": "mastercard",
				  "first": "511111",
				  "issuer_name": "PUBLIC JOINT-STOCK COMPANY COMMERCIAL BANK PRIVATBANK",
				  "issuer_country": "UA"
			   }
			},
			"description": null,
			"callback_url": null
		 },
		 "relationships": {
			"payment-service": {
			   "data": {
				  "type": "payment-services",
				  "id": "payment_card_uah_hpp"
			   }
			},
			"payment-method": {
			   "data": {
				  "type": "payment-methods",
				  "id": "payment_card"
			   }
			},
			"customer": {
			   "data": null
			}
		 },
		 "links": {
			"self": "\/api\/payment-invoices\/cpi_p<...>"
		 }
		}
	}
    Примечание

    Тело запроса Callback содержит тело соответствующей операции инвойса. Статусы инвойсов описаны в руководствах: платежей, выплат

    Проверка подлинности

    Cascad подписывает данные, используя ключи в хедере запроса X-Signature.

    Алгоритм генерации: $signature = base64_encode(sha1($secret . $callbackData . $secret, true));

    где $secret— боевой («Live key») или тестовый («Test key») секретный ключ, который находится в настройках аккаунта;

    $callbackData— неформатированный JSON код.

    Примечание

    Чтобы убедиться в достоверности источника, сгенерируйте подпись используя соответствующий ключ и сравните с данными в Callback.

    Превышение времени ожидания (тайм-аут)

    Cascad выделяет три типа тайм-аутов для Callbacks:

    1. Тайм-аут соединения (Connection Timeout): граничное время для установления начального соединения с HTTP-сервером URL Callbacks.
    2. Тайм-аут чтения (Read Timeout): граничное время сообщения о прочтении данных HTTP сервера после установки соединения.
    3. Общий тайм-аут отправки Callbacks (Total Callback Timeout): в дополнение к двум предыдущим, Cascad также проверяет общее время выполнения Callbacks.

    Значения тайм-аутов:

    Тип Для тестового соединения Для боевого соединения
    Connection Timeout 10,000 мс 20,000 мс
    Read Timeout 10,000 мс 20,000 мс
    Execution Timeout 10,000 мс 60,000 мс

    Автоповтор отправки

    После успешного выполнения запроса Callbacks должен вернуться HTTP-код 200. Любые другие данные в ответе игнорируются.

    Если вернулся другой HTTP-код, значит, запрос не доставлен. По умолчанию, невыполненный запрос повторно отправляется с промежутком ожидания между попытками:

    1-й повтор запроса будет отправлен спустя 1 минуту после начальной попытки;

    2-й повтор — спустя 2 минуты после 1-го повтора;

    3-й — спустя 3 минуты после 2-го;

    4-й — спустя 4 минуты после 3-го;

    5-й — спустя 5 минут после 4-го;

    и 6-й — спустя 6 минут после 5го.

    и т.д. до 100 попыток или до получения 200 HTTP-кода

    Существует возможность настройки интервала отправки и количества попыток

    Отправьте запрос нашей службе поддержки, чтобы мы вместе подобрали наилучший вариант.

    Примечание

    Вы можете переотправить запрос c панели управления, если хотите синхронизировать данные немедленно. Для этого нужно перейти к информации о переводе, выбрать вкладку Callbacks и кликнуть кнопку Отправить заново.

    Автоповтор отправки - API Документация - Cascad.com

    Дублирование

    Из-за повторной отправки Callbacks есть вероятность, что приложение получит одни и те же данные несколько раз. Вы можете убедиться в идемпотентности операции (свойстве объекта или операции при повторном применении операции к объекту давать тот же результат, что и при первом), обнаружив такие дубликаты в данных приложения.

    Это не является проблемой, если приложение определяет идемпотентность. Для контроля используйте параметр id в данных запроса Callbacks, т.к. его значение является уникальным для операции и позволяет её идентифицировать.

    Пакетная обработка

    Мы связываем Callbacks для близких статусов. Так что, если платеж сразу же перешел из статуса created(создан) в статус invoked(в обработке) и в статус processed(обработан), вы получите только один Callback с последним по времени статусом (т.е. processed).

    Преимущество такого подхода: возможность избежать перегрузки Ваших серверов HTTP запросами и избавить Ваше приложение от необходимости усложнять логику взаимодействия с последовательными изменениями статуса. Ваше приложение должен заботить только последний статус объекта.

    Доставка не по порядку

    Callbacks могут приходить не по порядку из-за неполадок сети или сбоев отправки. Вы все равно можете установить правильную последовательность событий, ориентируясь на атрибут updated в Callbacks. updated — это временная отметка, которая обновляется с каждым изменением ресурса.

    IP-адреса

    Для повышения безопасности взаимодействия между платформой Cascad и Вашим сервером, необходимо использовать белый список IP-адресов.

    Узнать детальнее о доменах и IP адресах

    API Документация - Cascad.com

    API документация не имеет
    адаптивной версии.

    Откройте страницу на вашем ПК
    или ноутбуке, с разрешением экрана
    от 1200px по ширине.

    вернуться на главную

    Консультация.

    Нажимая «Отправить», я подтверждаю что ознакомился с Публичным договором и Публичной офертой, и принимаю условия.

    Спасибо за вашу заявку.

    Мы свяжемся с вами в ближайшее время
    и ответим на ваши вопросы .

    Понятно