> ## Documentation Index
> Fetch the complete documentation index at: https://docs.splashpay.co.tz/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Payments

> Accept Visa and Mastercard payments securely using the SplashPay Card Payments API.

# Card Payments

The Card Payments API enables merchants to securely accept payments from customers using **Visa**, **Mastercard**, and other supported bank cards.

SplashPay provides a hosted payment page that securely captures card details and processes payments through a PCI DSS compliant payment gateway.

<Card title="Hosted Checkout" icon="credit-card">
  Customers are redirected to a secure payment page hosted by SplashPay's payment provider. Card details are never transmitted through your servers.
</Card>

***

## Endpoint

```http theme={null}
POST /payments/card
```

***

## Base URL

<Tabs>
  <Tab title="Sandbox">
    ```bash theme={null}
    https://sandbox-api.splashpay.co.tz/api/v1
    ```

    Use this environment for development and testing.
  </Tab>

  <Tab title="Production">
    ```bash theme={null}
    https://api.splashpay.co.tz/api/v1
    ```

    Use this environment for live transactions.
  </Tab>
</Tabs>

***

# Request Body

| Field              | Type   | Required | Description                                               |
| ------------------ | ------ | :------: | --------------------------------------------------------- |
| reference          | string |    Yes   | Unique merchant payment reference                         |
| buyer\_name        | string |    Yes   | Customer full name                                        |
| buyer\_email       | string |    Yes   | Customer email address                                    |
| buyer\_phone       | string |    Yes   | Customer phone number                                     |
| amount             | number |    Yes   | Payment amount                                            |
| currency           | string |    Yes   | Currency (`TZS`)                                          |
| redirect\_url      | string |    Yes   | URL where customer is redirected after successful payment |
| cancel\_url        | string |    Yes   | URL where customer is redirected if payment is cancelled  |
| billing\_firstname | string |    Yes   | Billing first name                                        |
| billing\_lastname  | string |    Yes   | Billing last name                                         |
| billing\_address   | string |    Yes   | Billing address                                           |
| billing\_city      | string |    Yes   | Billing city                                              |
| billing\_state     | string |    Yes   | Billing state                                             |
| billing\_postcode  | string |    Yes   | Billing postcode                                          |
| billing\_country   | string |    Yes   | ISO 3166-1 Alpha-2 country code                           |
| billing\_phone     | string |    Yes   | Billing phone number                                      |

***

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.splashpay.co.tz/api/v1/payments/card \
    --header "Content-Type: application/json" \
    --header "X-API-KEY: pk_live_xxxxxxxxxxxxx" \
    --header "X-API-SECRET: sk_live_xxxxxxxxxxxxx" \
    --header "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
    --data '{
      "reference":"CIR-6723sg",
      "buyer_email":"john.doe@example.com",
      "buyer_name":"John Doe",
      "buyer_phone":"255744123456",
      "amount":1000,
      "currency":"TZS",
      "redirect_url":"https://example.com",
      "cancel_url":"https://example.com",
      "billing_firstname":"John",
      "billing_lastname":"Doe",
      "billing_address":"123 Main St",
      "billing_city":"Dar es Salaam",
      "billing_state":"Tanzania",
      "billing_postcode":"67116",
      "billing_country":"TZ",
      "billing_phone":"255744123456"
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.splashpay.co.tz/api/v1/payments/card',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-KEY': process.env.SPLASHPAY_KEY,
        'X-API-SECRET': process.env.SPLASHPAY_SECRET,
        'Idempotency-Key': crypto.randomUUID(),
      },
      body: JSON.stringify({
        reference: 'CIR-6723sg',
        buyer_email: 'john.doe@example.com',
        buyer_name: 'John Doe',
        buyer_phone: '255744123456',
        amount: 1000,
        currency: 'TZS',
        redirect_url: 'https://example.com',
        cancel_url: 'https://example.com',
        billing_firstname: 'John',
        billing_lastname: 'Doe',
        billing_address: '123 Main St',
        billing_city: 'Dar es Salaam',
        billing_state: 'Tanzania',
        billing_postcode: '67116',
        billing_country: 'TZ',
        billing_phone: '255744123456'
      }),
    }
  );

  const payment = await response.json();
  ```

  ```python Python theme={null}
  import uuid
  import requests

  response = requests.post(
      "https://api.splashpay.co.tz/api/v1/payments/card",
      headers={
          "Content-Type": "application/json",
          "X-API-KEY": "YOUR_API_KEY",
          "X-API-SECRET": "YOUR_API_SECRET",
          "Idempotency-Key": str(uuid.uuid4())
      },
      json={
          "reference":"CIR-6723sg",
          "buyer_email":"john.doe@example.com",
          "buyer_name":"John Doe",
          "buyer_phone":"255744123456",
          "amount":1000,
          "currency":"TZS",
          "redirect_url":"https://example.com",
          "cancel_url":"https://example.com",
          "billing_firstname":"John",
          "billing_lastname":"Doe",
          "billing_address":"123 Main St",
          "billing_city":"Dar es Salaam",
          "billing_state":"Tanzania",
          "billing_postcode":"67116",
          "billing_country":"TZ",
          "billing_phone":"255744123456"
      }
  )

  print(response.json())
  ```
</CodeGroup>

***

# Successful Response

```json theme={null}
{
  "status": "success",
  "code": "PAYMENT_INITIATED",
  "message": "Payment initiated",
  "data": {
    "merchant_id": 2,
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "customer_phone": "255744123456",
    "reference": "CIR-6723sg",
    "amount": "1000.00",
    "fee": 29,
    "net_amount": 971,
    "currency": "TZS",
    "source": "api",
    "payment_method": "card",
    "provider": "selcom",
    "provider_reference": "S20618123473",
    "redirect_url": "https://example.com",
    "cancel_url": "https://example.com",
    "payment_gateway_url": "https://...",
    "status": "pending",
    "metadata": null,
    "created_at": "2026-07-03T11:03:09Z",
    "processing_at": "2026-07-03T14:03:09Z"
  },
  "meta": [],
  "request_id": "ee0cc9bf-9298-448e-a757-8c399e8c2f11"
}
```

***

# Redirect Customer

After receiving the response, redirect your customer to the URL provided in the `payment_gateway_url` field.

> **Note**
>
> The `payment_gateway_url` may be Base64 encoded. Decode it before redirecting the customer if required by your integration.

Example

```javascript theme={null}
window.location.href = payment.data.payment_gateway_url;
```

***

# Payment Status

| Status     | Description                                   |
| ---------- | --------------------------------------------- |
| pending    | Waiting for customer to complete card payment |
| processing | Payment is being processed                    |
| success    | Payment completed successfully                |
| failed     | Payment failed                                |
| cancelled  | Customer cancelled the payment                |
| expired    | Payment session expired                       |

***

# Webhook Payload

```json theme={null}
{
  "event": "payment.success",
  "created_at": "2026-07-03T14:10:12Z",
  "data": {
    "reference": "CIR-6723sg",
    "amount": "1000.00",
    "fee": "29.00",
    "net_amount": "971.00",
    "currency": "TZS",
    "status": "success",
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "customer_phone": "255744123456",
    "payment_method": "card",
    "provider": "selcom",
    "provider_reference": "S20618123473",
    "metadata": null
  }
}
```

***

# Error Responses

## Invalid Request

```json theme={null}
{
  "status": "error",
  "code": "INVALID_REQUEST",
  "message": "The request payload is invalid."
}
```

## Authentication Failed

```json theme={null}
{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid API credentials."
}
```

## Duplicate Request

```json theme={null}
{
  "status": "error",
  "code": "DUPLICATE_REQUEST",
  "message": "A request with this Idempotency-Key has already been processed."
}
```

***

# Best Practices

<Steps>
  <Step title="Use HTTPS">
    Always provide secure HTTPS URLs for `redirect_url` and `cancel_url`.
  </Step>

  <Step title="Generate a Unique Reference">
    Every payment request should use a unique merchant reference.
  </Step>

  <Step title="Use Idempotency Keys">
    Reuse the same `Idempotency-Key` only when retrying the same request.
  </Step>

  <Step title="Handle Webhooks">
    Do not rely solely on the customer's browser redirect. Update payment status using webhook notifications.
  </Step>

  <Step title="Store the SplashPay Reference">
    Store both the merchant reference and the provider reference for reconciliation and customer support.
  </Step>
</Steps>

***

# Next Steps

<CardGroup cols={2}>
  <Card title="Payment Status" href="/collections/status" icon="circle-check">
    Retrieve the latest status of a card payment.
  </Card>

  <Card title="Webhooks" href="/collections/webhooks" icon="webhook">
    Receive real-time payment notifications.
  </Card>
</CardGroup>