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.

Hosted Checkout

Customers are redirected to a secure payment page hosted by SplashPay’s payment provider. Card details are never transmitted through your servers.

Endpoint

POST /payments/card

Base URL

Sandbox
Production

https://sandbox-api.splashpay.co.tz/api/v1

Use this environment for development and testing.

https://api.splashpay.co.tz/api/v1

Use this environment for live transactions.

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

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"
}'

Successful Response

{
  "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

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

{
  "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

{
  "status": "error",
  "code": "INVALID_REQUEST",
  "message": "The request payload is invalid."
}

Authentication Failed

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid API credentials."
}

Duplicate Request

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

Best Practices

Use HTTPS

Always provide secure HTTPS URLs for redirect_url and cancel_url.

Generate a Unique Reference

Every payment request should use a unique merchant reference.

Use Idempotency Keys

Reuse the same Idempotency-Key only when retrying the same request.

Handle Webhooks

Do not rely solely on the customer’s browser redirect. Update payment status using webhook notifications.

Store the SplashPay Reference

Store both the merchant reference and the provider reference for reconciliation and customer support.

​Card Payments

Hosted Checkout

​Endpoint

​Base URL

​Request Body

​Example Request

​Successful Response

​Redirect Customer

​Payment Status

​Webhook Payload

​Error Responses

​Invalid Request

​Authentication Failed

​Duplicate Request

​Best Practices

​Next Steps

Payment Status

Webhooks

Card Payments

Endpoint

Base URL

Request Body

Example Request

Successful Response

Redirect Customer

Payment Status

Webhook Payload

Error Responses

Invalid Request

Authentication Failed

Duplicate Request

Best Practices

Next Steps