ข้ามไปยังเนื้อหา

IZI + CloudPayments Integration

Опубликовано: · Обновлено: (1 месяц назад)· IZI Team

เนื้อหานี้ยังไม่มีในภาษาของคุณ

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.

  • 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)
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.

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.

AddressWho calls itPurpose
POST /webhook/cloudpayments/:gateIdCloudPayments serverPayment notifications
GET /billing-widget/cloudpaymentsPlayer’s browser (from the app)Page with the CloudPayments widget for linking card/SBP
GET /billing-callback/cloudpayments/:gateIdPlayer’s browser after widgetReturn from the widget: IZI reconciles the linking status
GET /billing-3ds/cloudpayments/:gateIdPlayer’s browser after topUp3-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/returnThe bank’s ACS3-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.

  • Every notification’s signature is checked against the Content-HMAC header: HMAC-SHA256 of the request body keyed with the API Secret. The check runs after the reply: IZI answers every notification with 200 {"code": 0} immediately, and a notification with a wrong or missing Content-HMAC is 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.
  1. The player’s app calls linkPaymentSourceByUrl(clubId, method) and opens the returned redirectUrl — the /billing-widget/cloudpayments page.
  2. To link a card, the widget places a 10 RUB hold. After the Pay notification, IZI stores the card token and releases the hold.
  3. The browser returns to /billing-callback/cloudpayments/:gateId, and IZI reconciles the linking status with CloudPayments.
  4. A balance top-up is the topUp mutation with the linked payment method. If the bank requires 3-D Secure, topUp returns a redirectUrl to /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).

Test mode and test cards are on the CloudPayments side: enable test mode in their dashboard and use the cards from the CloudPayments documentation.

คำถามที่พบบ่อย

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.

About IZI