Dynamic TANQR

The Dynamic TANQR API enables merchants to generate a unique QR code for every payment transaction. Customers can scan the QR code using any participating banking or mobile banking application that supports the Tanzania National QR (TANQR) standard. Unlike Static QR codes, Dynamic QR codes are generated per transaction and include the payment amount and transaction reference.

Dynamic QR Payments

Generate a unique QR code for every payment and receive real-time payment notifications through webhooks.

Endpoint

POST /payments/dynamic-qr

Base URL

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

Request Body

Field	Type	Required	Description
reference	string	Yes	Unique merchant 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`)
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 Country Code
billing_phone	string	Yes	Billing phone number

Example Request

curl --request POST \
  --url https://api.splashpay.co.tz/api/v1/payments/dynamic-qr \
  --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-6723e8ss6",
    "buyer_email":"john.doe@example.com",
    "buyer_name":"John Doe",
    "buyer_phone":"255744123456",
    "amount":1000,
    "currency":"TZS",
    "billing_firstname":"John",
    "billing_lastname":"Doe",
    "billing_address":"Bwawani, Mkonze",
    "billing_city":"Dodoma",
    "billing_state":"Tanzania",
    "billing_postcode":"67116",
    "billing_country":"TZ",
    "billing_phone":"255744123456"
}'

const response = await fetch(
  'https://api.splashpay.co.tz/api/v1/payments/dynamic-qr',
  {
    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-6723e8ss6',
      buyer_email: 'john.doe@example.com',
      buyer_name: 'John Doe',
      buyer_phone: '255744123456',
      amount: 1000,
      currency: 'TZS',
      billing_firstname: 'John',
      billing_lastname: 'Doe',
      billing_address: 'Bwawani, Mkonze',
      billing_city: 'Dodoma',
      billing_state: 'Tanzania',
      billing_postcode: '67116',
      billing_country: 'TZ',
      billing_phone: '255744123456'
    }),
  }
);

const payment = await response.json();

import uuid
import requests

response = requests.post(
    "https://api.splashpay.co.tz/api/v1/payments/dynamic-qr",
    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-6723e8ss6",
        "buyer_email":"john.doe@example.com",
        "buyer_name":"John Doe",
        "buyer_phone":"255744123456",
        "amount":1000,
        "currency":"TZS",
        "billing_firstname":"John",
        "billing_lastname":"Doe",
        "billing_address":"Bwawani, Mkonze",
        "billing_city":"Dodoma",
        "billing_state":"Tanzania",
        "billing_postcode":"67116",
        "billing_country":"TZ",
        "billing_phone":"255744123456"
    }
)

print(response.json())

Successful Response

{
  "status": "success",
  "code": "PAYMENT_INITIATED",
  "message": "Payment initiated",
  "data": {
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "customer_phone": "255744123456",
    "reference": "CIR-6723e8ss6",
    "amount": "1000.00",
    "fee": 10,
    "net_amount": 990,
    "currency": "TZS",
    "payment_method": "tanqr",
    "provider": "selcom",
    "provider_reference": null,
    "qr": "iVBORw0KGgoAAAANSUhEUgAA...",
    "status": "pending",
    "metadata": null,
    "created_at": "2026-07-03T12:02:23Z",
    "processing_at": "2026-07-03T15:02:23Z"
  },
  "meta": [],
  "request_id": "a92e05fe-2156-4891-b659-5a9fcee3ee87"
}

QR Code

The qr field contains the generated QR code as a Base64-encoded PNG image. To display the QR code in a web browser, prepend the following prefix:

data:image/png;base64,

Example

<img src="data:image/png;base64,{qr}" alt="SplashPay TANQR" />

Payment Status

Status	Description
pending	Waiting for customer to scan and pay
processing	Payment is being processed
success	Payment completed successfully
failed	Payment failed
cancelled	Payment cancelled
expired	QR code expired before payment

Webhook Payload

{
  "event": "payment.success",
  "created_at": "2026-07-03T15:04:30Z",
  "data": {
    "reference": "CIR-6723e8ss6",
    "amount": "1000.00",
    "currency": "TZS",
    "status": "success",
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "customer_phone": "255744123456",
    "channel": "TANQR",
    "provider_reference": "1769142083",
    "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

Generate a unique reference

Every QR payment should use a unique merchant reference.

Display the QR immediately

Render the Base64 image returned in the qr field to allow the customer to scan and pay.

Use Webhooks

Update transaction status using webhook notifications instead of polling.

Verify Payment Status

If a webhook is delayed, retrieve the latest transaction status using the Payment Status endpoint.

Use Idempotency Keys

Always include a unique Idempotency-Key when generating a Dynamic TANQR.

Getting Started

Collections

Disbursements

Dynamic TANQR

Dynamic TANQR

Dynamic QR Payments

Endpoint

Base URL

Request Body

Example Request

Successful Response

QR Code

Payment Status

Webhook Payload

Error Responses

Invalid Request

Authentication Failed

Duplicate Request

Best Practices

​Dynamic TANQR

Dynamic QR Payments

​Endpoint

​Base URL

​Request Body

​Example Request

​Successful Response

​QR Code

​Payment Status

​Webhook Payload

​Error Responses

​Invalid Request

​Authentication Failed

​Duplicate Request

​Best Practices

Dynamic TANQR

Endpoint

Base URL

Request Body

Example Request

Successful Response

QR Code

Payment Status

Webhook Payload

Error Responses

Invalid Request

Authentication Failed

Duplicate Request

Best Practices