Payments API

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

The Payment Object

Payment Object

{
  "id": "pay_abc123def456",
  "object": "payment",
  "amount": 5000,
  "currency": "GHS",
  "status": "succeeded",
  "payment_method": "mobile_money",
  "provider": "mtn",
  "phone": "0241234567",
  "description": "Order #1234",
  "customer": "cus_xyz789",
  "metadata": {
    "order_id": "1234"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:45Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the payment
`object`	string	Always `"payment"`
`amount`	integer	Amount in pesewas (smallest currency unit)
`currency`	string	Three-letter ISO currency code (`GHS`)
`status`	string	Payment status: `pending`, `processing`, `succeeded`, `failed`
`payment_method`	string	Payment method type: `mobile_money`, `card`, `bank_transfer`
`provider`	string	Mobile money provider: `mtn`, `telecel`, `airteltigo`
`phone`	string	Customer's phone number
`description`	string	Description of the payment
`customer`	string	ID of the customer (if attached)
`metadata`	object	Custom key-value pairs
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Create a Payment

Creates a new payment request.

POST /v1/payments

Request Body

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in pesewas
`currency`	string	Yes	Currency code (`GHS`)
`payment_method`	string	Yes	`mobile_money`, `card`, or `bank_transfer`
`provider`	string	Yes*	Required for mobile money: `mtn`, `telecel`, `airteltigo`
`phone`	string	Yes*	Customer phone number (for mobile money)
`description`	string	No	Payment description
`customer`	string	No	Customer ID to attach
`metadata`	object	No	Custom metadata
`idempotency_key`	string	No	Unique key to prevent duplicate payments

curl -X POST https://api.44.200.142.19.nip.io/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "GHS",
    "payment_method": "mobile_money",
    "provider": "mtn",
    "phone": "0241234567",
    "description": "Order #1234",
    "metadata": {
      "order_id": "1234"
    }
  }'

const payment = await paygate.payments.create({
  amount: 5000,
  currency: 'GHS',
  payment_method: 'mobile_money',
  provider: 'mtn',
  phone: '0241234567',
  description: 'Order #1234',
  metadata: {
    order_id: '1234'
  }
})

payment = client.payments.create(
    amount=5000,
    currency='GHS',
    payment_method='mobile_money',
    provider='mtn',
    phone='0241234567',
    description='Order #1234',
    metadata={'order_id': '1234'}
)

$payment = $paygate->payments->create([
    'amount' => 5000,
    'currency' => 'GHS',
    'payment_method' => 'mobile_money',
    'provider' => 'mtn',
    'phone' => '0241234567',
    'description' => 'Order #1234',
    'metadata' => ['order_id' => '1234']
]);

Response

{
  "id": "pay_abc123def456",
  "object": "payment",
  "amount": 5000,
  "currency": "GHS",
  "status": "pending",
  "payment_method": "mobile_money",
  "provider": "mtn",
  "phone": "0241234567",
  "description": "Order #1234",
  "metadata": {
    "order_id": "1234"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Retrieve a Payment

Retrieves a payment by ID.

GET /v1/payments/:id

curl https://api.44.200.142.19.nip.io/v1/payments/pay_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const payment = await paygate.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
`ending_before`	string	Cursor for pagination
`status`	string	Filter by status
`customer`	string	Filter by customer ID
`created[gte]`	string	Filter by creation date
`created[lte]`	string	Filter by creation date

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

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

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

Response

{
  "object": "list",
  "data": [
    {
      "id": "pay_abc123def456",
      "object": "payment",
      "amount": 5000,
      "status": "succeeded",
      ...
    }
  ],
  "has_more": true,
  "url": "/v1/payments"
}

Cancel a Payment

Cancels a pending payment.

POST /v1/payments/:id/cancel

You can only cancel payments that are in pending status. Once a payment starts processing, it cannot be cancelled.

curl -X POST https://api.44.200.142.19.nip.io/v1/payments/pay_abc123def456/cancel \
  -H "Authorization: Bearer sk_test_..."

const payment = await paygate.payments.cancel('pay_abc123def456')

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

Payments

On this page