> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.stakaba.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.stakaba.com/_mcp/server.

# Card Payments

Accept Visa and Mastercard through a Stakaba-hosted, PCI-DSS certified checkout page. Your server creates the payment and gets back a `checkoutUrl` — redirect the customer there to enter their card details.

## How it works

1. Your server calls `POST /api/v1/payments/card`
2. Stakaba creates a pending transaction and returns a `checkoutUrl`
3. You redirect the customer to `checkoutUrl`
4. The customer enters their card on the hosted page
5. Stakaba sends a webhook to your `notifyUrl` when the payment settles
6. The customer is redirected back to your `returnUrl`

## Create a card payment

```http
POST /api/v1/payments/card
x-api-key: sk_live_...
Content-Type: application/json
```

```json
{
  "grossAmount": 120000,
  "currency": "TZS",
  "customerEmail": "jane@example.com",
  "customerName": "Jane Doe",
  "customerPhone": "255742000331",
  "billingAddress": "Dar es Salaam",
  "postalCode": "00000",
  "metadata": {
    "orderId": "ORD-2026-001"
  }
}
```

**Response:**

```json
{
  "checkoutUrl": "https://checkout.stakaba.com/pay/...",
  "internalReference": "C_A1B2C3D4"
}
```

Redirect the customer to `checkoutUrl` immediately.

## Parameters

| Field            | Type   | Required | Description                                      |
| ---------------- | ------ | -------- | ------------------------------------------------ |
| `grossAmount`    | number | Yes      | Amount in TZS (e.g. `120000` = TSh 120,000)      |
| `currency`       | string | No       | Always `TZS`                                     |
| `customerEmail`  | string | Yes      | Customer email for the receipt                   |
| `customerName`   | string | Yes      | Customer full name                               |
| `customerPhone`  | string | Yes      | Customer phone in `255XXXXXXXXX` format          |
| `billingAddress` | string | No       | Billing address                                  |
| `postalCode`     | string | No       | Postal code                                      |
| `metadata`       | object | No       | Your custom key-value data, returned in webhooks |

## Checking payment status

Use the `internalReference` to look up the transaction:

```http
GET /api/v1/transactions/C_A1B2C3D4
x-api-key: sk_live_...
```

Or receive it automatically via [webhook](/webhooks).

## Supported cards

Visa and Mastercard. The checkout page is PCI-DSS Level 1 compliant — Stakaba never stores raw card numbers.