# Checkout and Remittance

**Overview**

The **Remittance and Checkout** feature provides users with the ability to create branded, customizable payment links that can be shared publicly to receive money. The checkout links allow payments for various purposes, including donations, e-commerce, fundraisers, pledges, or other financial needs.

Key Features:

1. **Pledge Support:**
   * The amount can be a fixed value or determined by the public user (e.g., donations).
2. **User Information:**
   * Public users can optionally provide their **name** and **phone number** during payment, depending on app preferences.
3. **Branding:**
   * Checkout links can include a title, description, logo, and website link for branding purposes.
   * By default, the logo will use the company’s logo or a default image if not specified.
4. **Transaction Costs:**
   * Each payment automatically calculates and applies applicable transaction costs. These costs are recorded separately and linked to the primary transaction for accurate reconciliation.
5. **Integration:**
   * Supports payments via Visa/MasterCard, M-Pesa (with STK Push), PayPal, and other channels.
6. **Real-Time Completion:**
   * The payment completes in real-time, and the payer sees a confirmation page with payment details.
   * For M-Pesa, the public user receives an STK push on their phone to complete the transaction.
7. **Transaction Mapping:**
   * Payment references and transaction costs are mapped to the **checkout ID** for traceability.

The checkout is hosted on Tuku Pay’s website: [**https://tuku.money**](https://tuku.money).

***

**Endpoint: Create a Checkout Link**

* **Method:** `POST`
* **URL:** `/api/checkout/create`

**Request Body:**

```json
{
  "appId": "app123",
  "userId": "user123",
  "purpose": "Church offering",
  "pledgeAllowed": true,
  "fixedAmount": false,
  "amount": 1000,
  "metadata": {
    "referenceId": "OFFERING2023",
    "additionalInfo": "Sunday service offering"
  },
  "branding": {
    "title": "Support Our Ministry",
    "description": "Help us with Sunday offerings to build our community.",
    "logoUrl": "https://example.com/logo.png",
    "websiteLink": "https://examplechurch.com"
  }
}
```

**Request Body Fields:**

| **Field**              | **Type**  | **Required** | **Description**                                                   |
| ---------------------- | --------- | ------------ | ----------------------------------------------------------------- |
| `appId`                | `string`  | Yes          | The app ID associated with the checkout.                          |
| `userId`               | `string`  | Yes          | The user ID for whom the checkout link is created.                |
| `purpose`              | `string`  | Yes          | The purpose of the checkout link (e.g., fundraiser, product).     |
| `pledgeAllowed`        | `boolean` | Yes          | Indicates if users can specify their own amount.                  |
| `fixedAmount`          | `boolean` | Yes          | If `true`, the amount is fixed; if `false`, it's user-determined. |
| `amount`               | `number`  | No           | The amount for the transaction (optional if pledgeAllowed=true).  |
| `metadata`             | `object`  | No           | Additional information about the link, such as a reference ID.    |
| `branding`             | `object`  | No           | Custom branding options for the checkout link.                    |
| `branding.title`       | `string`  | No           | The title displayed on the checkout page.                         |
| `branding.description` | `string`  | No           | The description displayed on the checkout page.                   |
| `branding.logoUrl`     | `string`  | No           | The logo URL to display; defaults to the app's logo if null.      |
| `branding.websiteLink` | `string`  | No           | A website link displayed on the checkout page.                    |

***

**Endpoint: Record a Payment via Checkout**

* **Method:** `POST`
* **URL:** `/api/checkout/payment`

**Request Body:**

```json
{
  "checkoutId": "OFFERING2023",
  "payerDetails": {
    "name": "John Doe",
    "phoneNumber": "+254700123456"
  },
  "amountPaid": 500,
  "transactionChannel": "mpesa",
  "transactionReference": "MPESA12345",
  "transactionCost": {
    "amount": 10,
    "type": "mpesa",
    "parentTransactionId": "TXN12345"
  },
  "timestamp": "2024-12-12T10:00:00Z"
}
```

**Request Body Fields:**

| **Field**                             | **Type** | **Required** | **Description**                                       |
| ------------------------------------- | -------- | ------------ | ----------------------------------------------------- |
| `checkoutId`                          | `string` | Yes          | The unique ID of the checkout.                        |
| `payerDetails`                        | `object` | No           | Details of the payer (optional).                      |
| `payerDetails.name`                   | `string` | No           | The name of the payer.                                |
| `payerDetails.phoneNumber`            | `string` | No           | The phone number of the payer.                        |
| `amountPaid`                          | `number` | Yes          | The amount paid by the payer.                         |
| `transactionChannel`                  | `string` | Yes          | The channel used (e.g., mpesa, paypal).               |
| `transactionReference`                | `string` | Yes          | The reference for the payment.                        |
| `transactionCost`                     | `object` | Yes          | Details of the associated transaction cost.           |
| `transactionCost.amount`              | `number` | Yes          | The amount of the transaction cost.                   |
| `transactionCost.type`                | `string` | Yes          | The type of the cost (e.g., mpesa).                   |
| `transactionCost.parentTransactionId` | `string` | Yes          | Links the transaction cost to the parent transaction. |
| `timestamp`                           | `string` | Yes          | The date and time of the transaction.                 |

***

**Transaction Costs**

* Each transaction cost is treated as a separate record, linked to the parent transaction for reconciliation purposes.
* Costs are calculated based on predefined rates and stored with the following fields:

  | **Field**             | **Description**                            |
  | --------------------- | ------------------------------------------ |
  | `amount`              | The cost of the transaction.               |
  | `type`                | The cost type (e.g., mpesa, paypal).       |
  | `parentTransactionId` | The ID of the related primary transaction. |


---

# 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://tuku-pay.gitbook.io/tuku-pay-internal-docs/transactions/checkout-and-remittance.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.