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": "+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.