Payments API

The Payments API allows you to create, retrieve, and manage payments.

The Payment Object

Payment Object

{
  "id": "pay_abc123def456",
  "object": "payment",
  "status": "succeeded",
  "amount": 50,
  "currency": "GHS",
  "fee": 1.50,
  "net_amount": 48.50,
  "payment_method": {
    "type": "mobile_money",
    "provider": "mtn",
    "number": "024****567",
    "name": "John Doe"
  },
  "gateway_provider": "ORANGE_PAY",
  "description": "Order #1234",
  "metadata": {
    "order_id": "1234"
  },
  "provider_reference": "OP123456789",
  "failure_reason": null,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:45Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the payment
`object`	string	Always `"payment"`
`status`	string	`created`, `pending`, `processing`, `succeeded`, `failed`, `cancelled`, `refunded`, `partially_refunded`
`amount`	number	Amount in GHS
`currency`	string	Three-letter ISO currency code (`GHS`)
`fee`	number	Transaction fee in GHS
`net_amount`	number	Net amount after fees in GHS
`payment_method`	object	Payment method details
`payment_method.type`	string	`mobile_money`, `bank_transfer`, `card`, or `shika_wallet`
`payment_method.provider`	string	Provider: `mtn`, `telecel`, `airteltigo` (null for card/wallet)
`payment_method.number`	string	Masked phone/account number
`payment_method.name`	string	Account holder name
`payment_method.card_brand`	string	Card brand (for card payments, e.g., `visa`, `mastercard`)
`payment_method.card_last4`	string	Last 4 digits of card (for card payments)
`payment_method.card_expiry_month`	string	Card expiry month (for card payments)
`payment_method.card_expiry_year`	string	Card expiry year (for card payments)
`gateway_provider`	string	Payment gateway used: `ORANGE_PAY` or `CYBERSOURCE`
`description`	string	Description of the payment
`metadata`	object	Custom key-value pairs
`provider_reference`	string	Provider transaction reference
`failure_reason`	string	Error message if failed
`created_at`	string	ISO 8601 timestamp
`completed_at`	string	Completion timestamp

Create a Payment

Creates a new payment request.

POST /v1/payments

Request Body

Parameter	Type	Required	Description
`amount`	number	Yes	Amount in GHS (e.g., `50` for GHS 50.00)
`currency`	string	No	Currency code (default: `GHS`)
`payment_method`	object	Yes	Payment method details
`payment_method.type`	string	Yes	`mobile_money`, `bank_transfer`, or `card`
`payment_method.phone_number`	string	Yes*	Phone number (for mobile money)
`payment_method.provider`	string	No	Provider code (auto-detected from phone): `mtn`, `telecel`, `airteltigo`
`payment_method.account_number`	string	Yes*	Account number (for bank transfer)
`payment_method.bank_code`	string	Yes*	Bank code (for bank transfer)
`payment_method.token`	string	Yes*	Payment token from Flex Microform (for card)
`payment_method.cardholder_name`	string	No	Cardholder name (for card)
`description`	string	No	Payment description
`metadata`	object	No	Custom metadata

Use the X-Idempotency-Key header to prevent duplicate payments.

curl -X POST https://api.shikacreators.com/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "currency": "GHS",
    "payment_method": {
      "type": "mobile_money",
      "phone_number": "0241234567"
    },
    "description": "Order #1234",
    "metadata": {
      "order_id": "1234"
    }
  }'

const payment = await shikacreators.payments.create({
  amount: 50,
  currency: 'GHS',
  payment_method: {
    type: 'mobile_money',
    phone_number: '0241234567'
  },
  description: 'Order #1234',
  metadata: {
    order_id: '1234'
  }
})

payment = client.payments.create(
    amount=50,
    currency='GHS',
    payment_method={
        'type': 'mobile_money',
        'phone_number': '0241234567'
    },
    description='Order #1234',
    metadata={'order_id': '1234'}
)

$payment = $shikacreators->payments->create([
    'amount' => 50,
    'currency' => 'GHS',
    'payment_method' => [
        'type' => 'mobile_money',
        'phone_number' => '0241234567'
    ],
    'description' => 'Order #1234',
    'metadata' => ['order_id' => '1234']
]);

Response

{
  "id": "pay_abc123def456",
  "object": "payment",
  "status": "created",
  "amount": 50,
  "currency": "GHS",
  "fee": 1.50,
  "net_amount": 48.50,
  "payment_method": {
    "type": "mobile_money",
    "provider": "mtn",
    "number": "024****567",
    "name": null
  },
  "gateway_provider": "ORANGE_PAY",
  "description": "Order #1234",
  "metadata": {
    "order_id": "1234"
  },
  "provider_reference": null,
  "failure_reason": null,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": null
}

Retrieve a Payment

Retrieves a payment by ID.

GET /v1/payments/:id

curl https://api.shikacreators.com/v1/payments/pay_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const payment = await shikacreators.payments.retrieve('pay_abc123def456')

payment = client.payments.retrieve('pay_abc123def456')

List Payments

Returns a list of payments.

GET /v1/payments

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100, default 10)
`starting_after`	string	Cursor for pagination
`status`	string	Filter by status

curl "https://api.shikacreators.com/v1/payments?limit=10&status=succeeded" \
  -H "Authorization: Bearer sk_test_..."

const payments = await shikacreators.payments.list({
  limit: 10,
  status: 'succeeded'
})

payments = client.payments.list(limit=10, status='succeeded')

Response

{
  "object": "list",
  "data": [
    {
      "id": "pay_abc123def456",
      "object": "payment",
      "status": "succeeded",
      "amount": 50,
      "currency": "GHS",
      "fee": 1.50,
      "net_amount": 48.50,
      "payment_method": {
        "type": "mobile_money",
        "provider": "mtn",
        "number": "024****567"
      },
      ...
    }
  ],
  "has_more": true,
  "url": "/v1/payments"
}

Payments with payment_method.type: "shika_wallet" are initiated by Shika Creators consumer app users scanning your merchant QR code. These payments are settled instantly from the consumer's Shika wallet to your merchant balance.

Shika Wallet payments are created through the consumer app, not through the Payments API directly. You cannot create a shika_wallet payment via POST /v1/payments. They appear in your payment list with payment_method.type: "shika_wallet". No external provider is involved — settlement is instant.

How it works

Generate a QR code using the QR Codes API
Display the QR code at your point of sale or in your application
The consumer scans it with the Shika Creators app and confirms payment
Funds are instantly credited to your merchant balance
You receive a payment.completed webhook event

Shika Wallet Payment Object

{
  "id": "pay_abc123def456",
  "object": "payment",
  "status": "succeeded",
  "amount": 50,
  "currency": "GHS",
  "fee": 0.60,
  "net_amount": 49.40,
  "payment_method": {
    "type": "shika_wallet",
    "provider": null,
    "number": "acc_xxx",
    "name": "John Doe"
  },
  "gateway_provider": null,
  "description": "Shika Wallet payment via QR",
  "metadata": {
    "qr_code_id": "qr_abc123",
    "consumer_account_id": "acc_xxx",
    "payment_type": "shika_wallet_qr"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:00Z"
}

Payment Statuses

Status	Description
`created`	Payment has been created
`pending`	Payment is pending customer authorization
`processing`	Payment is being processed
`succeeded`	Payment was successful
`failed`	Payment failed
`cancelled`	Payment was cancelled
`refunded`	Payment was fully refunded
`partially_refunded`	Payment was partially refunded

Webhook Events

Event	Description
`payment.created`	Payment was created
`payment.pending`	Payment is pending authorization
`payment.completed`	Payment was successful
`payment.failed`	Payment failed

app.post('/webhooks', (req, res) => {
  const event = Webhook.constructEvent(req.body, signature, secret)

  switch (event.type) {
    case 'payment.completed':
      const payment = event.data.object
      console.log(`Payment ${payment.id} completed!`)
      break
    case 'payment.failed':
      const failedPayment = event.data.object
      console.log(`Payment failed: ${failedPayment.failure_reason}`)
      break
  }

  res.json({ received: true })
})

Payments

Payments API

The Payment Object

Attributes

Create a Payment

Request Body

Response

Retrieve a Payment

List Payments

Query Parameters

Response

Shika Wallet Payments

How it works

Shika Wallet Payment Object

Payment Statuses

Webhook Events

On this page