IZI + CloudPayments Integration

IZI + CloudPayments Integration

CloudPayments is one of the supported payment gateways in IZI. Once connected, club clients can top up their balance by card, Apple Pay, or Google Pay directly from the CRM or mobile app — no redirect to third-party pages.

Prerequisites

• Active CloudPayments merchant account (KYC completed)
• Public ID and API Secret from CloudPayments dashboard
• IZI API token with OWNER or ADMIN role at the organization level

Step 1 — Configure in IZI API

mutation ConfigurePaymentGateway($input: PaymentGatewayInput!) {
  configurePaymentGateway(input: $input) {
    id
    type
    isActive
    publicId
  }
}

{
  "input": {
    "organizationId": "org_abc123",
    "type": "CLOUDPAYMENTS",
    "publicId": "pk_your_public_id",
    "apiSecret": "your_api_secret",
    "description": "Main acquirer"
  }
}

apiSecret is stored encrypted and not returned in responses. To update it, call the mutation again.

Step 2 — CloudPayments Webhook

In the CloudPayments dashboard: Settings → Notifications → Check and Pay.

URL for both notification types:

https://api.izi.is/payments/cloudpayments/callback

IZI handles Check and Pay notifications. On Check it validates the amount and client existence. On Pay it credits the balance and creates a transaction.

Step 3 — Initiate a Payment via API

To trigger a client balance top-up through the widget:

mutation InitiateTopUp($input: InitiatePaymentInput!) {
  initiateTopUpPayment(input: $input) {
    paymentUrl
    transactionId
    expiresAt
  }
}

{
  "input": {
    "clientId": "client_xyz",
    "clubId": "club_abc123",
    "amount": 500,
    "returnUrl": "https://yourapp.example.com/payment/success",
    "description": "Balance top-up"
  }
}

The response includes paymentUrl to redirect the client. After payment, CloudPayments sends a notification to IZI and the balance is credited automatically.

Step 4 — Testing

CloudPayments test cards:

Card	Result
4111 1111 1111 1111	Successful payment
4444 4444 4444 4441	Bank decline
5500 0000 0000 0004	3DS confirmation

Test mode is enabled in the CloudPayments dashboard. All test transactions don’t charge real money but go through the full IZI cycle including balance credit on a test client profile.

Tracking Payment Status

query PaymentStatus($transactionId: ID!) {
  payment(id: $transactionId) {
    id
    status
    amount
    clientId
    createdAt
    confirmedAt
    gatewayTransactionId
  }
}

Statuses: PENDING → AUTHORIZED → CONFIRMED | CANCELLED | FAILED.

Or subscribe via IZI webhook for PAYMENT_RECEIVED:

mutation CreatePaymentWebhook {
  createWebhook(input: {
    url: "https://your-service.example.com/payments",
    events: ["PAYMENT_RECEIVED", "PAYMENT_FAILED"]
  }) {
    id
    secret
  }
}

Refunds

mutation RefundPayment($input: RefundInput!) {
  refundPayment(input: $input) {
    success
    refundId
    amount
  }
}

{
  "input": {
    "transactionId": "txn_abc123",
    "amount": 500,
    "reason": "Client request"
  }
}

Partial refunds are supported. amount cannot exceed the original transaction amount.

Related Pages

• Authentication & Tokens — token for mutations
• Webhooks — PAYMENT_RECEIVED events
• API Error Codes — payment operation errors
• SDK Examples — ready wrappers for payment operations