Особистий кабінет Вхід
Укр
Вхід

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 містить дані для 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-кода

    Існує можливість налаштування інтервалу відправки та кількості спроб

    Надішліть запит до нашої служби підтримки, щоб ми разом підібрали найкращий варіант..

    Примітка

    Ви можете перевідправити запит з панелі управління, якщо хочете синхронізувати дані негайно. Для цього потрібно перейти до інформації про переведення, вибрати вкладку 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 по ширині.

    Повернутися

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

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

    Дякуємо за вашу заявку.

    Ми зв'яжемось з вами в найближчий час
    і відповімо на ваші запитання.

    Зрозуміло