> For the complete documentation index, see [llms.txt](https://docs.paytota.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.paytota.com/payments/cards-1/card-collection.md).

# 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 %}