# Card Payments

## Initiate Card Payment

Postman Collection 

For more header and response codes descriptions expand the link below.

## Initiate Card Payment.

<mark style="color:green;">`POST`</mark> `https://api.chpter.co/v1/initiate/card-payment`

Send a request and get a checkout url to complete the card payment.

#### Headers

| Name                                      | Type   | Description            |
| ----------------------------------------- | ------ | ---------------------- |
| Api-Key<mark style="color:red;">\*</mark> | String | Your chpter Public Key |
| Content-Type                              | String | application/json       |

#### Request Body

| Name                                                     | Type         | Description                           |
| -------------------------------------------------------- | ------------ | ------------------------------------- |
| customer\_details<mark style="color:red;">\*</mark>      | Object       | Customer Details                      |
| full\_name<mark style="color:red;">\*</mark>             | String       | Customer Name                         |
| products<mark style="color:red;">\*</mark>               | List / Array | Product Details                       |
| location<mark style="color:red;">\*</mark>               | String       | Customer Location                     |
| email<mark style="color:red;">\*</mark>                  | String       | Customer Email                        |
| phone\_number<mark style="color:red;">\*</mark>          | String       | Customer PhoneNumber                  |
| unit\_price<mark style="color:red;">\*</mark>            | Float        | Product Price                         |
| quantity<mark style="color:red;">\*</mark>               | Integer      | Product Quantity                      |
| product\_name<mark style="color:red;">\*</mark>          | String       | Product Name                          |
| digital\_link                                            | String       | Product Digital Link                  |
| amount<mark style="color:red;">\*</mark>                 | Object       | Object with Amount Details            |
| discount\_fee<mark style="color:red;">\*</mark>          | Float        | Discount Fee                          |
| delivery\_fee<mark style="color:red;">\*</mark>          | Float        | Delivery Fee                          |
| currency<mark style="color:red;">\*</mark>               | String       | Currency code (KES)                   |
| total<mark style="color:red;">\*</mark>                  | Float        | Total Amount to be paid               |
| callback\_details<mark style="color:red;">\*</mark>      | Object       | Callback Object                       |
| transaction\_reference<mark style="color:red;">\*</mark> | String       | Unique reference                      |
| callback\_url<mark style="color:red;">\*</mark>          | String       | Your callback URL                     |
| success\_url<mark style="color:red;">\*</mark>           | String       | Url to redirect on successful payment |
| failed\_url<mark style="color:red;">\*</mark>            | String       | Url to redirect on failed payment     |

{% tabs %}
{% tab title="200 Payment Initiated Successfully" %}

```json
{
    "message": "Successful",
    "success": true,
    "status": 200,
    "transaction_reference": "1234",
    "chpter_transaction_ref": "p-2RbNdXIKxfXC6SydcHe7Q8Lq7CF",
    "checkout_url": "https://checkout.paystack.com/cjdjfd****"
}
```

{% endtab %}

{% tab title="401 Unauthorized" %}

```json
{
    "message": "unauthorized",
    "success": false,
    "status": 401
}
```

{% endtab %}

{% tab title="500: Internal Server Error Failed request" %}

```json
{
    "message": "processing transaction error. please contact support@chpter.co",
    "success": false,
    "status": 500
}
```

{% endtab %}

{% tab title="400: Bad Request Bad request payload" %}

```json
{
    "message": "payload validation error. ",
    "success": false,
    "status": 400
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Good to know:** This API uses webhooks to notify you of the payment status through the callback url. \
The user will be redirected to the passed success url on successful payment and to the failed url on failed payment.
{% endhint %}

#### Quick view

Sample body and the respective response code.

{% tabs %}
{% tab title="Body" %}

```json
{
  "customer_details": {
   "full_name": "Albert Chela",
    "location": "Nairobi",
    "phone_number": "254700123123",
    "email": "alber@chpter.co"
  },
  "products": [
    {
      "product_name": "HoodEez",
      "quantity": 1,
      "unit_price": 1,
      "digital_link": "https://example.com/link"
    }
  ],
  "amount": {
    "currency": "KES",
    "delivery_fee": 0.00,
    "discount_fee": 0.00,
    "total": 100.00
  },
  "callback_details": {
    "transaction_reference": "1234",
    "success_url": "https://chpter.shop",
    "failed_url": "https://chpter.shop",
    "callback_url": "https://eozdpom307nca3.m.pipedream.net"
  }
}
```

{% endtab %}

{% tab title="200 Response" %}

```json
{
    "message": "Successful",
    "success": true,
    "status": 200,
    "transaction_reference": "1234",
    "chpter_transaction_ref": "p-2RbNdXIKxfXC6SydcHe7Q8Lq7CF",
    "checkout_url": "https://checkout.paystack.com/cjdjfd****"
}
```

{% endtab %}

{% tab title="400 Response" %}

```json
{
    "message": "payload validation error. ",
    "success": false,
    "status": 400
}
```

{% endtab %}

{% tab title="401 Response" %}

```json
{
    "message": "unauthorized",
    "success": false,
    "status": 401
}
```

{% endtab %}

{% tab title="500 Response" %}

```json
{
    "message": "processing transaction error. please contact support@chpter.co",
    "success": false,
    "status": 500
}
```

{% endtab %}
{% endtabs %}

## Webhook / Callback Responses

{% hint style="info" %}
**Good to know**: Use the **Success key** value on the response to check if the payment is successful or not.
{% endhint %}

Here are sample webhook/callback responses.

{% tabs %}
{% tab title="Successful Response" %}

```json
{
    "Message":"Successful",
    "Success": true,
    "Status": 200,
    "Amount": 100,
    "transaction_code": "fXC6SydcHe7Q8Lq7CF",
    "transaction_reference": "12345678901345644",
    
}
```

{% endtab %}

{% tab title="Failed Response" %}

```json
{
    "Message":"Invalid card credentials",
    "Success": false,
    "Status": 200,
    "transaction_reference":"12345678901345644"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://chpter.gitbook.io/chpter-3.0-public-api-reference/api-reference/payments/card-payments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.