# Card Collection

### Initiate

## This API method initiates a collection/purchase request and returns a JSON response.

<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="Payload" %}

```json5
{
"client": {
    "email": "example@gmail.com",
    "country": "AU",
    "city": "Lisbon",
    "street_address": "sixth street",
    "zip_code": "3425678",
    "state": "PT"
    },
"purchase": {
    "currency": "USD",
    "products": [{
        "name": "test",
        "price": 1000
    }]
    },
"skip_capture": false,
"brand_id": "{{Brand Id}}",
}
```

{% endtab %}

{% tab title="Response" %}

```json5
{
  "client": {
    "client_type": null,
    "email": "example@gmail.com",
    "phone": "0793457034",
    "full_name": "Example One",
    "personal_code": "123245",
    "legal_name": "",
    "brand_name": "",
    "registration_number": "",
    "tax_number": "",
    "bank_account": "",
    "bank_code": "234235",
    "street_address": "sixth street",
    "city": "Lisbon",
    "zip_code": "3425678",
    "country": "AU",
    "state": "PT",
    "shipping_street_address": "",
    "shipping_city": "",
    "shipping_zip_code": "",
    "shipping_country": "",
    "shipping_state": "",
    "cc": [],
    "bcc": [],
    "delivery_methods": [
      {
        "method": "email",
        "options": {}
      },
      {
        "method": "text_message",
        "options": {
          "custom_message": ""
        }
      }
    ]
  },
  "purchase": {
    "currency": "USD",
    "products": [
      {
        "name": "test",
        "price": 1000,
        "quantity": "1.0000",
        "discount": 0,
        "tax_percent": "0.00",
        "category": ""
      }
    ],
    "language": "en",
    "notes": "",
    "debt": 0,
    "subtotal_override": null,
    "total_tax_override": null,
    "total_discount_override": null,
    "total_override": null,
    "total": 1000,
    "request_client_details": [],
    "timezone": "UTC",
    "due_strict": false,
    "email_message": "",
    "shipping_options": [],
    "payment_method_details": {},
    "has_upsell_products": false
  },
  "payment": null,
  "issuer_details": {
    "brand_name": "PAYTOTA",
    "website": "https://paytota.com",
    "legal_name": "PAYTOTA",
    "registration_number": "80020002500244",
    "tax_number": "",
    "legal_street_address": "Venture Labs, Plot 23 Binayomba Road, Bugolobi",
    "legal_country": "UG",
    "legal_city": "Kamplaa",
    "legal_zip_code": "23235",
    "bank_accounts": [
      {
        "bank_account": "1036201557307",
        "bank_code": "EQBLUGKAXXX"
      }
    ]
  },
  "transaction_data": {
    "payment_method": "",
    "flow": "payform",
    "extra": {},
    "country": "",
    "attempts": []
  },
  "status": "created",
  "status_history": [
    {
      "status": "created",
      "timestamp": 1687258526
    }
  ],
  "viewed_on": null,
  "force_recurring": false,
  "company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
  "is_test": false,
  "user_id": null,
  "brand_id": "edd6c020-eac6-4b4e-9716-47928f3401d1",
  "billing_template_id": null,
  "order_id": null,
  "client_id": "dfb1fb80-0322-4daa-900f-b0a39cda0450",
  "send_receipt": false,
  "is_recurring_token": false,
  "recurring_token": null,
  "skip_capture": false,
  "reference_generated": "PT213",
  "reference": "",
  "issued": "2023-06-20",
  "due": 1687262125,
  "refund_availability": "none",
  "refundable_amount": 0,
  "currency_conversion": null,
  "payment_method_whitelist": null,
  "success_redirect": "",
  "failure_redirect": "",
  "cancel_redirect": "",
  "success_callback": "",
  "marked_as_paid": false,
  "upsell_campaigns": [],
  "referral_campaign_id": null,
  "referral_code": null,
  "referral_code_details": null,
  "referral_code_generated": null,
  "retain_level_details": null,
  "can_retrieve": false,
  "can_chargeback": false,
  "creator_agent": "",
  "platform": "api",
  "product": "purchases",
  "created_from_ip": "102.218.37.140",
  "invoice_url": null,
  "checkout_url": "https://payments.paytota.com/p/9fd05d5c-6639-42f4-8189-a6f9e401988f/",
  "direct_post_url": null,
  "created_on": 1687258526,
  "updated_on": 1687258526,
  "type": "purchase",
  "id": "9fd05d5c-6639-42f4-8189-a6f9e401988f"
}
```

{% endtab %}

{% tab title="Curl" %}

```
curl --location --globoff '{{base_url}}/api/v1/purchases/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{Secret Key}}' \
--data-raw '{
"client": {
    "email": "example@gmail.com",
    "country": "AU",
    "city": "Lisbon",
    "street_address": "sixth street",
    "zip_code": "3425678",
    "state": "PT"
    },
"purchase": {
    "currency": "USD",
    "products": [{
        "name": "test",
        "price": 1000
    }]
    },
"skip_capture": false,
"brand_id": "{{Brand Id}}"
}'
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{{base_url}}/api/v1/purchases/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
"client": {
    "email": "example@gmail.com",
    "country": "AU",
    "city": "Lisbon",
    "street_address": "sixth street",
    "zip_code": "3425678",
    "state": "PT"
    },
"purchase": {
    "currency": "USD",
    "products": [{
        "name": "test",
        "price": 1000
    }]
    },
"skip_capture": false,
"brand_id": "{{Brand Id}}"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer {{Secret Key}}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

```

{% endtab %}

{% tab title="NodeJs" %}

```javascript
const axios = require('axios');
let data = JSON.stringify({
  "client": {
    "email": "example@gmail.com",
    "country": "AU",
    "city": "Lisbon",
    "street_address": "sixth street",
    "zip_code": "3425678",
    "state": "PT"
  },
  "purchase": {
    "currency": "USD",
    "products": [
      {
        "name": "test",
        "price": 1000
      }
    ]
  },
  "skip_capture": false,
  "brand_id": "{{Brand Id}}"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{{base_url}}/api/v1/purchases/',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{Secret Key}}'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

```

{% endtab %}

{% tab title="Python" %}

```python
import http.client
import json

conn = http.client.HTTPSConnection("{{base_url}}")
payload = json.dumps({
  "client": {
    "email": "example@gmail.com",
    "country": "AU",
    "city": "Lisbon",
    "street_address": "sixth street",
    "zip_code": "3425678",
    "state": "PT"
  },
  "purchase": {
    "currency": "USD",
    "products": [
      {
        "name": "test",
        "price": 1000
      }
    ]
  },
  "skip_capture": False,
  "brand_id": "{{Brand Id}}"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{Secret Key}}'
}
conn.request("POST", "/api/v1/purchases/", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```

{% endtab %}
{% endtabs %}

### You have two methods to collect card details from the customer .

1. Redirect the customer to the **{{checkout\_url}}** on the paytota platform.
2. Direct Post.\
   Here you submit the customer card details from your application to the **{{checkout\_url}}** . In this case the customer will be redirected to the bank authorization page immediately.\
   \
   Take note the following parameters should be added to your Initial JSON body on using Direct Post **`success_redirect`**, **`failure_redirect`**\
   After the payment is processed, the system will redirect the customer back to your website.

* ```
   <!DOCTYPE html>
  <html>
     <head>
        <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8">
     </head>
     <body>
        <form id="form" action="{{checkout_url}}" method="POST">
           <input type="hidden" name="cardholder_name" value="Asiman Gasanov">
              <input type="hidden" name="card_number" value="4444 3333 2222 1111">
              <input type="hidden" name="expires" value="11/25">
              <input type="hidden" name="cvc" value="123">
              <input type="hidden" name="remember_card" value="true">
              <noscript>
              <input type="submit" name="continue" value="Continue">
              </noscript>
        </form>
     </body>
  </html>
  ```

### Testing Integration

It’s possible to test-drive all checkouts using a test Purchase.\
\
\- 4444 3333 2222 1111 - non-3D Secure card\
\- 5555 5555 5555 4444 - 3D Secure card\
\
For both cards, please use:\
\
\- any cardholder name\
\- any expiry larger or equal to the current month/year\
\- CVC = 123\
\
For a failed payment, please change the CVC or expiration date

{% 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": "761196a9-6aa2-4afd-a59f-214ad6788e5e",
  "due": 1694609579,
  "type": "purchase",
  "client": {
    "cc": [],
    "bcc": [],
    "city": "London",
    "email": "johndeo@outlook.com",
    "phone": "+447702700000",
    "state": "WA",
    "country": "US",
    "zip_code": "CT6 6HG",
    "bank_code": "",
    "full_name": "John Deo",
    "brand_name": "",
    "legal_name": "",
    "tax_number": "",
    "client_type": null,
    "bank_account": "",
    "personal_code": "",
    "shipping_city": "",
    "shipping_state": "",
    "street_address": "39 coromant way",
    "delivery_methods": [
      {
        "method": "email",
        "options": {}
      },
      {
        "method": "text_message",
        "options": {
          "custom_message": ""
        }
      }
    ],
    "shipping_country": "",
    "shipping_zip_code": "",
    "registration_number": "",
    "shipping_street_address": ""
  },
  "issued": "2023-09-13",
  "status": "paid",
  "is_test": false,
  "payment": {
    "amount": 2300,
    "paid_on": 1694606029,
    "currency": "USD",
    "fee_amount": 150,
    "net_amount": 2150,
    "description": "",
    "is_outgoing": false,
    "payment_type": "purchase",
    "pending_amount": 0,
    "remote_paid_on": 1694606028,
    "owned_bank_code": null,
    "owned_bank_account": null,
    "pending_unfreeze_on": null,
    "owned_bank_account_id": null
  },
  "product": "purchases",
  "user_id": null,
  "brand_id": "869aca7c-6348-4c5f-9141-6f9e908da099",
  "order_id": null,
  "platform": "api",
  "purchase": {
    "debt": 0,
    "notes": "",
    "total": 2300,
    "currency": "USD",
    "language": "en",
    "products": [
      {
        "name": "deposit",
        "price": 2300,
        "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,
    "has_upsell_products": false,
    "payment_method_details": {},
    "request_client_details": [],
    "total_discount_override": null
  },
  "client_id": "70a626d4-b415-46b9-9dda-89e37ebdf1d4",
  "reference": "325408517",
  "viewed_on": null,
  "company_id": "177bde08-d0a3-47b0-9601-7fec23b8d4fb",
  "created_on": 1694605979,
  "event_type": "purchase.paid",
  "updated_on": 1694606029,
  "invoice_url": null,
  "can_retrieve": true,
  "checkout_url": "https://gate.paytota.com/p/761196a9-6aa2-4afd-a59f-214ad6788e5e/invoice/",
  "send_receipt": false,
  "skip_capture": false,
  "creator_agent": "",
  "referral_code": null,
  "can_chargeback": true,
  "issuer_details": {
    "website": "",
    "brand_name": "PAYTOTA LIMITED",
    "legal_city": "Kampala",
    "legal_name": "PAYTOTA LIMITED",
    "tax_number": "",
    "bank_accounts": [
      {
        "bank_code": "Will send",
        "bank_account": "Will send"
      }
    ],
    "legal_country": "UG",
    "legal_zip_code": "102145",
    "registration_number": "80020002500244",
    "legal_street_address": "Venture Labs, Plot 23 Binayomba Road, Bugolobi"
  },
  "marked_as_paid": false,
  "status_history": [
    {
      "status": "created",
      "timestamp": 1694605979
    },
    {
      "status": "pending_execute",
      "timestamp": 1694605986
    },
    {
      "status": "paid",
      "timestamp": 1694606029
    }
  ],
  "cancel_redirect": "https://example.com/1B7fCk992UZVAbWngU0j7-w",
  "created_from_ip": "85.208.60.10",
  "direct_post_url": null,
  "force_recurring": false,
  "recurring_token": null,
  "failure_redirect": "https://example.com/1jkfljS8Uxa-dNEGkPHLbsQ",
  "success_callback": "https://example.com/0bCCbefX4Bi-4JXjpgB5Qpw",
  "success_redirect": "https://example.com/1ulvVG6sAKQEUkDvKDRBX6w",
  "transaction_data": {
    "flow": "direct_post",
    "extra": {
      "card_type": "debit",
      "card_brand": "mastercard",
      "masked_pan": "537410******0294",
      "card_issuer": "national westminster bank plc",
      "expiry_year": 26,
      "expiry_month": 12,
      "cardholder_name": "Ryan lee",
      "card_issuer_country": "GB"
    },
    "country": "GB",
    "attempts": [
      {
        "flow": "direct_post",
        "type": "execute",
        "error": null,
        "extra": {
          "card_type": "debit",
          "card_brand": "mastercard",
          "masked_pan": "537410******0294",
          "card_issuer": "national westminster bank plc",
          "expiry_year": 26,
          "expiry_month": 12,
          "cardholder_name": "Jon Deo",
          "card_issuer_country": "GB"
        },
        "country": "GB",
        "client_ip": "84.70.164.234",
        "fee_amount": 150,
        "successful": true,
        "payment_method": "mastercard",
        "processing_time": 1694606028
      }
    ],
    "payment_method": "mastercard"
  },
  "upsell_campaigns": [],
  "refundable_amount": 2300,
  "is_recurring_token": false,
  "billing_template_id": null,
  "currency_conversion": null,
  "reference_generated": "PT159",
  "refund_availability": "all",
  "referral_campaign_id": null,
  "retain_level_details": null,
  "referral_code_details": null,
  "referral_code_generated": null,
  "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="201: Created " %}

{% 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/cards-1/card-collection.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.