Card Collection

Initiate

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

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

Headers

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

201: Created

Payload

{
"client": {
    "email": "[e-mail]",
    "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}}",
}

Response

{
  "client": {
    "client_type": null,
    "email": "[e-mail]",
    "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"
}

Curl

curl --location --globoff '{{base_url}}/api/v1/purchases/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{Secret Key}}' \
--data-raw '{
"client": {
    "email": "[e-mail]",
    "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}}"
}'

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": "[e-mail]",
    "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;

NodeJs

const axios = require('axios');
let data = JSON.stringify({
  "client": {
    "email": "[e-mail]",
    "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);
});

Python

import http.client
import json

conn = http.client.HTTPSConnection("{{base_url}}")
payload = json.dumps({
  "client": {
    "email": "[e-mail]",
    "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"))

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

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": "761196a9-6aa2-4afd-a59f-214ad6788e5e",
  "due": 1694609579,
  "type": "purchase",
  "client": {
    "cc": [],
    "bcc": [],
    "city": "London",
    "email": "[e-mail]",
    "phone": "[phone]",
    "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
}

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

201: Created