Checkout and Remittance

Allows generation of Checkout Links and International 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.

---

Endpoint: Create a Checkout Link

• Method: POST

• URL: /api/checkout/create

Request Body:

{
  "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:

{
  "checkoutId": "OFFERING2023",
  "payerDetails": {
    "name": "John Doe",
    "phoneNumber": "[phone]"
  },
  "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.