Collection/Purchase

Step 1 - Initiate

This API method is utilized to trigger a collection/purchase request, resulting in a JSON response being returned to you.

POST {base url}/api/v1/purchases/

Headers

Name	Type	Description
Authorization*		Bearer {{secret key}}
Content-Type*	String	application/json

201: Created

Request

{
    "client": {
        "email": "[email protected]",
        "phone": "256751123456"
    },
    "purchase": {
        "currency": "UGX",
        "products": [
            {
                "name": "Example One",
                "price": "500"
            }
        ]
    },
    "reference": "Your unique transaction reference",
    "skip_capture": false,
    "brand_id": "{{BrandId}}",
    "payment_method_whitelist": ["airtel", "mtnmomo"],
}

Response

The transaction ID in JSON response is then used to execute request(Step 2) to initiate a PIN prompt on the Subscriber's mobile handset to be debited.

Step 2 - Execute

You have two methods to execute the transaction

• Redirect the customer to the {{checkout_url}} provided in the response from step 1 on the Paytota platform. Take note the following parameters should be added to your Initial JSON body on using this method success_redirect, failure_redirect After the payment is processed, the system will redirect the customer back to your website.

• Alternatively, you can initiate a PIN prompt on the subscriber handset by sending a form-data request through your backend system. Following a successful execution, you will receive asynchronous status update via webhook. The notification will have the status 'pending_execute'.

Using the transaction ID received in Step 1, this method is then queried by sending a form-data request to initiate a PIN prompt on the subscriber handset.

POST {base url}/p/{id}/

Headers

Name	Type	Description
Content-Type*	String	multipart/form-data

Request Body

Name	Type	Description
Phone*	String	256751123456
pm*	String	Should be airtel or mtnmomo

200: OK

You will receive a callback on your webhook URL regarding the status of the transaction

Successful transaction  (status = paid)
Failed transaction (status = error)

Callback Example

{
  "id": "00fddd1a-6a30-4081-946b-c5d99f363ff3",
  "due": 1669138257,
  "type": "purchase",
  "client": {
    "cc": [],
    "bcc": [],
    "city": "",
    "email": "[email protected]",
    "phone": "256700123123",
    "state": "",
    "country": "",
    "zip_code": "",
    "bank_code": "",
    "full_name": "",
    "brand_name": "",
    "legal_name": "",
    "tax_number": "",
    "client_type": null,
    "bank_account": "",
    "personal_code": "",
    "shipping_city": "",
    "shipping_state": "",
    "street_address": "",
    "delivery_methods": [
      {
        "method": "email",
        "options": {}
      },
      {
        "method": "text_message",
        "options": {
          "custom_message": ""
        }
      }
    ],
    "shipping_country": "",
    "shipping_zip_code": "",
    "registration_number": "",
    "shipping_street_address": ""
  },
  "issued": "2022-11-22",
  "status": "paid",
  "is_test": false,
  "payment": {
    "amount": 500,
    "paid_on": 1669134668,
    "currency": "UGX",
    "fee_amount": 15,
    "net_amount": 485,
    "description": "",
    "is_outgoing": false,
    "payment_type": "purchase",
    "pending_amount": 0,
    "remote_paid_on": 1669134668,
    "owned_bank_code": null,
    "owned_bank_account": null,
    "pending_unfreeze_on": null,
    "owned_bank_account_id": null
  },
  "product": "purchases",
  "user_id": null,
  "brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
  "order_id": null,
  "platform": "api",
  "purchase": {
    "debt": 0,
    "notes": "",
    "total": 500,
    "currency": "UGX",
    "language": "en",
    "products": [
      {
        "name": "PAYTOTA",
        "price": 500,
        "category": "",
        "discount": 0,
        "quantity": "1.0000",
        "tax_percent": "0.00"
      }
    ],
    "timezone": "UTC",
    "due_strict": false,
    "email_message": "",
    "total_override": null,
    "shipping_options": [],
    "subtotal_override": null,
    "total_tax_override": null,
    "payment_method_details": {},
    "request_client_details": [],
    "total_discount_override": null
  },
  "client_id": null,
  "reference": "",
  "viewed_on": 1669134657,
  "company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
  "created_on": 1669134657,
  "event_type": "purchase.paid",
  "updated_on": 1669134667,
  "invoice_url": null,
  "checkout_url": "https://gate.paytota.com/p/00fddd1a-6a30-4081-946b-c5d99f363ff3/invoice/",
  "send_receipt": false,
  "skip_capture": false,
  "creator_agent": "",
  "issuer_details": {
    "website": "https://paytota.com",
    "brand_name": "PAYTOTA",
    "legal_city": "Kamplaa",
    "legal_name": "PAYTOTA",
    "tax_number": "",
    "bank_accounts": [
      {
        "bank_code": "EQBLUGKAXXX",
        "bank_account": "1036201557307"
      }
    ],
    "legal_country": "UG",
    "legal_zip_code": "23235",
    "registration_number": "80020002500244",
    "legal_street_address": "Venture Labs, Plot 23 Binayomba Road, Bugolobi"
  },
  "marked_as_paid": false,
  "status_history": [
    {
      "status": "created",
      "timestamp": 1669134657
    },
    {
      "status": "viewed",
      "timestamp": 1669134657
    },
    {
      "status": "pending_execute",
      "timestamp": 1669134657
    },
    {
      "status": "paid",
      "timestamp": 1669134668
    }
  ],
  "cancel_redirect": "",
  "created_from_ip": "102.218.37.140",
  "direct_post_url": null,
  "force_recurring": false,
  "recurring_token": null,
  "failure_redirect": "",
  "success_callback": "",
  "success_redirect": "",
  "transaction_data": {
    "flow": "payform",
    "extra": {},
    "country": "",
    "attempts": [
      {
        "flow": "payform",
        "type": "execute",
        "error": null,
        "extra": {},
        "country": "",
        "client_ip": "",
        "fee_amount": 15,
        "successful": true,
        "payment_method": "airtel",
        "processing_time": 1669134668
      }
    ],
    "payment_method": "airtel"
  },
  "refundable_amount": 500,
  "is_recurring_token": false,
  "billing_template_id": null,
  "currency_conversion": null,
  "reference_generated": "PT121",
  "refund_availability": "none",
  "payment_method_whitelist": null
}

Check Collection/Purchase Status

This method is used to query the collections/purchases transaction status using the transaction ID. Please note that this API also requires authorization using the Secret Key.

GET {base url}/api/v1/purchases/{id}/

Headers

Name	Type	Description
Content-Type*	String	application/json
Authorization*	String	Bearer {{secret key}}

200: OK