# 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.

<mark style="color:green;">`POST`</mark> `{base url}/api/v1/purchases/`

#### Headers

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| Authorization<mark style="color:red;">\*</mark> |        | Bearer **`{{secret key}}`** |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json            |

{% tabs %}
{% tab title="201: Created " %}

{% endtab %}
{% endtabs %}

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

```json5
{
    "client": {
        "email": "example@gmail.com",
        "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"],
}
```

{% endtab %}

{% tab title="Response" %}

```json5
{
  "id": "5322be8e-af12-4afd-be2c-2a4bdd77c273",
  "due": 1669137983,
  "type": "purchase",
  "client": {
    "cc": [],
    "bcc": [],
    "city": "",
    "email": "test@xample.com",
    "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": "created",
  "is_test": false,
  "payment": 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": null,
  "company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
  "created_on": 1669134383,
  "event_type": "purchase.created",
  "updated_on": 1669134383,
  "invoice_url": null,
  "checkout_url": "https://payments.paytota.com/p/5322be8e-af12-4afd-be2c-2a4bdd77c273/",
  "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": 1669134383
    }
  ],
  "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": [],
    "payment_method": ""
  },
  "refundable_amount": 0,
  "is_recurring_token": false,
  "billing_template_id": null,
  "currency_conversion": null,
  "reference_generated": "PT119",
  "refund_availability": "none",
  "payment_method_whitelist": null
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

### Step 2 - Execute

### You have two methods to execute the transaction&#x20;

* 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.&#x20;

<mark style="color:green;">`POST`</mark> `{base url}/p/{id}/`

#### Headers

| Name                                           | Type   | Description         |
| ---------------------------------------------- | ------ | ------------------- |
| Content-Type<mark style="color:red;">\*</mark> | String | multipart/form-data |

#### Request Body

| Name                                    | Type   | Description                 |
| --------------------------------------- | ------ | --------------------------- |
| Phone<mark style="color:red;">\*</mark> | String | 256751123456                |
| pm<mark style="color:red;">\*</mark>    | String | Should be airtel or mtnmomo |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}

{% hint style="info" %}
You will receive a callback on your webhook URL regarding the status of the transaction

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

{% endhint %}

<details>

<summary>Callback Example</summary>

```json5
{
  "id": "00fddd1a-6a30-4081-946b-c5d99f363ff3",
  "due": 1669138257,
  "type": "purchase",
  "client": {
    "cc": [],
    "bcc": [],
    "city": "",
    "email": "test@example.com",
    "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
}

```

</details>

### 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.

<mark style="color:blue;">`GET`</mark> `{base url}/api/v1/purchases/{id}/`

#### Headers

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json            |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer **`{{secret key}}`** |

{% tabs %}
{% tab title="200: OK " %}

{% 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://docs.paytota.com/payments/mobile-money/collection-purchase.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.