IZI + CloudPayments Integration
Bu içerik henüz dilinizde mevcut değil.
IZI + CloudPayments Integration
Section titled “IZI + CloudPayments Integration”CloudPayments is one of the payment providers IZI supports. Once connected, a player links a card or SBP in the mobile app and tops up their club balance.
The provider is usually connected in the CRM interface. Below is what happens at the API level.
Prerequisites
Section titled “Prerequisites”- A CloudPayments merchant account
- Public ID and API Secret from the CloudPayments dashboard
- A CRM token of an employee whose role has the permission to create acquiring (
PAYMENT_PROVIDER_CREATE)
Step 1 — Add the Provider in IZI
Section titled “Step 1 — Add the Provider in IZI”mutation CreateCloudPaymentsProvider($input: CreatePaymentProviderInput!) { createPaymentProvider(input: $input) { organizationPaymentProvider { id providerCode webhookUrl enabledMethods credentialsStatus { isConfigured } } }}{ "input": { "organizationId": "2a7d9c41-...", "name": "Primary acquiring", "credentials": { "CLOUDPAYMENTS": { "publicId": "pk_your_public_id", "apiSecret": "your_api_secret" } } }}apiSecret is not returned in the response: the provider type carries no secrets at all. credentialsStatus.isConfigured does not check the credentials themselves — it means “the provider is not deleted” and is always true for a live provider. A mistake in publicId or apiSecret shows up only as a declined payment or a notification that was not accepted. Change credentials with the updatePaymentProvider mutation.
Step 2 — Assign the Provider to a Club
Section titled “Step 2 — Assign the Provider to a Club”A club picks a provider separately for each payment method. This needs the PAYMENT_METHOD_CONFIG_EDIT permission:
mutation AssignClubPaymentMethods($input: SetClubPaymentMethodConfigsInput!) { setClubPaymentMethodConfigs(input: $input) { items { method organizationPaymentProviderId } }}{ "input": { "clubId": "8b0f8c3e-...", "patches": [ { "method": "CARD", "organizationPaymentProviderId": "5e3b1f20-..." } ] }}patches is the club’s full desired state, not a partial update: every existing config of the club is deleted and rebuilt from patches. Send all the payment methods the club needs, or the call will wipe the rest. To disable a method, send it with organizationPaymentProviderId: null. Changing a method’s provider unlinks the players’ cards and SBP accounts that were linked through the previous one.
When CloudPayments is assigned to the card (CARD) method, IZI assigns it to SBP in the same call — unless patches carries a separate SBP patch naming another provider. The club’s previous SBP setting is not consulted: the state is set from scratch. SBP cannot be switched off for a club whose CARD provider is CloudPayments — an SBP patch with organizationPaymentProviderId: null is overridden by this mirror.
Step 3 — IZI Addresses for CloudPayments
Section titled “Step 3 — IZI Addresses for CloudPayments”All addresses live on the API host of the club’s contour (contour addresses). :gateId is the provider id from step 1.
| Address | Who calls it | Purpose |
|---|---|---|
POST /webhook/cloudpayments/:gateId | CloudPayments server | Payment notifications |
GET /billing-widget/cloudpayments | Player’s browser (from the app) | Page with the CloudPayments widget for linking card/SBP |
GET /billing-callback/cloudpayments/:gateId | Player’s browser after widget | Return from the widget: IZI reconciles the linking status |
GET /billing-3ds/cloudpayments/:gateId | Player’s browser after topUp | 3-D Secure page: auto-submits the form to the bank’s ACS. This address arrives in the redirectUrl of the topUp response |
POST /billing-3ds/cloudpayments/:gateId/return | The bank’s ACS | 3-D Secure return: IZI forwards the result to CloudPayments and finalizes the payment |
The ready notification address is returned in the provider’s webhookUrl field — set exactly that in the CloudPayments dashboard.
Addresses like /payments/... in the CloudPayments documentation belong to CloudPayments’ own API: IZI calls them, not the other way round.
What IZI Does with Notifications
Section titled “What IZI Does with Notifications”- Every notification’s signature is checked against the
Content-HMACheader: HMAC-SHA256 of the request body keyed with the API Secret. The check runs after the reply: IZI answers every notification with200 {"code": 0}immediately, and a notification with a wrong or missingContent-HMACis then dropped silently. In the CloudPayments dashboard this looks like successful delivery, so a key mismatch shows up only as top-ups not being credited. - Pay — IZI confirms the payment and credits the top-up; when a card is being linked, it stores the card token.
- Fail — IZI marks the payment as failed.
- Check, Refund, Cancel — IZI answers
{"code": 0}and changes nothing.
How a Player Payment Goes
Section titled “How a Player Payment Goes”- The player’s app calls
linkPaymentSourceByUrl(clubId, method)and opens the returnedredirectUrl— the/billing-widget/cloudpaymentspage. - To link a card, the widget places a 10 RUB hold. After the Pay notification, IZI stores the card token and releases the hold.
- The browser returns to
/billing-callback/cloudpayments/:gateId, and IZI reconciles the linking status with CloudPayments. - A balance top-up is the
topUpmutation with the linked payment method. If the bank requires 3-D Secure,topUpreturns aredirectUrlto/billing-3ds/cloudpayments/:gateId— open it, and the payment is finalized after the 3-D Secure return. IZI learns the payment outcome from the Pay or Fail notification.
linkPaymentSourceByUrl and topUp are available only with a player token (PLAYER).
Testing
Section titled “Testing”Test mode and test cards are on the CloudPayments side: enable test mode in their dashboard and use the cards from the CloudPayments documentation.
Related Pages
Section titled “Related Pages”- Authentication & Tokens — token for calling mutations
- API Error Codes — error format
- SDK Examples — ready wrappers in JS and Python
Sık sorulan sorular
Which CloudPayments payment methods work through IZI?
Card (CARD) and the Russian Faster Payments System (SBP). Apple Pay through CloudPayments is not supported in IZI.
Can I use multiple payment gateways simultaneously?
Yes. An organization can have several acquiring providers, and a club picks a provider separately for each payment method.
IZI LLC (ООО «ИЗИ»), TIN 7842227686, OGRN 1257800012249, office 1, premises 3-N, lit. A, 15-17 Perekupnoy lane, Saint Petersburg, 191024, Russia, admin@izi.is · Cookie settings